A new engineer joining a project reads the README, asks where the tests live and learns the team’s habits over a few weeks. A coding agent starts every session with none of that. An instruction file closes part of the gap. A typical one says: install with npm ci, run npm test before every commit, never edit generated files, use the existing logging helper, and open pull requests as drafts.
The file becomes part of the agent’s context at the start of a task, a little like a project-level system prompt. Because it lives in the repository, it is reviewed and versioned like code, and every developer’s agent gets the same instructions. Large repositories can nest files so each package carries its own rules.
The names vary by tool. AGENTS.md is read by several agents, including OpenAI Codex, Cursor and GitHub Copilot’s agents. Claude Code reads CLAUDE.md; Cursor also has its own rules directory; Copilot has a repository-wide instructions file. Many teams keep one source file and point the others at it, so the instructions don’t drift apart.
An instruction file is guidance, not enforcement. Agents can miss or misread it, especially when it is long or contradictory (see instruction adherence). Rules that must hold, such as “don’t push to main”, belong in permissions, sandboxing and CI checks as well. Keep the file short and specific, and move reusable procedures into agent skills that load only when needed. This is one of the simplest forms of context engineering.
Sources
- AGENTS.md — Describes AGENTS.md as an open format, a README for agents; nested files apply to subprojects, the nearest one taking precedence; now stewarded by the Agentic AI Foundation under the Linux Foundation; checked October 24, 2026.
- OpenAI Codex docs: Custom instructions with AGENTS.md — Documents how Codex reads AGENTS.md files for project instructions; checked October 24, 2026.
- Claude Code docs: How Claude remembers your project — Documents CLAUDE.md files, where to place them and how they load; checked October 24, 2026.
- Cursor docs: Rules — Lists project rules in .cursor/rules, user rules, team rules and AGENTS.md, and notes that rules give persistent context because models don't retain memory between completions; checked October 24, 2026.
- GitHub Docs: Adding repository custom instructions for GitHub Copilot — Covers .github/copilot-instructions.md and says Copilot agents use the nearest AGENTS.md, or a root CLAUDE.md or GEMINI.md; checked October 24, 2026.
