Quick check
Guess first, no penalty. Your coding agent keeps running npm test, but your project uses pnpm, and it keeps editing a generated folder. What's the lasting fix?
A coding agent is an AI tool that reads your files, runs commands and makes changes for you, such as Claude Code. Each session starts with no memory of your project. A project instruction file fills that gap: a short file in the repository the agent reads first.
The file names differ by tool:
- AGENTS.md is, in its own site's words, "a simple, open format for guiding coding agents". The agents.md page lists tools that read it, including OpenAI Codex, Cursor and Gemini CLI.
- GitHub Copilot reads repository instructions from
.github/copilot-instructions.md, and also supports AGENTS.md, CLAUDE.md or GEMINI.md, per GitHub's docs. - Claude Code reads CLAUDE.md, and can read AGENTS.md instead.
Anthropic's Claude Code docs say the agent treats these files "as context, not enforced configuration", and that specific, concise instructions are followed more consistently. So keep it short, and back every hard rule with a real guard, like a CI check (the tests that run on every change).
What earns a line:
- Commands, exactly as typed: install, test, lint.
- Conventions: naming, where things live, the helpers to reuse.
- No-touch zones: generated code, merged migrations, secrets.