Instruction Docs

How to write instruction docs for AI agents. e.g. AGENTS.md and CLAUDE.md.

Key Insights

• AGENTS.md = vendor-neutral open standard.
• CLAUDE.md = Claude Code-specific memory file, loaded every session.
  • Loads into memory every session, so keep it under ~60–150 lines, only include what applies to every session.
  • Before Claude Code starts support AGENTS.md, just put a single line of See @AGENTS.md.
• Human written docs improve success ~4% over LLM-generated ones¹.
• Updated docs do not applied to existing session.

DOs

• Focus on non-trivial, non-inferable, non-enforceable info that agents can't easily infer.
• Use progressive disclosure with multiple docs.
• Put all crucial commands in packages.json, Makefile, or nested docs.
• Setup hooks to enforce code style and patterns.
• Create a canary instruction so you can easily tell if agents are following instructions.

DON'Ts

• Don't put project tree structure without explanations. Agents can easily infer from the codebase itself.
• Don't put task-specific instructions. These should be in directory-specific AGENTS.md.
• Don't put code examples of patterns. Agents can learn from the codebase itself.
• Don't set "Never do X" rules. This make agents get stuck, always provide alternatives.
• Don't put repetitive, outdated, or non-crucial info (e.g. Emojis)

Hierarchy

~/.codex/
└── AGENTS.md                 → personal Codex global preferences, apply to all projects
~/.claude/
└── CLAUDE.md                 → personal Claude global preferences, apply to all projects

my-awesome-project/
├── AGENTS.md                 → project (primary)
├── CLAUDE.md                 → project
├── CLAUDE.local.md           → personal overrides, git ignored
└── packages/api/
    ├── AGENTS.md             → local overrides (primary)
    ├── CLAUDE.md             → local overrides
    └── CLAUDE.local.md       → personal local overrides, git ignored

Template

Root AGENTS.md

# [Project Name]

[One sentence: what this project does and why it exists.]

## Project Map

- `path/to/dir` — Non-trivial info that agents can't easily infer.
- `path/to/dir` — This file is the entry point for X, it does Y and Z. If you want to modify X, this is the file to start with.
- `path/to/dir` — This is where the core domain logic lives, pure functions with no I/O.

## Landmines & Gotchas

<!-- Things the agent CANNOT discover by reading your code. -->
<!-- If it can figure it out from a directory listing or README, don't put it here — you're just adding noise. -->

- Use `uv` for Python deps, NOT pip
- Always run tests with `--no-cache` — fixture setup causes false positives otherwise
- `some.file` is auto-generated. Never edit it — modify `some.other.files` instead.
- The auth module uses a custom middleware pattern. Do NOT refactor to standard Express middleware.
- `some-path/` is deprecated but still imported by 3 production modules — do not delete anything in it
- When adding a new API route, you MUST also update `some.file`.

## Conventions & Workflow

- Prefer small, focused diffs
- Use Plan Mode for any refactor touching `src/core/`

## For More Context

<!-- Use progressive disclosure: don't paste docs here, point to them. -->
<!-- The agent will read these on-demand when relevant.                -->

- Architecture deep-dive: see `agent-docs/architecture.md`
- Testing patterns: see `agent-docs/testing-guide.md`
- API conventions: see `agent-docs/api-conventions.md`

Override AGENTS.md

# [directory-name/]

[One sentence: what this package/module/service is responsible for.]

## Commands (overrides root)

<!-- Only include if commands differ from root AGENTS.md. -->
<!-- The closest AGENTS.md to the file being edited wins. -->

```bash
# Run tests for this package only
make test-module

# Lint this package only
make lint-module
```

## Domain Rules

<!-- Non-obvious constraints specific to this part of the codebase. -->
<!-- Skip anything that's obvious from reading the code itself.     -->

- All monetary values MUST use `Decimal` type — never floats
- webhook handlers go in `some/path/`, nowhere else
- PCI compliance: never log card numbers or CVVs, even in debug mode
- This service talks to `orders-service` via gRPC, not REST

## Key Files

<!-- Pointers to the files that matter most in this directory.   -->
<!-- Helps the agent orient quickly without scanning everything. -->

- `path/to/file` — main webhook entrypoint
- `path/to/file` — subscription lifecycle logic
- `path/to/file` — shared test data — do not modify without updating all tests

## Local Conventions

<!-- Only include conventions that DIFFER from or ADD TO the root file. -->
<!-- Don't repeat root-level rules here.                                -->

- Error responses must use `SomeError` class from `some/file`, not generic `Error`
- All new endpoints require an integration test in `__tests__/integration/`
- Database queries go through `repo/` layer — never call Prisma directly in handlers

References

• AGENTS.md
• Claude Code Docs - Best Practices for Claude Code
• HumanLayer Blog - Writing a good CLAUDE.md
• GitHub - How to write a great agents.md: Lessons from over 2,500 repositories
• Vercel - AGENTS.md outperforms skills in our agent evals
• The Prompt Shelf - AGENTS.md vs CLAUDE.md: What's the Difference and When to Use Each (2026)

Footnotes

1. A study by ETH Zurich. ↩