Project instructions
Customizing agents · topic customizing-agents/instructions
Project instructions are the standing brief an agent reads at the start of every session in a repository. This topic covers the instruction file and its conventions, which sections earn their place, how instructions layer in a monorepo, and the point where a rule needs a hook or a tool instead of a sentence.
Concepts
- AGENTS.md / CLAUDE.md
- The instruction file coding agents load automatically from a repository root. Several tools read a shared name and others read their own; a symlink lets one file serve both. It holds what the agent must know every session: commands, conventions, boundaries. It is not documentation for people and is read on every turn, so every line costs context. glossary
- Sections
- The recurring parts of a good instruction file: what the project is, how to build, test and lint, the layout of the code, the conventions to follow, the things never to do, and how to finish a piece of work. Each section answers a question the agent would otherwise guess at. Remove anything the agent can discover cheaply itself, and keep examples concrete. glossary
- Monorepo hierarchy
- In a repository with many packages, instruction files can sit at the root and inside subdirectories; the agent reads the ones on the path to the files it is working on. Root holds what is true everywhere, subdirectory files hold what differs. The hierarchy keeps each file short and lets teams own their own rules without conflicting. glossary
- When instructions are not enough
- Instructions are requests; a model follows them most of the time and forgets them as context fills. A rule that must hold every time, such as never committing secrets or always running the formatter, belongs in a hook or a permission setting that enforces it mechanically. A capability the agent lacks belongs in a tool or a skill, not in a longer paragraph. glossary
Links
- Builds on: nothing
- Leads to: Hooks, permissions, settings, Connecting tools with MCP, Agent skills
- Related: Context engineering for code
- Competencies drawing on it: Configures an agent for a project, Writes a reusable agent skill
Lessons
- Project instructions: AGENTS.md (tutorial)
Your reference
Each lesson above adds its takeaways and its example here once you finish it. Your reference lists every lesson you have finished.
Project instructions: AGENTS.md
Unlocks when you finish Project instructions: AGENTS.md.
Takeaways
- The agent reads
AGENTS.md(orCLAUDE.md; same content, different tool convention) at the start of every session; it is the briefing for a capable contractor's first morning. - Put in it what the agent can't read from the code: commands, structure, conventions, and one line for every mistake it keeps making.
- Leave out what the code already says, long prose, and rules that apply to every project on earth. Short files get followed; long ones get skimmed.
- In a monorepo, the root file holds what's shared and each project's file holds only what differs, and on conflict the closer file applies.
- A rule you can't afford to have skipped belongs in a hook rather than in prose, and a procedure the agent should repeat belongs in a skill.
Example
This lesson has no runnable example or prompt block.
Sources
AEC-15AGENTS.md: contents, monorepo hierarchies, with a builder widget, Agent Engineer Course (course)Academy claude-code-101Claude Code 101, Claude Academy (course)Academy claude-code-in-actionClaude Code in action, Claude Academy (course)