Chapter 1 of 6 · 4 practices · 3 min · 4-question quiz
Project instruction files
Assistants start every session knowing nothing about your project. A short, well-kept instruction file gives them the context they cannot infer from the code.
Start: Add a project instruction file that the assistants you use will read4 practices in this chapter
- 1Add a project instruction file that the assistants you use will readMost assistants read a Markdown file of project instructions at the start of every session. The common ones: If your team uses several tools, keep one source of truth, such as
AGENTS.md, and point… - 2Write only what the assistant cannot work out from the codeClaude Code's best practices give a clear test for every line: "Would removing this cause Claude to make mistakes?" If not, cut it.
- 3Keep the file short and prune it when rules get ignoredA long instruction file is not a thorough one. Claude Code's docs warn that bloated files cause the assistant to ignore your actual instructions, because important rules get lost in the noise.
- 4Use nested or path-specific instructions for different parts of a repoLarge repositories have parts with different rules: a frontend app, a data pipeline, infrastructure code. Put those rules where they apply.
Check yourself on this chapter
4 questions, right here once you are signed in. Your progress is saved as you read.