AGENTS.md Author Guide

Overview

AGENTS.md is a Markdown file located at the root (or any subdirectory) of a code repository. It tells AI coding agents—across vendors—how to set up, build, test, and contribute to the project. Unlike README.md, which is for humans, AGENTS.md is for agents: it is loaded automatically by the agent's harness as high-priority context.

When to Use AGENTS.md

Use AGENTS.md when ALL of these hold:

• The repository will be touched by AI coding agents (CI, devs, IDEs);
• Agents need to know how to build, test, lint, or commit safely without re-discovering it every session;
• Conventions exist that a human reads from a README but an agent will miss without explicit instruction.

Prefer CLAUDE.md only when:

• The project is Claude-Code-specific and you need Claude-only behaviors;
• Note: many tools (Codex, Cursor, Aider) honor AGENTS.md but ignore CLAUDE.md;
• Best practice: write AGENTS.md as the canonical file and (if needed) create CLAUDE.md as a thin wrapper that references it.

Prefer SKILL.md when:

• The knowledge is a portable, vendor-neutral capability (e.g., "PDF extraction skill") rather than project setup.

Prefer README.md when:

• The audience is humans evaluating or onboarding to the project;
• Marketing, screenshots, philosophy belong in README, not AGENTS.md.

Both can coexist. Each should refer to the other where useful—never duplicate.

File Location Rules

• AGENTS.md at the repo root is the default entry point;
• Nested AGENTS.md files (e.g., apps/web/AGENTS.md, packages/core/AGENTS.md) apply within their subtree and override or extend the root;
• Resolution: the most specific AGENTS.md wins for the file the agent is editing;
• Monorepos: prefer per-package AGENTS.md so agents do not load irrelevant setup for unrelated subprojects.

Recommended Sections (in suggested order)

Skip any that does not add value. Do not pad. Do not invent commands.

1. PROJECT OVERVIEW (≤ 3 sentences)

   • What this repo is. Stack. Primary language(s).
   • State explicitly if it is a monorepo, library, service, or app.

2. SETUP COMMANDS

   • Minimum commands an agent runs to get a working dev environment.
   • Pin versions where required (e.g., "Node ≥ 20.x", "uv ≥ 0.4").
   • Include the install command verbatim.

3. BUILD / TEST / LINT / TYPECHECK

   • Exact commands. One per line. No prose between them.
   • Distinguish: full suite, fast suite, single-file, watch mode.
   • Specify which command the agent should default to before committing.

4. CODE STYLE

   • Tabs vs spaces, line length, formatter (e.g., "ruff format", "prettier").
   • Module conventions (e.g., "Use ES modules, not CommonJS").
   • Naming patterns specific to this project.
   • Forbidden patterns ("Do not import from internal/").

5. TESTING INSTRUCTIONS

   • What kind of tests to write (unit / integration / E2E).
   • Where they live (tests/, __tests__, *_test.go, etc.).
   • Coverage expectations, if enforced.
   • How to run a single test.
   • When to skip writing a test (rare—be explicit).

6. PR / COMMIT RULES

   • Branch naming, conventional commits, Signed-off-by, DCO.
   • PR title format, required body sections.
   • Required CI checks before merge.
   • Whether the agent may push directly or must open a PR.

7. SECURITY & SECRETS

   • Files the agent must never read or write (.env*, *.pem, secrets/, credentials.json).
   • Which APIs require auth and where keys live.
   • Whether the agent may run arbitrary curl / network calls.
   • Whether the agent may run rm -rf, destructive git, or migrations.

8. DEPLOYMENT & RELEASE

   • Only if the agent is expected to deploy or cut releases.
   • Otherwise omit.

9. ARCHITECTURE NOTES (only what an agent needs to act safely)

   • Modules whose ownership matters ("Do not modify generated files in proto/").
   • Boundaries between subsystems.
   • Where to add new code by default ("Add new endpoints under api/v2/").

10. NESTED AGENTS.md POINTERS

    • List sibling AGENTS.md files in the monorepo so the agent can navigate.

Writing Rules

1. WRITE FOR AN AGENT, NOT A NEW HIRE.

   • Imperative mood, second person, terse.
   • "Run pnpm test." NOT "You can run pnpm test if you want to verify."
   • No motivational language. No "great!", "important!", "remember to".

