AGENTS.md template reference: sections and formats

Field-by-field reference for both context files, including the compressed pipe-delimited format, the 120-line budget, and what belongs where.

The Agent Context System uses two files: AGENTS.md (committed, shared with your team) and .agents.local.md (gitignored, personal). Every agent reads both at session start. AGENTS.md delivers compressed project knowledge that applies to every developer and every agent on the project. .agents.local.md holds your personal accumulation of session notes, preferences, and patterns that are still experimental.

This page documents what goes in each file, why each section exists, and how to fill them in.

The 120-line budget

AGENTS.md must stay under 120 lines. This is not an arbitrary style rule — it is an instruction budget constraint.

Research by HumanLayer found that frontier LLMs reliably follow approximately 150–200 instructions. A coding agent’s system prompt already consumes around 50 of those slots. That leaves roughly 120 lines for project context. Content that exceeds the budget does not disappear — it competes for attention with everything else, and the agent quietly deprioritizes it.

Deeper documentation belongs in agent_docs/ and loads on demand when a task requires it. The content in AGENTS.md is passive context: it loads into the prompt on every single turn, whether the agent needs it or not. Vercel’s evals found that passive context achieves a 100% task pass rate, versus 53% when agents must decide to look things up. Make every line count.

Run agent-context validate to check your line count. It warns you when AGENTS.md exceeds 120 lines and suggests moving content to agent_docs/.

---

AGENTS.md sections

Project

Basic project metadata. Keep each field to one line.

## Project

- **Name:** [Project Name]
- **Stack:** [e.g., TypeScript, Next.js 15, Tailwind]
- **Package manager:** [e.g., pnpm]

Replace the bracketed placeholders with your actual values. The stack line is the first thing an agent reads when it opens the file — be specific enough that it can make correct technology assumptions immediately.

---

Commands

Executable commands for the most common developer tasks. Place this section early because agents need it on the first turn.

## Commands

```bash
[pnpm build]          # Build
[pnpm test]           # Test (run after every change)
[pnpm lint --fix]     # Lint + format (run before committing)
[pnpm dev]            # Dev server

Replace the bracketed placeholders with real commands. Include the exact flags your project uses — `pnpm test --run` behaves differently from `pnpm test`.

---

### Architecture

One line per directory, describing its purpose. The agent gets this on every turn without any lookup.

```markdown
## Architecture

src/ → Application source tests/ → Test files agent_docs/ → Deep-dive references (read only when needed) .agents/ → Memory system (local.md index, logs/, topics/)

Limit this to the directories an agent actually needs to navigate. Skip generated directories, build output, and node_modules.

---

Project Knowledge (Compressed)

This is the highest-value section in the file. It contains three subsections, each using a compact pipe-delimited format that keeps information dense without requiring prose.

Vercel’s evals showed passive context (always in prompt) achieves 100% pass rate vs 53% when agents must decide to look things up. This section is that passive context. Keep it dense and current.

Patterns

Documents recurring code patterns and where to find a canonical example. Format: pattern | where-to-see-it.

### Patterns

[named exports only | src/components/Button.tsx] [server components default | src/app/page.tsx] [Zustand for client state | src/stores/counter.ts] [Result types, not try/catch| src/lib/errors.ts]

Each entry fits on one line. The file reference gives the agent a concrete starting point — it does not need to search.

Boundaries

Rules the agent must not break, with the reason so it understands the constraint. Format: rule | reason.

### Boundaries

[never modify src/generated/ | auto-generated by Prisma] [env vars through src/config | never read process.env directly] [no default exports | breaks tree-shaking] [no inline styles | use Tailwind classes]

The reason column matters. An agent that understands why a boundary exists is less likely to violate it when the rule feels inconvenient.

Gotchas

Known traps with their fixes. Format: trap | fix.

### Gotchas

[pnpm build hides type errors | run pnpm typecheck separately] [dev sessions expire after 24h | don’t assume persistence in tests] [integration tests need DB up | docker compose up db first]

