June 24, 2026 / AI, Development

Use AGENTS.md, CLAUDE.md, Cursor Rules, and Prompt Logs to Keep AI Coding Bots in Context

Tags: agents.md, ai coding agents, claude.md, codex, cursor, developer workflow, prompt archive

Different AI coding tools look for different instruction files. If you use Codex, start with AGENTS.md. If you use Claude Code, start with CLAUDE.md. If you use Cursor, use .cursor/rules/ and optionally AGENTS.md.

They can technically live in the same repository, but most teams are not running all three at the same time. The clean setup is to pick the files for the tool you actually use, then share only the common project facts across tools.

Short Answer

Codex: use root AGENTS.md.
Claude Code: use root CLAUDE.md, or .claude/CLAUDE.md.
Cursor: use .cursor/rules/*.mdc, plus AGENTS.md if you want a shared agent instruction file.
Shared project notes: keep reusable context in .codex/, docs/ai-context/, or another project-owned folder and point each tool-specific file at it.
Prompt history: keep a simple prompt counter and prompt CSV when you want an easy record of how the session started and what was asked.

Why These Files Matter

Context is the information the AI coding tool has loaded into the current session. It does not automatically know your project layout, source folders, build commands, deployment rules, or prompt logging habit unless those details are made available.

Instruction files solve that problem. They give the tool a reliable starting point:

Which files to read first.
Which folder is the active app or site.
Which code is project-owned.
Which files are vendor or reference-only.
How to verify changes.
How to record prompts, decisions, and completed work.

These files are not magic enforcement. They are loaded as context. For mandatory blocking behavior, use hooks, tests, linters, CI, permissions, or review gates.

Tool Differences

Codex, Claude Code, and Cursor overlap, but their native context surfaces are different.

Codex

Use AGENTS.md.

Codex discovers instruction files by starting at the project root and walking down to the working directory. It checks for AGENTS.override.md, then AGENTS.md, then configured fallback names. Files closer to the current working directory are appended later, so more specific instructions can override broader ones.

Use Codex files for:

Repo startup instructions.
Project ownership boundaries.
Verification commands.
Prompt counter and prompt archive rules.
Nested overrides for subfolders or services.

Common Codex files:

[CODEX]  AGENTS.md
[CODEX]  AGENTS.override.md
[CODEX]  .codex/AGENT_PROJECT_NOTES.md
[CODEX]  .codex/AGENT_PREFERENCES.md
[CODEX]  .codex/AGENT_CODING_PREFERENCES.md
[CODEX]  .codex/AGENT_PROMPTS.md
[CODEX]  .codex/prompts/administrator.csv

Claude Code

Use CLAUDE.md.

Claude Code uses CLAUDE.md files for persistent instructions. A project file can live at ./CLAUDE.md or ./.claude/CLAUDE.md. Claude Code also supports CLAUDE.local.md for personal project notes and .claude/rules/ for modular or path-scoped rules.

That is separate from Claude Code's automatic memory. CLAUDE.md is the committed project instruction file. Claude's auto memory is local machine state, usually under a path like C:\Users\<you>\.claude\projects\<project>\memory\.

Use Claude files for:

Claude-specific project instructions.
Rules that Claude should read at session start.
Path-scoped rules for large projects.
Local personal instructions that should not be committed.
Imports from shared project notes.
Pointers to what belongs in Claude memory instead of committed docs.

Common Claude files:

[CLAUDE] CLAUDE.md
[CLAUDE] .claude/CLAUDE.md
[CLAUDE] CLAUDE.local.md
[CLAUDE] .claude/rules/api.md
[CLAUDE] .claude/rules/testing.md

Claude can also import shared files from CLAUDE.md with @path/to/file syntax. That is useful when you want Claude to read the same shared project notes that Codex reads.

Example:

# CLAUDE.md

@.codex/AGENT_PROJECT_NOTES.md
@.codex/AGENT_CODING_PREFERENCES.md

## Claude-specific notes

- Use `/memory` to inspect loaded Claude memory files.
- Keep Claude-only preferences in `CLAUDE.local.md`.

Claude Auto Memory and Transcripts

Claude Code can preserve context outside your repository:

C:\Users\<you>\.claude\projects\<project>\memory\
|-- MEMORY.md
|-- debugging.md
`-- api-conventions.md

Use that memory for machine-local working notes, recurring debugging facts, or things you explicitly ask Claude to remember. MEMORY.md acts as the index Claude can load at session start, while detailed topic files are read when needed.

Session summaries may also point to .jsonl transcript files. Those transcripts can help recover fine-grained conversation detail, but they should not be treated as the main project memory. If a fact matters for future sessions, save it deliberately in Claude memory or, better for team use, in a repo-owned file such as CLAUDE.md, AGENTS.md, .codex/AGENT_PROJECT_NOTES.md, or docs/ai-context.md.

Cursor

Use .cursor/rules/*.mdc.

Cursor has User Rules, Project Rules, Team Rules, and support for AGENTS.md. Project rules are stored in .cursor/rules/ and can be configured to always apply or to apply to specific file patterns.

Use Cursor files for:

Editor-agent behavior inside Cursor.
Project rules committed with the repo.
File-pattern-specific instructions.
Team rules managed outside one repo.
Shared AGENTS.md support when you want one cross-agent instruction file.

Common Cursor files:

[CURSOR] .cursor/rules/project-context.mdc
[CURSOR] .cursor/rules/api.mdc
[CURSOR] .cursor/rules/testing.mdc
[CURSOR] .cursor/rules/release-checklist.mdc
[SHARED] AGENTS.md

Example Cursor rule:

---
description: "Load this repository's project context before code or content work."
alwaysApply: true
---

# Project Context

Before non-trivial work:

1. Read `AGENTS.md`.
2. Read the active project-owned files listed by `AGENTS.md`.
3. Follow the prompt counter and prompt CSV archive rules.
4. Prefer project-owned source files over generated output, vendored dependencies, or third-party package code.
5. Verify changes with the repo's documented commands.

Labeled Directory Tree

Use a labeled tree so it is obvious which files belong to which tool. If your renderer supports colors, you can style these labels. If it only renders plain code blocks, the labels still make ownership clear.

Legend:

[SHARED]: useful across tools.
[CODEX]: Codex-specific.
[CLAUDE]: Claude Code-specific.
[CURSOR]: Cursor-specific.
[LOCAL]: personal machine-only file, usually ignored by git.

repo
|-- [SHARED] AGENTS.md
|-- [CLAUDE] CLAUDE.md
|-- [LOCAL]  CLAUDE.local.md
|-- [CODEX]  AGENTS.override.md
|-- [CODEX]  .codex
|   |-- [SHARED] AGENT_PROJECT_NOTES.md
|   |-- [SHARED] AGENT_CODING_PREFERENCES.md
|   |-- [SHARED] AGENT_TODO.md
|   |-- [SHARED] AGENT_CHANGELOG.md
|   |-- [CODEX]  AGENT_PROMPTS.md
|   |-- [SHARED] site_map.md
|   `-- [CODEX]  prompts
|       |-- [CODEX] README.md
|       `-- [CODEX] administrator.csv
|-- [CLAUDE] .claude
|   |-- [CLAUDE] CLAUDE.md
|   `-- [CLAUDE] rules
|       |-- [CLAUDE] api.md
|       `-- [CLAUDE] testing.md
`-- [CURSOR] .cursor
    `-- [CURSOR] rules
        |-- [CURSOR] project-context.mdc
        |-- [CURSOR] api.mdc
        `-- [CURSOR] testing.mdc

You do not need every file in that tree. Use the section that matches your tool.

If You Use Only Codex

Keep it simple:

repo
|-- AGENTS.md
`-- .codex
    |-- AGENT_PROJECT_NOTES.md
    |-- AGENT_CODING_PREFERENCES.md
    |-- AGENT_PROMPTS.md
    `-- prompts
        `-- administrator.csv

Root AGENTS.md should tell Codex exactly what to read:

# Agents

Required startup routine:

1. Read this file first for every new session.
2. Read `.codex/AGENT_PROJECT_NOTES.md`.
3. Read `.codex/AGENT_CODING_PREFERENCES.md`.
4. Increment `.codex/AGENT_PROMPTS.md` by 1 for each new user message.
5. Save every exact user prompt in `.codex/prompts/{username}.csv`.
6. Verify changes with the commands documented in this repo.

If You Use Only Claude Code

Use Claude's native file name:

repo
|-- CLAUDE.md
|-- CLAUDE.local.md
`-- .claude
    `-- rules
        |-- api.md
        `-- testing.md

Example CLAUDE.md:

# Claude Project Instructions

## Startup

1. Read this file at session start.
2. Read `docs/project-notes.md`.
3. Use `.claude/rules/` for path-specific instructions.
4. Keep generated output and vendored dependencies unchanged unless the task explicitly targets them.

## Verification

- Run the smallest useful test after code changes.
- Explain any test that could not be run.

## Memory and handoff

- Use `/memory` to inspect Claude's loaded files and auto memory.
- Save private, machine-local notes in Claude memory or `CLAUDE.local.md`.
- Save shared project facts in committed project docs.

If you already maintain AGENTS.md, you can import it from CLAUDE.md:

# Claude Project Instructions

@AGENTS.md

## Claude-only additions

- Use `/memory` to inspect what Claude loaded.
- Treat Claude auto memory as machine-local unless your team has explicitly decided otherwise.
- Keep personal machine notes in `CLAUDE.local.md`.

If You Use Only Cursor

Use Cursor project rules:

repo
`-- .cursor
    `-- rules
        |-- project-context.mdc
        |-- api.mdc
        `-- testing.mdc

Example .cursor/rules/project-context.mdc:

---
description: "Project context for the coding agent."
alwaysApply: true
---

# Project Context

- Read `docs/project-notes.md` before non-trivial code changes.
- Treat `src/` as project-owned application code.
- Treat `docs/` as project documentation.
- Treat generated output, vendored dependencies, and third-party package code as reference-only unless the task explicitly targets them.

If you want Cursor and Codex to share the same root instructions, add AGENTS.md too and have Cursor rules point to it.

If You Use More Than One Tool

You can keep multiple tool files in the same repo, but do not copy and paste 300 lines into each one. That causes drift. Put shared facts in one place, then have tool-specific files point to those facts.

Recommended mixed setup:

repo
|-- [SHARED] AGENTS.md
|-- [CLAUDE] CLAUDE.md
|-- [SHARED] docs
|   `-- [SHARED] ai-context.md
|-- [CODEX] .codex
|   |-- [SHARED] AGENT_PROJECT_NOTES.md
|   `-- [CODEX] AGENT_PROMPTS.md
|-- [CLAUDE] .claude
|   `-- [CLAUDE] rules
`-- [CURSOR] .cursor
    `-- [CURSOR] rules

Use this division as a practical starting point:

Put common project facts in AGENTS.md, .codex/AGENT_PROJECT_NOTES.md, or docs/ai-context.md.
Put Codex-specific prompt counting in .codex/AGENT_PROMPTS.md and .codex/prompts/.
Put Claude-specific imports, /memory notes, and Claude rules in CLAUDE.md and .claude/.
Put Claude auto memory in Claude's user-profile memory folder only when the note is machine-local or explicitly personal.
Put Cursor editor behavior in .cursor/rules/.

Prompt Count Example

A prompt-count file is useful because it shows whether the bot actually followed startup bookkeeping. If the count does not move after a new prompt, the bot probably skipped the repo rules.

Example .codex/AGENT_PROMPTS.md:

# Agent Prompts

114

The number is intentionally plain. It is easy to inspect in a diff and easy to update.

Prompt CSV Example

The CSV keeps the prompt history easy to review later. The example below uses fictional prompts so the format is clear without exposing a real conversation.

Example .codex/prompts/administrator.csv:

USERNAME,DATE,ENTRY
"administrator","2026-06-24 09:15:10 EST","read AGENTS.md and the .codex files before changing the API client"
"administrator","2026-06-24 09:03:44 EST","add validation tests for the import command and verify they pass"

Keep the newest prompts directly under the header. Quote CSV fields so commas, quotes, and line breaks remain valid.

Common Mistakes to Avoid

Assuming every tool reads every file name.
Using only CLAUDE.md when the team actually works in Codex.
Using only AGENTS.md when the team actually works in Claude Code and expects Claude memory.
Copying the same long instructions into Codex, Claude, and Cursor files, then letting them drift apart.
Including real prompt logs in screenshots, tutorials, or example files.
Assuming Claude's local memory folder or .jsonl transcripts are shared with other machines or teammates.
Treating context files like enforcement. Use hooks, tests, linters, CI, permissions, or review gates for that.

Practical Rule

Pick the native file for the tool you use:

Codex: AGENTS.md.
Claude Code: CLAUDE.md.
Cursor: .cursor/rules/*.mdc.

Then use shared project notes for durable facts that all tools should understand.

References

Post Views: 1,537