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
Loading versus pointing: Two ways to give an agent guidance. Loading puts the text in the instruction file, so it is in the context of every session whether the task needs it or not. Pointing puts one line there that says where the detail is, such as a file path or a skill, and the agent reads it when a task calls for it. Load what nearly every task needs and point at the rest. An import that pulls a file in at start-up still loads it. glossary
Pruning instructions: Removing the lines of an instruction file that no longer earn their place: a rule the agent already follows without being told, a fact it can work out from the code, a line that conflicts with another, a rule for a problem that has gone away. The test for each line is whether removing it would cause a mistake. Rules in a long file get ignored, so pruning makes the remaining rules work better. glossary

Lessons

Project instructions: AGENTS.md (tutorial)
Load it, point at it, or cut it (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.