Your agent already reads a file every session that tells it your stack and your non-negotiables. But that file says what to do, not where anything lives. So new code lands wherever the agent guesses: a feature split across the wrong folders, a database call inside a button, a structure it invents instead of yours. This chapter gives the agent a map of your codebase in that same file, so its code extends your architecture instead of fighting it.
3.10.1Hand the agent the map
An architecture map is a compact picture of your codebase, added to the file your agent reads first. It says where features live, how the layers stack, what things are named, and where new code goes. It is the same thing a senior would tell a new hire before they touch anything.
Without it, the agent reverse-engineers your structure from whatever files it happened to open, and gets it wrong half the time. With it, the agent places code instead of guessing at it.
3.10.2Rules plus structure in one file
The map lives in the same always-read file as your rules, the one most tools share as AGENTS.md or call CLAUDE.md. Rules say how to behave; the map says where the code goes. The agent needs both in front of it every session.
Keep it a map, not an essay. A dozen lines that a beginner could not have written but an agent can follow exactly:
3.10.3New code lands in the right place
That last line does the heavy lifting. "New feature goes under src/features/, match the nearest neighbor" turns a vague instruction into a placement the agent cannot miss. The layer rule then stops it from wiring a database call straight into the UI. The naming line makes the new file look like it was always there.
Because this lives in the always-read file, it holds on every session, not just the one where you happened to explain it. The agent stops inventing structure and starts filling in yours.
3.10.4Keep the handoff current
The map is only as good as its accuracy. Add a new top-level folder or a new layer and forget to update the map, and the agent follows the old one straight into the wrong place. A stale map misroutes worse than no map at all.
Do not maintain it by hand. When you and the agent add a real structural piece, have it update the map in the same change. That is how your memory file grows itself when you correct it. Treat a map written months ago like old documentation: check it against the real folders before you trust it.
3.10.5Write the map into your file
This prompt has your agent read the code and write the map:
Do this now: paste the prompt so your agent writes the map, then read it against your real folders and cut any line the code does not actually follow.