2. EVERY COMMAND MUST BE COPY-PASTABLE AND CORRECT.

   • If you do not know the exact command, ask the user—do not guess.
   • Do not include commands that depend on environment variables that the repo does not document.

3. KEEP IT SHORT.

   • Aim for ≤ 200 lines for typical repos.
   • Long AGENTS.md files get truncated by harnesses or pollute the agent's context window. Push detail into per-package AGENTS.md or linked docs.

4. DO NOT DUPLICATE THE README.

   • Cross-reference instead: "See README.md for project background."
   • AGENTS.md owns: how to build, test, commit safely. README owns: what and why.

5. PREFER NEGATIVE CONSTRAINTS WHERE THEY MATTER.

   • "Do not edit files under vendor/.
   • "Do not run npm install—this project uses pnpm.
   • Agents follow explicit prohibitions better than implicit conventions.

6. STATE THE DEFAULT VERIFICATION STEP.

   • Always include the single command an agent should run before declaring a task done (e.g., make check, pnpm verify, cargo test).

7. NO SECRETS, NO TOKENS, NO PRIVATE PATHS.

   • AGENTS.md is committed. Treat it as public.

8. ONE SOURCE OF TRUTH.

   • If a command appears in README, package.json scripts, Makefile, and AGENTS.md—keep the canonical definition in the build tool and reference it from AGENTS.md.

Common Anti-Patterns (MUST NOT)

• Aspirational rules nobody follows ("All code must have 100% coverage" when the project has 30%).
• Generic best-practice essays ("Always write clean code").
• Re-listing every dependency ("This project uses React, TypeScript, …").
• Mentioning tools but not the commands ("We use Playwright"—say which command runs it).
• Long conceptual architecture sections—those belong in docs/.
• Conflicting commands between root AGENTS.md and nested AGENTS.md without an explicit override note.
• Marketing language, philosophy, or "why we built this"—that is README's job.
• Embedding API keys, internal URLs, employee names, or anything that should not be public.

Workflow

When the user asks you to author or improve an AGENTS.md:

1. ORIENT

   • Inspect the repo structure, package manager, languages, frameworks, test runner, CI configuration.
   • Read the existing README.md, Makefile, package.json scripts, pyproject, Cargo.toml, go.mod, and CI workflow files. Extract the actual build/test/lint commands.
   • Identify whether it is a monorepo and where natural AGENTS.md boundaries are.

2. EXTRACT, DO NOT INVENT

   • Every command in AGENTS.md must come from a real source in the repo (script, Makefile, CI). If a command is missing, flag it and ask.
   • Note any conflicts between sources (README says one thing, CI does another)—surface them; do not silently pick one.

3. DRAFT

   • Use the recommended section order. Skip empty sections.
   • Keep ≤ 200 lines for the root file.
   • Wrap commands in fenced code blocks with the language hint.

4. VERIFY

   • For each command in the draft, point to the file in the repo where it comes from (e.g., "from package.json:scripts.test").
   • Run a self-review against the WRITING RULES and ANTI-PATTERNS lists.
   • Confirm secrets and private paths are absent.

5. PROPOSE NESTED FILES

   • For monorepos, propose per-package AGENTS.md outlines and explain what each overrides from the root.

Output Format

When asked to produce an AGENTS.md, output three blocks in order:

1. PROPOSED AGENTS.md—a single fenced markdown block, ready to commit.
2. PROVENANCE—a list pairing each command/section with the source file it was derived from (e.g., "test command ← package.json:scripts.test").
3. QUESTIONS—anything you could not resolve from the repo and need the user to confirm before finalizing. If none, write "None".

When asked to review or improve an existing AGENTS.md, output:

1. REVIEW—diff-style, line-by-line, listing what to keep, change, or remove and why.
2. REVISED AGENTS.md—a single fenced markdown block.
3. PROVENANCE and QUESTIONS as above.

Final Instruction

AGENTS.md is the contract between a repository and any AI coding agent that visits it. Make it tight, concrete, executable, and safe. If a section does not directly help an agent act correctly on this codebase, cut it.