Make your AGENTS.md a table of contents

If you use an AI coding agent, you've probably heard of AGENTS.md. It's a Markdown file you place in the root of your project to give your agent instructions and context. Most AI coding tools — Claude Code, Cursor, Copilot, Codex — look for it automatically. Think of it as a README for your AI. Where a README orients a human contributor, an AGENTS.md orients the agent.

The problem is that most AGENTS.md files try to do everything. Coding conventions, architecture decisions, style preferences, product context — all jammed into one file that grows to hundreds of lines. The LLM reads it every time it starts a task. Most of that context is irrelevant to the work at hand.

OpenAI's Harness team ran into the same problem. They built and shipped a million-line product with zero hand-written code — every line generated by Codex. Early on they tried the "one big AGENTS.md" approach and watched it fail. Context is scarce. When everything is "important," nothing is. The file rots fast and agents start pattern-matching locally instead of navigating intentionally.

"Instead of treating AGENTS.md as the encyclopedia, we treat it as the table of contents." — Ryan Lopopolo, OpenAI

Their fix was to keep AGENTS.md short — roughly 100 lines — and point it at a structured docs/ directory that serves as the system of record. Design docs, execution plans, architecture notes, and product specs all live in their own files. The AGENTS.md is just the map.

This is the approach I'd recommend for any project. Keep the file itself short and link to the documents that carry the real weight. When an agent picks up a task, it reads the table of contents first, then follows the links it needs for the specific job. A bug fix might pull in architecture notes and coding conventions. A new feature might need the product vision and customer profiles. The agent decides what's relevant rather than processing everything upfront.

This is especially powerful if you have a context repository — a collection of product documents like your vision, roadmap, customer profiles, and feature specs. Without an AGENTS.md pointing to it, your agent doesn't know that context exists. With one, every document in your context repository becomes discoverable. The AGENTS.md is the bridge between your codebase and the business knowledge your agent needs to make good decisions.

Here's what a practical AGENTS.md looks like:

# Project name
 
Brief one-liner about what this project is.
 
## Essential references
 
- [Architecture notes](./docs/architecture.md)
- [Coding conventions](./docs/conventions.md)
- [Style guide](./docs/style-guide.md)
- [Testing strategy](./docs/testing.md)
 
## Product context
 
- [Product vision](./planning/strategy/vision.md)
- [Current roadmap](./planning/strategy/roadmap.md)
- [Customer profiles](./planning/customers/)
- [Feature specs](./planning/features/)
 

# Project name
 
Brief one-liner about what this project is.
 
## Essential references
 
- [Architecture notes](./docs/architecture.md)
- [Coding conventions](./docs/conventions.md)
- [Style guide](./docs/style-guide.md)
- [Testing strategy](./docs/testing.md)
 
## Product context
 
- [Product vision](./planning/strategy/vision.md)
- [Current roadmap](./planning/strategy/roadmap.md)
- [Customer profiles](./planning/customers/)
- [Feature specs](./planning/features/)
 

The first section points to technical references — how the code is structured, how to write it, how to test it. The second section links to your context repository where product knowledge lives. Each document stands on its own. The AGENTS.md just tells the agent where to find them.

What makes this work is that every reference document becomes independently useful. Your architecture notes can be thorough without bloating the root file. Your coding conventions can evolve without touching AGENTS.md. Add a new feature spec to the features directory and the agent discovers it automatically — no root file update needed.

You don't have to write this by hand. Ask your LLM to scan your project and generate one for you. Here's a prompt you can copy and paste:

Scan this project and create an AGENTS.md file in the root. Treat it as a table of contents, not a dump of instructions. First, look for existing documentation, READMEs, architecture docs, style guides, coding conventions, and planning documents. Then interview me about any important context that isn't already documented — product vision, key decisions, conventions that live in my head. Create short reference docs for anything worth capturing. Link to everything with a short description. Keep the AGENTS.md under 40 lines. Group links into sections: essential references and product context. If a section has no relevant documents, skip it.

Scan this project and create an AGENTS.md file in the root. Treat it as a table of contents, not a dump of instructions. First, look for existing documentation, READMEs, architecture docs, style guides, coding conventions, and planning documents. Then interview me about any important context that isn't already documented — product vision, key decisions, conventions that live in my head. Create short reference docs for anything worth capturing. Link to everything with a short description. Keep the AGENTS.md under 40 lines. Group links into sections: essential references and product context. If a section has no relevant documents, skip it.

Run that in your project and you'll have a solid starting point in about thirty seconds. Review what it generates, adjust the sections to match your project's structure, and commit it. From there, treat AGENTS.md like any other living document. When you add a new architecture decision record or update your testing strategy, add a link. When a document moves or gets retired, update or remove the pointer. A stale table of contents is worse than none at all.

The goal is to give your agent a map, not a manual. Keep AGENTS.md short, link to documents that matter, and let the agent pull in context as it needs it.