AI agent files pillar guide
AI agent instruction files explained
AI coding agents read Markdown files to learn how your project works. This guide covers every common .md and rules file, what it does, and when to use it.
What are AI agent instruction files?
AI agent instruction files are Markdown documents that give AI coding tools persistent context about a project: how to build it, the coding style to follow, which files matter, and what not to touch. Tools load them automatically at the start of a session, so the assistant begins each task already knowing your rules instead of guessing from the surrounding code.
They are plain Markdown on purpose. Markdown is compact, token-efficient, version-controls cleanly in Git, and is readable by both people and models. That is why nearly every AI coding tool now standardizes on a Markdown instruction file.
Why these files exist
Large language models are powerful but stateless. Without context they re-derive your conventions every session and often get them wrong: the wrong test command, the wrong library, a style that does not match the codebase. Instruction files solve this by writing the project rules down once. The result is fewer hallucinations, fewer corrections, and code that fits your project on the first try. Studies of agent files report meaningfully fewer bugs and corrections when a clear file is present.
Every AI agent file at a glance
| File | Tool | Location | Purpose |
|---|---|---|---|
| README.md | Universal | Repo root | Explain the project to humans and give first context |
| AGENTS.md | Cross-agent | Repo root | Open format with build, test, and behavior rules for any agent |
| CLAUDE.md | Claude Code | Root or ~/.claude | Persistent project memory and workflow rules for Claude |
| GEMINI.md | Gemini CLI | Root or ~/.gemini | Hierarchical context for Google Gemini CLI |
| copilot-instructions.md | GitHub Copilot | .github/ | Repository-wide custom instructions for Copilot |
| Cursor rules (.mdc) | Cursor | .cursor/rules/ | Scoped, glob-targeted rules for the Cursor agent |
| Windsurf rules | Windsurf | Root / global | Global and workspace rules for the Cascade agent |
| CONVENTIONS.md | Aider, others | Repo root | Tool-neutral coding standards and library preferences |
| DESIGN.md | Universal | Repo root or docs/ | Design intent and architecture decisions behind the code |
| SKILL.md | Claude Agent Skills | Skill folder | Package a reusable capability the agent loads on demand |
| llms.txt | AI search engines | Site root | Site-level summary so AI models cite the right pages |
Projects also use supporting Markdown files that agents read for context, including CHANGELOG.md, CONTRIBUTING.md, TODO.md, PROMPTS.md, API.md, and SECURITY.md.
README.md: the human front door
README.md is the universal starting point. It explains what a project is and how to use it, and AI tools read it first for high-level context. Keep it focused on humans, then push operational detail into the agent files below.
AGENTS.md: the cross-agent standard
AGENTS.md is an open format that OpenAI introduced for Codex in 2025 and most major tools adopted. It holds setup commands, test rules, code style, and boundaries that agents need but that would clutter a README. If you only adopt one agent file, AGENTS.md gives the widest coverage.
Tool-specific memory and rules files
Each major tool also has its own file. CLAUDE.md is Claude Code's project memory. GEMINI.md is Gemini CLI's hierarchical context. copilot-instructions.md drives GitHub Copilot. Cursor rules use scoped `.mdc` files, and Windsurf rules guide the Cascade agent. They share a purpose: tell one tool exactly how to work in your project.
CONVENTIONS.md and DESIGN.md: standards and intent
CONVENTIONS.md documents coding standards and library preferences in a tool-neutral way. DESIGN.md records the reasoning and architecture behind the code, which helps agents make changes that match the product direction, not just local syntax.
llms.txt: instructions at the site level
llms.txt extends the idea from repositories to whole websites. It is a root-level Markdown file that tells AI search engines what a site is about and which pages to reference, supporting AEO and GEO. See also our roundup of common .md files for AI projects.
Which files should you use?
Start small and add as needed:
- Always: a clear README.md.
- For any agent: add AGENTS.md for build, test, and behavior rules.
- Per tool: add the file your team uses (CLAUDE.md, GEMINI.md, Cursor rules, copilot-instructions.md, or Windsurf rules).
- For standards: add CONVENTIONS.md; for big decisions, add DESIGN.md.
- For your website: publish llms.txt.
You do not need every file. Use the ones that match your tools and your project.
Best practices for agent files
- Be concrete: give exact commands, not vague guidance.
- Keep them short and scannable, and split large rule sets into scoped files.
- Commit them to Git so the whole team gets the same behavior.
- Keep them current; an outdated instruction file is worse than none.
- Avoid duplication: shared rules in AGENTS.md, tool-only tweaks in the tool file.
Write and preview your agent files
Every file here is Markdown, so you can draft and preview them in one place. Use the Markdown Docs online editor for a quick live preview, or download Markdown Docs to open and edit `.md` files directly on Windows with autosave and a full toolbar.
Related references
- AGENTS.md open format the cross-agent standard.
- Anthropic Claude Code memory docs for CLAUDE.md.
- Gemini CLI GEMINI.md docs for GEMINI.md.
- GitHub Copilot custom instructions for copilot-instructions.md.
FAQ
What is an AI agent instruction file?
It is a Markdown file that gives an AI coding tool persistent project context, such as build commands, code style, and boundaries, loaded automatically each session.
Do I need all of these files?
No. Start with README.md, add AGENTS.md for broad agent support, then add the tool-specific file your team uses. Add others only when the project needs them.
What is the difference between AGENTS.md and CLAUDE.md?
AGENTS.md is a cross-agent open format read by many tools. CLAUDE.md is specific to Claude Code. Teams often keep shared rules in AGENTS.md and Claude-only notes in CLAUDE.md.
Why are these files written in Markdown?
Markdown is compact, token-efficient, easy to diff in Git, and readable by both humans and models, which makes it ideal for feeding context to AI tools.
Where do agent files usually live?
Most sit at the repository root or in a tool folder like .github or .cursor/rules. llms.txt sits at the website root. Global versions can live in your home directory.