June 24, 2026 / AI, Development, WordPress

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 audit: keep a simple prompt counter and prompt CSV when you want to prove the bot followed startup context.

Why These Files Matter

Context is the information the AI has loaded into the current session. A bot does not automatically know your project layout, active WordPress theme, build commands, deployment rules, or prompt logging habit unless those details are loaded into context.

Instruction files solve that problem. They tell the bot:

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.

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.

Common Claude files:

[CLAUDE] CLAUDE.md
[CLAUDE] .claude/CLAUDE.md
[CLAUDE] CLAUDE.local.md
[CLAUDE] .claude/rules/frontend.md
[CLAUDE] .claude/rules/wordpress.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`.

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/wordpress.mdc
[CURSOR] .cursor/rules/frontend.mdc
[CURSOR] .cursor/rules/release-checklist.mdc
[SHARED] AGENTS.md

Example Cursor rule:

---
description: "Always 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 code over vendor, core, generated, or third-party files.
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] wordpress.md
|       `-- [CLAUDE] frontend.md
`-- [CURSOR] .cursor
    `-- [CURSOR] rules
        |-- [CURSOR] project-context.mdc
        |-- [CURSOR] wordpress.mdc
        `-- [CURSOR] frontend.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
        |-- wordpress.md
        `-- frontend.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 or vendor code unchanged unless the task explicitly targets it.

## Verification

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

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.
- Keep personal machine notes in `CLAUDE.local.md`.

If You Use Only Cursor

Use Cursor project rules:

repo
`-- .cursor
    `-- rules
        |-- project-context.mdc
        |-- wordpress.mdc
        `-- frontend.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 `public/` as the active WordPress install.
- Treat `public/wp-content/themes/example-theme/` as project-owned code.
- Treat WordPress core, third-party plugins, and vendor folders as reference-only.

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:

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 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 exact prompts for audit and handoff. Public examples should use sample prompts, not real private prompt text.

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 checkout page"
"administrator","2026-06-24 09:03:44 EST","add a Blog link to the primary menu and verify it appears after Home"

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

What Not to Do

Do not assume every tool reads every file name.
Do not use CLAUDE.md as the only file if the team actually uses Codex.
Do not use AGENTS.md as the only file if the team actually uses Claude Code and expects native Claude memory.
Do not duplicate long rules across Codex, Claude, and Cursor files.
Do not publish real prompt archive rows in public documentation.
Do not treat context files as hard enforcement. Use hooks, tests, and CI for enforcement.

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: 25