Direct answer
Both files bring repository conventions into coding sessions, but their loading and configuration rules differ. Effective instruction files are concise and actionable, with test commands and boundaries expressed as verifiable rules.
What this guide helps you solve
Help teams maintain both coding-agent instruction files without duplication or rule drift.
Shared goal: turn team agreements into repository context
Both files can record conventions that maintainers expect an agent to follow across tasks, such as repository structure, build commands, test entry points, coding style and protected areas. They should neither duplicate the entire README nor contain credentials.
A rule is worth recording when it recurs across tasks and can be verified through commands, paths or review evidence. One-time requirements belong in the current prompt.
AGENTS.md focuses on hierarchical repository conventions
Codex discovers AGENTS.md files according to the working directory and repository hierarchy. The root file holds repository-wide conventions; subdirectory files hold language-, service- or package-specific rules. State the directory from which each command runs, and do not repeat every parent rule in deeper files.
For a monorepo, you can keep common security and commit rules in the root file, and place individual build and test requirements in the frontend, backend, or infrastructure directories.
CLAUDE.md combines project memory with imports
Claude Code supports multiple CLAUDE.md scopes and can organize larger instruction sets through imports. Keep team content separate from personal preferences: repository files belong in version control, while local and user-level files remain machine-specific.
Importing reduces duplication, but also increases dependency chains. Each imported file should have a clear owner and be verified when the directory is adjusted to avoid silent failures.
Repository layout for supporting both tools
Let both entry-point files reference a shared source of truth instead of maintaining two identical long documents. The README or docs/engineering.md holds stable engineering documentation; AGENTS.md and CLAUDE.md retain only the rules and references required by their respective loading mechanisms.
repository/
├── AGENTS.md
├── CLAUDE.md
├── docs/
│ └── engineering.md
├── frontend/
│ └── AGENTS.md
└── backend/
└── AGENTS.md
A maintainable instruction checklist
Write commands and boundaries before style preferences. A vague rule such as "maintain high quality" is not actionable, while "run pnpm typecheck before modification and pnpm build after modification" can be followed and verified.
- Repository purpose and key directories in one short paragraph.
- Installation, development, type checking, testing and build commands.
- Files that may be modified and files that must not be touched.
- Decision points requiring approval, such as dependency, database and deployment changes.
- Verification results and residual risks required in the final response.
Incorporate directive files into code reviews
Review instruction changes that affect builds, permissions or releases with the same care as code. At least quarterly, verify that commands still exist and run critical commands in CI so the documentation cannot drift away from the actual scripts.
When an agent frequently violates a rule, first check whether the rule conflicts, whether the location is correct, and whether the description is enforceable; don't just solve it by appending longer text.
Official sources and verification scope
This guide is based on public official documentation. Commands and configuration may change between client versions, so verify the linked sources before use.
Read the verification methodology