Repository instructions
Durable, version-controlled guidance that tells coding agents how a repository is organized, how to verify work, and which boundaries matter.
Use it when
- The same build, test, architecture, or safety guidance applies to most work in a repository.
- A monorepo needs narrower instructions near individual packages.
- Several agents need one shared source of project truth.
Choose another layer when
- A one-time task request that belongs in the current prompt.
- A hard enforcement requirement that should be implemented as a hook, policy, or CI check.
Production path
Build it in this order
- 01
Write the minimum shared truth
Document real commands, important paths, review expectations, and explicit boundaries. Prefer instructions that a reviewer can verify.
Quality check: A new contributor can use the file without guessing which commands or directories are current.
- 02
Scope instructions close to the work
Use nested files or path-scoped rules for package-specific guidance instead of growing one repository-wide prompt.
Quality check: Unrelated work does not receive package-specific context.
- 03
Audit for drift and conflicts
Review instruction files when commands, architecture, or agent behavior changes. Remove duplicated or contradictory rules.
Quality check: Every instruction still describes the repository and has one clear owner.
Artifacts you may see
- AGENTS.md
- CLAUDE.md
- .claude/rules/*.md
- .cursor/rules/*.mdc
Connected layers
Evidence ledger
Primary documentation behind this guide
Provider-specific behavior is sourced to that provider. Open standards are sourced to their specifications and official maintainers.
AGENTS.md specification and examples
AGENTS.md
The portable AGENTS.md format and repository instruction pattern.
Codex AGENTS.md guidance
OpenAI
Codex discovery, precedence, scope, and maintenance guidance.
How Claude remembers your project
Anthropic
CLAUDE.md locations, loading behavior, concise instruction guidance, and AGENTS.md interoperability.