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.
• Human written docs improve success ~4% over LLM-generated ones¹.

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

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

Hierarchy

./AGENTS.md                   → repo root (primary)
./packages/api/AGENTS.md      → specific overrides

CLAUDE.md

Some behavior that only applies to Claude Code worth noting.

• Loads into memory every session, so keep it under ~60–150 lines, only include what applies to every session.
• You can store personal global preferences at ~/.claude/CLAUDE.md that apply to all sessions.
• You can also have personal project-specific overrides at ./CLAUDE.local.md that are gitignored.

Before Claude Code starts support AGENTS.md, just put a single line in CLAUDE.md:

See @AGENTS.md

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

Footnotes

1. A study by ETH Zurich, source. ↩