# Project 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.

Page: https://schubergphilis.github.io/ai-training/topics/customizing-agents/instructions/
License: CC BY-SA 4.0, https://creativecommons.org/licenses/by-sa/4.0/

*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](https://schubergphilis.github.io/ai-training/glossary/#agents-md-claude-md)
- **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](https://schubergphilis.github.io/ai-training/glossary/#sections)
- **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](https://schubergphilis.github.io/ai-training/glossary/#monorepo-hierarchy)
- **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](https://schubergphilis.github.io/ai-training/glossary/#when-instructions-are-not-enough)
- **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](https://schubergphilis.github.io/ai-training/glossary/#loading-versus-pointing)
- **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](https://schubergphilis.github.io/ai-training/glossary/#pruning-instructions)

## Links

- **Builds on:** nothing
- **Leads to:** [Hooks, permissions, settings](https://schubergphilis.github.io/ai-training/topics/customizing-agents/hooks-permissions/), [Connecting tools with MCP](https://schubergphilis.github.io/ai-training/topics/customizing-agents/mcp/), [Agent skills](https://schubergphilis.github.io/ai-training/topics/customizing-agents/skills/)
- **Related:** [Context engineering for code](https://schubergphilis.github.io/ai-training/topics/coding-with-agents/context/)
- **Competencies drawing on it:** [Adopts a published skill set without giving up control of the project](https://schubergphilis.github.io/ai-training/competencies/customizing-agents/adopts-a-skill-set/), [Configures an agent for a project](https://schubergphilis.github.io/ai-training/competencies/customizing-agents/configures-agent/), [Writes a reusable agent skill](https://schubergphilis.github.io/ai-training/competencies/customizing-agents/writes-skill/)

## Lessons

- [Project instructions: AGENTS.md](https://schubergphilis.github.io/ai-training/customizing-agents/instructions/) (tutorial)
- [Load it, point at it, or cut it](https://schubergphilis.github.io/ai-training/customizing-agents/load-point-prune/) (tutorial)

## Sources

- `AEC-15` [AGENTS.md: contents, monorepo hierarchies, with a builder widget](https://lsimons.github.io/agent-engineer-course/15-agents-md/), Agent Engineer Course (course)
- `Academy claude-code-101` [Claude Code 101](https://academy.claude.com/courses/claude-code-101), Claude Academy (course)
- `Academy claude-code-in-action` [Claude Code in action](https://academy.claude.com/courses/claude-code-in-action), Claude Academy (course)
- `Claude Code memory` [How Claude remembers your project](https://code.claude.com/docs/en/memory), Claude Code documentation (reference)
- `Claude Code best practices` [Best practices for Claude Code](https://code.claude.com/docs/en/best-practices), Claude Code documentation (reference)
- `Anthropic context engineering` [Effective context engineering for AI agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents), Anthropic Engineering (reference)