Why Duplicating Your README Into AGENTS.md Makes Agents Worse

More context helps a junior developer. It does not help an agent, and the reason it doesn't is worth understanding before you write another line of your context file.

The finding

Guidance that emerged through 2026 converged on an unintuitive rule: keep your root AGENTS.md near 20 to 30 lines, because content duplicated from the README measurably hurts agent performance. Not "adds little value" — actively degrades it.

This runs against the instinct of every engineer who has ever onboarded a junior developer. More context helps a person. The mental model that says an agent is a very fast junior developer predicts that more context helps the agent too, and that model is wrong in a specific and instructive way.

Three mechanisms

1. The window is zero-sum

Every token in the context window is a token competing for attention with every other token. When an agent works on a task it is holding: the system prompt, your context file, the files it has opened, the conversation so far, and its own prior output. Nine hundred words of project history in your context file is nine hundred words that cannot be a relevant source file.

This is not merely about hitting a hard limit. Long before you run out of window, you run into the well-documented tendency of models to weight information at the beginning and end of a long context more heavily than material buried in the middle. A thirty-line file is entirely "beginning". A three-hundred-line file has a middle, and your most important rule may well be sitting in it.

2. Duplication creates contradiction

This is the mechanism that does the real damage. Consider the following, which is not a hypothetical — some version of it exists in a large fraction of repositories that have both files.

The repository migrated to uv. Nobody updated either markdown file, because neither is executed and neither breaks. A human developer runs poetry install, gets an error, looks around, and figures it out in thirty seconds. An agent runs poetry install, gets an error, and now has to decide whether the error means the command is wrong or the environment is broken. Frequently it concludes the latter and starts trying to install poetry.

Note that the duplication is what turned a stale README into an active hazard. Had AGENTS.md simply not mentioned installation, the agent would have read pyproject.toml — the file that cannot go stale, because it is the one the tooling actually executes.

3. It teaches the agent not to look

A context file that comprehensively describes the project implicitly tells the agent that reading the project is unnecessary. That is precisely backwards. You want the agent reading the actual code, because the actual code is correct by construction. What you want the context file to supply is the things reading the code will not reveal: intent, history, and the gap between what the code does and what it should do.

The discoverability test

Before a line goes into AGENTS.md, ask: could an agent determine this by reading the repository? If yes, cut it.

The right column has a shape to it. Every entry encodes either a constraint the code does not express, or a known trap that has already cost somebody an afternoon. That is the entire job of the file.

Before and after

A real-world file, lightly anonymised, that had grown to 180 lines:

# Project Atlas

Atlas is a distributed inventory management system built to replace the
legacy warehouse tracker. It was started in 2023 by the platform team and
now serves roughly 400 requests per second at peak...

## Architecture

Atlas follows a microservices architecture. Each service is independently
deployable. We use Kafka for inter-service messaging. The main services are:

- atlas-api: the public HTTP API, written in Go
- atlas-worker: background job processing, written in Go
- atlas-ui: the admin frontend, written in TypeScript and React
...

## Getting started

1. Clone the repository
2. Install Go 1.21 or later
3. Install Docker
4. Run `make setup`
...

Every word of that is in the README. The agent gains nothing and pays for all of it. Here is the same repository's file after applying the discoverability test:

# AGENTS.md

## Commands
- Setup: `make setup` (needs Docker running, takes ~4 min first time)
- Test: `go test ./... -short` for unit; drop `-short` only in CI, the
  full suite needs Kafka and takes 12 minutes
- Lint: `golangci-lint run` — config is authoritative, do not add nolint

## Boundaries
- `atlas-api/` must not import from `atlas-worker/` — shared code goes
  in `internal/shared/`
- Kafka topic names are declared in `internal/shared/topics.go` only.
  Never a string literal at the call site.

## Traps
- `make setup` fails silently if Docker is not running. Check first.
- Generated protobuf code is in `*_pb.go`. Never hand-edit; run `make proto`.
- The `-short` flag is load-bearing. Without it tests need a live cluster.

## Do not touch
- `legacy-sync/` — read-only, deleted once the 2024 migration finishes

Twenty-two lines, and every one of them is something the agent would otherwise get wrong.

What to do with the material you cut

Delete most of it. The architecture overview is in the README, where humans who need it will find it. If it is not in the README, that is a README problem and you have just discovered it.

Two categories are worth relocating rather than deleting:

• Package-specific rules belong in a nested AGENTS.md inside that package, where they apply automatically to work in that directory and cost nothing when the agent is working elsewhere.
• Long-form explanation that an agent occasionally needs belongs in a linked document. A one-line pointer — "Deployment is documented in docs/deploy.md; read it before changing anything under infra/" — costs twelve tokens instead of nine hundred, and the agent will follow the link when the task calls for it.

Measuring it on your own repository

You do not have to take the thirty-line guidance on faith. The check is cheap:

1. Write down five tasks representative of real work in the repo.
2. Run each against a fresh agent session with your current context file. Record what goes wrong: wrong command, wrong directory, wrong pattern.
3. Cut the file using the discoverability test.
4. Run the same five tasks again, fresh sessions.
5. Compare the error counts.

Keep the tasks written down. They become a regression suite for the context file itself, and re-running them after edits is the only way to know whether a change to the file helped or hurt. Most teams edit these files entirely on intuition and never find out.