A gotcha entry captures pain that has already been felt. Fill these in from your own experience — not from speculation about what might go wrong.

---

Rules

A numbered list of behavioral instructions for the agent. The template ships with a default set:

## Rules

1. Read this file and `.agents/local.md` (if it exists) before starting any task. This applies whether you are the main agent or a subagent.
2. Plan before you code. State what you'll change and why.
3. Locate the exact files and lines before making changes.
4. Only touch what the task requires.
5. Run tests after every change. Run lint before committing.
6. Summarize every file modified and what changed.
7. At session end, append to `.agents/logs/YYYY-MM-DD.md` (today's daily log): what changed, what worked, what didn't, decisions made, patterns learned.

You can add project-specific rules here, but count your lines. Each rule is a token cost paid on every turn.

---

Deep References

Pointers to the agent_docs/ directory. These files are read only when a task requires deeper context than the compressed section provides.

## Deep References (Read Only When Needed)

- `agent_docs/conventions.md` — Full code patterns, naming, file structure
- `agent_docs/architecture.md` — System design, data flow, key decisions
- `agent_docs/gotchas.md` — Extended known traps with full explanations

agent_docs/ is committed alongside AGENTS.md. Treat it like source code — no secrets, same review standards.

---

.agents.local.md sections

.agents.local.md is your personal scratchpad. It is gitignored by default and never shared with your team. It grows over time as your agent logs what it learns each session. When it exceeds 300 lines, the agent compresses it: deduplicating entries, merging related notes, and flagging stable patterns for promotion.

Preferences

Your personal working style. The agent applies these throughout the session.

## Preferences

- **Style:** [e.g., Friendly, technical, peer-to-peer. No corporate jargon.]
- **Code:** [e.g., Minimal changes. No speculative refactors.]
- **Planning:** [e.g., Always state the plan before writing code.]

Patterns

Settled truths about this project that you have validated but have not yet promoted to AGENTS.md. Promote recurring session learnings here.

## Patterns

<!-- Settled truths about this project. Promote recurring session learnings here. -->

Gotchas

Things that look right but aren’t. Include why — the agent needs the explanation, not just the warning.

## Gotchas

<!-- Things that look right but aren't. Include WHY. -->

Dead Ends

Approaches you tried and abandoned. Recording dead ends prevents the agent from repeating them.

## Dead Ends

<!-- Approaches tried and failed. Include WHY they failed. -->

Ready to Promote

The agent flags patterns here during compression when something has recurred across three or more sessions. Items use the same pipe-delimited format that AGENTS.md expects.

## Ready to Promote

<!-- The agent flags items here during compression when a pattern has recurred across 3+ sessions.
     Use the same pipe-delimited format AGENTS.md expects:
       pattern | where-to-see-it    → goes in Patterns
       rule | reason                → goes in Boundaries
       trap | fix                   → goes in Gotchas
-->

You decide when to move flagged items into AGENTS.md. Run agent-context promote to review what is waiting. Run agent-context promote --autopromote to append them automatically.

The scratchpad is where knowledge is experimental. AGENTS.md is where proven knowledge lives. The agent flags candidates — you make the call.

Session Log

The agent appends one entry per session. Entries go at the bottom, in chronological order.

## Session Log

<!-- Append new entries at the END. One entry per session. Keep each to 5-10 lines. -->

### YYYY-MM-DD — Topic

- **Done:** (what changed)
- **Worked:** (reuse this)
- **Didn't work:** (avoid this)
- **Decided:** (choices and reasoning)
- **Learned:** (new patterns or gotchas)

The agent must propose the session log entry and wait for your approval before writing. It does not append automatically.

Compression Log

Records when the file was compressed and what was removed or merged.

## Compression Log

<!-- When this file exceeds 300 lines, compress. Log it here. -->

Compression triggers automatically at 300 lines. The log gives you an audit trail of what happened to older session notes.