Your AGENTS.md is too long

I’ve been reviewing AGENTS.md files since agents started reading them. Open source repos, teams shipping real products with Claude Code, Cursor, Codex CLI. The pattern I keep seeing: people treat their AGENTS.md like a wiki. Three hundred lines of architecture docs, then coding standards, API references, deployment procedures, and the agent’s life story.

The thing is, agents will read the whole file. They’ll load every line into context. But that’s actually the problem. A 400-line AGENTS.md means 400 lines of rules that can conflict with each other, go stale at different rates, and bury your most important rules under a wall of nice-to-knows. It’s the same reason you don’t put your entire codebase in one file.

Here’s what I think you should do instead.

Think table of contents, not encyclopedia

Your AGENTS.md should be around 100 lines. Maybe 120 if you have a lot of hard rules. That’s it.

The job of AGENTS.md is orientation. It answers three questions: what is this repo, what are the rules, and where do I find more detail? It’s a map, not the territory.

When I first started writing these, I made the same mistake everyone makes. I put everything in one file. Architecture, principles, coding standards, deployment docs, test strategies. The file got way too big, way too fast. And I kept finding agents doing things I’d explicitly told them not to do. Turns out the rule was buried under 200 lines of context they didn’t need for that task. Five clear rules beat fifty buried ones.

So I split it up. AGENTS.md became the entry point. Everything else moved into docs/. The improvement was immediate, not because agents suddenly “read better” but because each file had one job and stayed maintainable.

What belongs in AGENTS.md

Five things. That’s it.

Repo structure. A quick tree showing where things live. Not every file, just the top-level layout so the agent knows where src/, docs/, scripts/, and config files are. Ten lines max.

Commands. How to install, build, test, lint, and deploy. Put these in a table. Agents need to run things, and if you don’t tell them how, they’ll guess. They’ll guess wrong. I once watched Claude Code run npm test on a project that used pnpm vitest run. It passed zero tests and then tried to “fix” the test runner.

Hard rules. The non-negotiables. “Never use console.log, use the shared logger.” “Every feature ships with tests.” “Validate all external input at ingestion.” These are the rules that, if broken, create real problems. Keep this list short (5-8 items) and every one will land.

Links to deeper docs. A table pointing to docs/ARCHITECTURE.md, docs/PRINCIPLES.md, docs/QUALITY.md, and whatever else you maintain. The agent knows these exist and can read them when relevant.

Plans and decisions. Where to find active work plans and architecture decision records. This is how agents understand what’s in-flight and why past choices were made.

That’s the whole file. Five sections, around 100 lines.

What does not belong in AGENTS.md

Architecture documentation. That’s its own file. When an agent needs to understand your domain model, layer rules, or dependency graph, it can read docs/ARCHITECTURE.md. Stuffing it into AGENTS.md just means it changes at a different pace than the rest of the file, and you end up with stale architecture docs sitting next to current rules.

Coding principles and standards. Same deal. Move them to docs/PRINCIPLES.md. Agents will reference them when they’re writing code. They don’t need your opinions about early returns vs. nested conditionals loaded for every single task.

Design decisions. Individual ADRs go in docs/decisions/. A running index can live in docs/DESIGN-INDEX.md. Decisions accumulate over time, and your AGENTS.md shouldn’t grow with every architectural choice you make.

API documentation. Just don’t.

The common thread: if it changes independently from AGENTS.md, it should live somewhere else. AGENTS.md is the thing that changes least. It’s the stable entry point. The docs it links to can evolve as fast as they need to.

Progressive disclosure

This pattern has a name, and it’s worth understanding why it works.

When an agent picks up a task, it reads AGENTS.md first. That gives it the repo layout, the rules, and the commands. For most tasks, that’s enough to get started. If the task touches architecture, the agent follows the link to docs/ARCHITECTURE.md. If it’s writing new code, maybe it checks docs/PRINCIPLES.md.

The agent loads context on-demand, just like a developer would. You don’t re-read the entire company wiki before fixing a bug. You check what’s relevant.

This is why a 100-line AGENTS.md with links to good docs outperforms a 500-line AGENTS.md with everything inline. The total documentation might be the same size. The difference is separation of concerns. Each file has one job, stays focused, and can be updated without touching everything else. When your coding standards change, you edit docs/PRINCIPLES.md. Your AGENTS.md doesn’t need a PR.

The supporting docs

A lean AGENTS.md only works if the docs it points to are actually maintained. Here’s what I keep in most projects:

docs/ARCHITECTURE.md covers your domain map, layer rules, dependency directions, and the key abstractions every developer (human or AI) needs to understand. This is the file where you explain that your API layer can import from core but not the other way around.

docs/PRINCIPLES.md holds your mechanical rules. Not philosophical ideals, but things you can check. “Parse at boundaries” with a grep command to verify compliance. “Structured logging always” with grep -r 'console.log' src/ returning zero results. If a principle can’t be checked, it’s a suggestion, and suggestions get ignored.

