Project Rule Documents
Design AGENTS.md, CLAUDE.md, and path-scoped rules without conflicts or drift.
Key takeaways
- Rule files are a control surface, not a knowledge base: keep always-needed rules short and move long procedures to Skills, runbooks, or deeper docs.
- The surface is layered across
AGENTS.md,CLAUDE.md/CLAUDE.local.md,.claude/rules/*.md, and CodexAGENTS.override.md, each with a distinct target and location. - Codex builds its instruction chain from global down to working directory, with
AGENTS.override.mdwinning overAGENTS.md, closer files overriding earlier ones, and a 32 KiB default cap (project_doc_max_bytes). - If
AGENTS.mdis the shared source, keepCLAUDE.mdthin (import via@AGENTS.md) and use.claude/rules/for path-scoped rules. - Avoid failure patterns like subjective rules ("write clean code"), commands buried in prose, conflicting global/local rules, and copy-paste drift between
AGENTS.mdandCLAUDE.md.
When an agent enters a project, it first needs to know how work is done in that repository. Project rule documents provide that entry context.
The surface is now layered:
- shared agent instructions:
AGENTS.md - Claude Code memory and instructions:
CLAUDE.md,CLAUDE.local.md - Claude Code path-scoped rules:
.claude/rules/*.md - Codex directory instructions and overrides:
AGENTS.md,AGENTS.override.md - compatibility files:
.cursorrules,.windsurfrules
Core Rule
Rule files are a control surface, not a knowledge base. Keep always-needed project rules short, and move long procedures to Skills, runbooks, or deeper docs.
Surface Comparison
| Surface | Target | Location | Use |
|---|---|---|---|
AGENTS.md | Codex and shared agents | repo root, nested dirs | common instructions |
AGENTS.override.md | Codex | home, repo, subdirs | temporary or local override |
CLAUDE.md | Claude Code | repo root, subdirs, home | memory and instructions |
CLAUDE.local.md | Claude Code | local repo | personal settings, gitignored |
.claude/rules/*.md | Claude Code | repo .claude/rules/ | path-scoped rules |
.cursorrules | Cursor | repo root | legacy compatibility |
.windsurfrules | Windsurf | repo root | legacy compatibility |
Codex AGENTS.md Loading
Codex builds an instruction chain at startup:
- Global scope:
~/.codex/AGENTS.override.mdif present, otherwise~/.codex/AGENTS.md. - Project scope: from project root down to the current working directory.
- In each directory,
AGENTS.override.mdwins overAGENTS.md. - Files closer to the working directory appear later and override earlier guidance.
- Empty files are skipped, and the combined project instruction size is capped by
project_doc_max_bytes(32 KiB by default).
repo/
├── AGENTS.md
├── apps/
│ └── web/
│ └── AGENTS.md
└── services/
└── payments/
└── AGENTS.override.mdAGENTS.md Template
# AGENTS.md
## Project
[One-line project description.]
## Commands
\`\`\`bash
[install]
[dev]
[typecheck]
[test]
[build]
\`\`\`
## Where to look
| Task | Location | Notes |
|---|---|---|
| [task] | [path] | [notes] |
## Conventions
- [project-specific rule]
## Validation
- [command to run after changes]
## Do not
- [explicit prohibition]Claude Code Rules
If AGENTS.md is the shared source, keep CLAUDE.md thin.
# CLAUDE.md
@AGENTS.md
## Claude Code
- Prefer planning before broad edits.
- Do not commit or push unless the user asks.Use .claude/rules/ for path-scoped rules.
---
paths:
- "src/api/**/*.ts"
- "app/api/**/*.ts"
---
# API Rules
- Validate all inputs with schema.
- Update OpenAPI when API behavior changes.
- Run `pnpm openapi:check` after changes.What Goes Where
| Content | Surface | Reason |
|---|---|---|
| Overview, commands, validation, prohibitions | AGENTS.md | shared startup context |
| Claude-specific preferences | CLAUDE.md | tool-specific memory |
| file-type or path rules | .claude/rules/, nested AGENTS.md | avoid global bloat |
| repeatable workflow | Skill | loaded only when needed |
| long API/domain reference | docs, OpenAPI, MCP Resource | avoid startup context waste |
| personal secrets or local URLs | local config or CLAUDE.local.md | do not commit |
Failure Patterns
| Mistake | Why it fails | Fix |
|---|---|---|
| "Write clean code" | Too subjective | State lint, naming, path rules |
| Commands in prose | Hard to execute | Use code blocks |
| Conflicting global/local rules | Last-loaded rule wins unexpectedly | Remove duplicates and state overrides |
Huge CLAUDE.md | Consumes startup context | Move procedures to Skills |
Copy-paste between AGENTS.md and CLAUDE.md | Drift | Import or link to the shared source |