A project-structure section in AGENTS.md is a short map of where things live: the top-level folders, which ones are apps, packages, and docs, and any naming or ownership rules an agent can't work out from the tree alone. AGENTS.md is plain Markdown with no required heading — you can use any headings you like. The map is guidance an agent reads. It doesn't enforce your layout. In a monorepo, keep the root map high-level and put a nested AGENTS.md in each package for its local map. Agents read the nearest file in the tree, so the closest one takes precedence.
Who this is for
Your agents keep creating files in the wrong package, looking for shared code in the wrong place, or editing generated output, and your AGENTS.md says nothing about how the repo is laid out.
What the map should list
| Put in the map | Why the agent needs it | Leave out |
|---|---|---|
| Top-level folders and what each holds | So it starts in the right place | A full file-by-file tree |
| Which folders are apps, packages, docs | So new code lands in the right kind of folder | Folders it never needs to touch |
| Where shared code and types live | So it reuses instead of duplicating | Implementation detail inside each module |
| Generated or vendored folders | So it doesn't hand-edit output | Build internals |
| Naming rules the tree doesn't show | So new files match existing ones | Style rules covered elsewhere in the file |
| Pointers to nested AGENTS.md files | So it knows local maps exist | A copy of each local map |
A sample section
## Project structure
- `apps/web/` — Next.js site. Pages in `app/`, components in `components/`.
- `apps/api/` — API server. Has its own AGENTS.md.
- `packages/ui/` — shared React components. Add new shared components here, not in apps.
- `packages/types/` — shared TypeScript types.
- `docs/` — human docs. Don't edit unless asked.
- `dist/`, `generated/` — build output. Never hand-edit.
- Naming: kebab-case file names; tests sit next to the file as `*.test.ts`.The heading is your choice. "Project structure," "Project overview," and "Repo map" all work, because the agent reads the text, not a schema.
Nested AGENTS.md in a monorepo
Keep the root map to the top level: which apps and packages exist and what each is for. Inside each package, add an AGENTS.md that maps that package's own folders and rules. When an agent works in `apps/api/`, the nearest file is the one it follows, and on a conflict the closest file wins. Your direct instructions in chat still override both. The inheritance map shows how nested files combine.
Pitfalls
- A full tree dump. Pasting `tree` output goes stale fast and buries the parts that matter. List folders and their purpose.
- Treating the map as a guard. AGENTS.md doesn't block edits to `generated/`. If a folder must never change, say so plainly and check it in review.
- Duplicating local maps at the root. Two copies drift apart. Point to the nested file instead.
- Writing for humans. Onboarding history belongs in README.md (see AGENTS.md vs README). The map should say what an agent needs to navigate.
- Forgetting to update it. When you move or add a top-level folder, update the map in the same change.
How to check it
- Read each path in the map and confirm it still exists.
- Ask an agent where a new shared component should go, and confirm it names the folder from your map.
- In a monorepo, open a session inside one package and confirm the agent follows that package's AGENTS.md.
- Ask it to change a file in a generated folder and confirm it points to your "never hand-edit" line.
For the wider question of what belongs in the file and how Cursor, Claude Code, and Codex use it, see the AGENTS.md guide for Cursor, Claude Code, and Codex. For the PR block that often sits next to this map, see AGENTS.md PR and commit instructions.
Where ShipKits fits
The Operator Pack ($47) is markdown seats + skills + install.sh — not a hosted app, not a chatbot. Seven named seats, three skills, an ops playbook and a token-cost playbook. Done means a file, PR, or URL. Its AGENTS.md templates include a project-structure section, a nested-file pattern for monorepos, and placeholders for build, test, and PR instructions. Soft path: start at /free. Cheat Sheet for the skim checklist mindset.
Soft next step
Write a ten-line project-structure section for your repo and check every path in it today. Soft ladder: /free, then the Operator Pack ($47). Related: AGENTS.md vs README, AGENTS.md guide, PR and commit instructions.