How to keep AGENTS.md useful as a repository grows

AGENTS.md should help an agent decide where to work, which rules apply, and how to check a change. Those questions stay fairly stable as a repository grows. The implementation details do not. Putting both in the same file gives every task more to read and every source change more places to update.

A useful arrangement is a short entry file that points to maps of the relevant source areas. A change to the retry code starts with the retry map. A change to the renderer starts with the renderer map. The project rules remain in one place.

@deweydocs/dewey 0.5.1 keeps entry instructions in AGENTS.md, implementation details in source maps, public instructions in guides, and past plans and decisions in history. Dewey overview

Give the entry file a small job

Keep three kinds of information near the entrance:

• The project's purpose and hard rules.

• Commands that a contributor needs to run.

• Directions to the source map for the work at hand.

Move implementation explanations into those maps. Put task instructions in guides and interface contracts in reference pages. Preserve decisions and old plans as history, where they remain available without becoming instructions for every new task.

This division also gives each document a reason to change. A new hard rule changes the front door. A changed retry limit calls for a review of the retry map and any guide that states the limit.

Start with an actual source area

For a small project with src/index.ts and src/retry.ts, initialize Dewey from the project root:

bun add -d @deweydocs/dewey@0.5.1bunx dewey init \  --purpose "Print the retry budget" \  --rule "Keep the retry budget in src/retry.ts"

The purpose describes the job. The rule describes a constraint an agent must preserve. Use your own project's purpose and rules when applying the command elsewhere.

In this two-file example, the generated AGENTS.md has 24 lines. It directs work on src to docs/src.agent.md. The source map begins with a declaration of what it covers:

---kind: maptitle: Retry implementationcovers: [src/*]---

The rest of the map names the two files, explains how the entry point reads the exported retry budget, and records the relevant constraints. That explanation belongs close to its source coverage.

Init creates drafts. An empty set of section headings is not a finished map. Read the files, write what they do, remove draft: true, and record the review:

bunx dewey review docs/src.agent.mdbunx dewey buildbunx dewey check

The quickstart covers the full authoring loop.

Make the routing useful before adding more prose

An agent should be able to find the relevant document from a source path:

bunx dewey which src/retry.ts --json

For the completed example, the result identifies docs/src.agent.md, its src/* pattern, and its size: 20 lines and an estimated 103 tokens. The size is a reading estimate, not a measurement from a particular model's tokenizer.

The complementary question is whether any source files have no map:

bunx dewey uncovered --json

The example returns {"areas": []}. In a growing project, this command helps identify the next source area that needs documentation.

Choose coverage deliberately. src/* covers files directly inside src; it does not cover src/sync/index.ts. A separate map can explain that nested area. Broad coverage makes a short file look comprehensive while hiding the work needed to maintain it. Coverage and lookup commands

Treat the budget as an editing constraint

Dewey checks a combined limit of 150 lines and about 2,000 tokens for AGENTS.md and configured host pointer files. Those are Dewey's limits, not a claim that every agent performs best at precisely that size.

When the file exceeds the budget, look for misplaced material: long API tables, implementation walkthroughs, repeated task instructions, or old plans. Give that material a destination and leave a useful direction in the front door.

Keep authored rules outside Dewey's marked observed region. Build refreshes that region from the project, including scripts and source-map routes. This separates the facts Dewey can observe from the constraints you must decide.

A passing check means references, coverage, reviews, and generated outputs agree. It does not judge whether the map's explanation is true.