The complete AGENTS.md guide — standard section structure and how to write it

Updated 2026-07-11 · A reference guide for developers

1. What is AGENTS.md

AGENTS.md is a tool-agnostic markdown file that gives coding agents the rules and context of a project. Placed at the repository root, it is read by agents that support the convention — Cursor, Claude Code, OpenAI Codex, GitHub Copilot, Google Jules, and others — before they generate or edit code. It tells them how to set up, build, and test the project; the code style; the directory structure; commit conventions; and security constraints. Think of it not as a README for humans, but as an operating manual for agents.

2. Why it matters — the fragmentation problem

Every AI coding tool used to have its own rules filename. Claude Code read CLAUDE.md, Cursor read .cursorrules or .cursor/rules, and GitHub Copilot read .github/copilot-instructions.md. Maintaining the same rules across several files is painful — change one and the others drift out of sync. The AGENTS.md standard emerged to solve this fragmentation and has been adopted across tens of thousands of repositories. The recommended pattern is to keep a single AGENTS.md as the source of truth and symlink the rest.

3. The standard section structure (8 sections)

AGENTS.md is free-form markdown, but a section structure has settled in practice. This generator emits the following eight sections in a standard order.

1. Project overview — a one-line summary and the tech stack, so the agent instantly knows what it is working on.
2. Setup commands — dependency install commands (in a code block), plus dev-server, build, test, and lint commands.
3. Code style — indentation, naming, formatter (Prettier/Black/gofmt), and linter rules.
4. Testing — how to run the tests, plus rules like "run tests before committing".
5. Project structure — the main directories and their roles (a code tree).
6. Commit & PR conventions — Conventional Commits, subject length, one PR per change.
7. Security — how to handle secrets, what must never be logged, input validation.
8. Do not — an explicit list of prohibited actions (don't edit generated files, don't commit to main).

4. Tips for each section

Make setup commands copy-pasteable

Put the exact commands in a code block so the agent can run them verbatim — npm install, pip install -r requirements.txt — not prose like "install the dependencies".

Code style: one rule per line

List short, verifiable rules such as "Indent with 2 spaces", "TypeScript strict mode", "Format with Prettier". This generator turns each line into a bullet.

"Do not" is the most powerful section

Agents often edit generated files or add unnecessary dependencies. Explicit prohibitions — don't edit dist/ or build/, don't add dependencies without discussion, don't commit directly to main — dramatically reduce mistakes.

5. Stack presets

This generator ships presets for Node.js/TypeScript, React/Vite, Python, Go, Rust, and Monorepo (pnpm/Turborepo). Choosing a preset auto-fills the commands and code style with each ecosystem's conventions (for example, Python uses 4-space indentation, PEP 8, and pytest; Go uses gofmt and explicit error handling). Then you adjust the fields to match your project.

6. Relationship to CLAUDE.md, .cursorrules, and copilot-instructions

For tools that don't yet support AGENTS.md, this generator emits the same content as four files.

• AGENTS.md — standard, tool-agnostic.
• CLAUDE.md — Claude Code.
• .cursorrules — Cursor.
• .github/copilot-instructions.md — GitHub Copilot.

Regenerate all four whenever the rules change, or keep AGENTS.md as the source of truth and symlink the rest.

ln -s AGENTS.md CLAUDE.md ln -s AGENTS.md .cursorrules

7. Privacy

This generator is 100% client-side. Your project details are never sent to a server; they live only in localStorage and, if you copy a share link, the URL token (?s=). It is safe to use even with details about a private codebase.