docs/QUALITY.md tracks quality grades by module. Which parts of the codebase are solid, which ones are held together with tape. Agents use this to calibrate how much care to take in different areas.

docs/decisions/ stores architecture decision records. When an agent asks “why is this done this weird way?” the answer should be in an ADR, not in someone’s memory.

docs/plans/ holds execution plans for multi-step work. Before starting anything that takes more than two steps, write a plan. It keeps agents on track and gives future agents context about what was attempted and why.

You don’t need all of these on day one. Start with AGENTS.md and ARCHITECTURE.md. Add the others as your project grows.

Mistakes I keep seeing

The novel. Someone writes an AGENTS.md with every detail they can think of. Architecture, standards, history, roadmap, team norms. It reads like an onboarding doc for a human employee. The problem isn’t that agents can’t read it. It’s that you’re less likely to keep this mega-file up to date, and conflicting rules start creeping in. If your AGENTS.md needs a table of contents, it’s too long.

No commands section. This one baffles me because it’s so easy to fix. Agents need to run your test suite. They need to build the project. If you don’t tell them pnpm test:unit they’re going to try npm test or yarn test or something they picked up from training data. I’ve seen agents install entirely different test frameworks because nothing told them what was already set up.

Stale content. You switched from Express to Fastify six months ago. Your AGENTS.md still says Express. Now every agent is confused when it reads the source code and the docs don’t match. An outdated AGENTS.md is actively harmful. It’s worse than having no file at all, because the agent trusts what you wrote.

Missing rules. This is the sneaky one. Your team knows you never use default exports. Your team knows the auth middleware is fragile and shouldn’t be touched without review. Your team knows you use Zod for all input validation. But none of that is written down, so the agent cheerfully uses default exports, refactors the auth middleware, and hand-rolls input validation with if statements.

If you find yourself correcting an agent about the same thing twice, that’s a missing rule. Write it down.

A template you can steal

Here’s a complete AGENTS.md you can copy into your project and fill in. It’s about 80 lines when populated, which leaves room for project-specific additions without getting bloated.

# AGENTS.md

Entry point for AI agents. Read this first, follow links for depth.

## Repo structure

\```
src/           <- application source
docs/          <- deep documentation (architecture, principles, decisions)
scripts/       <- build, test, lint, deploy tooling
tests/         <- test suites (if not colocated)
.github/       <- CI workflows, PR templates
\```

## Commands

| Task    | Command          |
|---------|------------------|
| Install | `npm install`    |
| Build   | `npm run build`  |
| Test    | `npm test`       |
| Lint    | `npm run lint`   |
| Deploy  | `npm run deploy` |

Run all commands from the repo root.

## Hard rules

1. Validate all external input at ingestion. Never pass untyped data downstream.
2. Every feature ships with tests. No exceptions.
3. Use the shared logger. No console.log in application code.
4. Check shared utilities before writing new helpers. Duplication is a bug.
5. Never commit broken builds. The repo must be in a working state after every change.

## Deeper docs

| Doc                      | Purpose                                        |
|--------------------------|-------------------------------------------------|
| `docs/ARCHITECTURE.md`   | Domain map, layer rules, dependency directions  |
| `docs/PRINCIPLES.md`     | Coding standards and mechanical rules           |
| `docs/QUALITY.md`        | Quality grades by module                        |
| `docs/DESIGN-INDEX.md`   | Index of architecture decision records          |
| `docs/PLANS.md`          | Active and completed execution plans            |

## Plans and decisions

- Before starting work with >2 steps, write a plan in `docs/plans/`.
- Significant technical choices get an ADR in `docs/decisions/`.
- Update `docs/PLANS.md` when starting or completing a plan.

Customize it for your stack. Replace npm with pnpm or cargo or make or whatever you use. Swap the rules for the ones that matter in your project. Add links to the docs you actually maintain. Delete rows from the docs table if you haven’t created those files yet.

The whole thing should take about 20 minutes to fill in. The return on that time is every future agent session in your project being measurably better.

Keeping it alive

The last thing, and maybe the most important: treat AGENTS.md like code. Review it in PRs. Update it when your stack changes. If you add a new lint rule that agents need to know about, add it to the hard rules section. If you move your test command, update the commands table.

I’ve started adding a line to my PR checklist: “Does this change affect AGENTS.md?” It catches drift before it becomes a problem.

One trick that helps: run a fresh agent session on your project every couple of weeks and give it a real task. Watch where it stumbles. If it makes wrong assumptions about how to run tests, your commands section is stale. If it violates a pattern your team follows, you’re missing a rule. The agent is basically a canary for your documentation quality.

A hundred lines, five sections, twenty minutes to set up. That’s all it takes to go from a wall of text to a map agents can actually follow.