Chapter 1 · Practice 1 of 4
Add a project instruction file that the assistants you use will read
Why it matters
Most assistants read a Markdown file of project instructions at the start of every session. The common ones:
| File | Read by |
|---|---|
AGENTS.md | Many agents and editors, including OpenAI Codex, Cursor, Gemini CLI, Zed and GitHub Copilot's coding agent |
CLAUDE.md | Claude Code (it can import other files, such as AGENTS.md) |
.github/copilot-instructions.md | GitHub Copilot, repository-wide |
.github/instructions/NAME.instructions.md | GitHub Copilot, for paths matched by an applyTo glob |
If your team uses several tools, keep one source of truth, such as AGENTS.md, and point the others at it rather than maintaining copies that drift.
Check the file into git so the whole team shares and improves it. Claude Code's docs note that the file compounds in value over time.
Do
- Keep one main instruction file and reference it from tool-specific ones
Avoid
- Separate, diverging copies of the same rules for each tool