How to stop AI coding agents guessing your architecture
· 7 minute read
AI coding agents guess your architecture because each session starts fresh and only sees the files it opens. The fix is to give them the structure as something they can read or query: a rules file for decisions, docs for intent, search for exact strings, a code graph over MCP for how the code connects, and CI checks that block what slips through.
What is the short answer?Link to What is the short answer?
Use these together. Each one answers a different part of "how is this codebase put together?"
- A rules file (
CLAUDE.mdorAGENTS.md) for decisions the code cannot show, such as which service owns payments. - Architecture docs and decision records for why the system looks the way it does.
- Code search (grep, ripgrep, your editor's search) for exact strings like an error message or a config key.
- A semantic index for fuzzy questions over prose, comments and docs.
- A code knowledge graph over MCP, such as Graphify, for callers, dependencies and what a change reaches.
- Architecture checks in CI that fail the build when a boundary is crossed.
The rest of this guide covers what each one gives an agent, and how to set them up so they work together.
Why do coding agents guess about architecture?Link to Why do coding agents guess about architecture?
Because they start every session knowing very little. Anthropic's Claude Code memory docs put it plainly: "Each Claude Code session begins with a fresh context window." What carries over is whatever you load in, such as a CLAUDE.md file and Claude's own notes.
So when an agent is asked to change a function, it knows the files it has read so far. The callers in another package, the service that consumes this one's events, the module everyone agreed never to import from: none of that is in view unless something puts it there. A model asked to fill that gap writes the most likely answer, which is how you get an import path that does not exist or an edit that skips half the callers.
Architecture questions are almost always about connections between files, which is exactly what a single file view does not show.
What does each fix give an agent?Link to What does each fix give an agent?
| Fix | What the agent gets | Best for |
|---|---|---|
Rules file (CLAUDE.md, AGENTS.md) | Instructions loaded at the start of every session | Decisions, conventions and boundaries in a few lines |
| Docs and decision records | The reasoning behind the design | Why a layer exists, what was tried before |
| Code search | Exact matches for a string | Error messages, config keys, a known name |
| Semantic index | Text that reads like the question | Fuzzy lookups over prose and comments |
| Code knowledge graph over MCP | Real edges between functions, files and modules, with file and line | Who calls this, what depends on it, what a change reaches |
| Architecture checks in CI | A failing build when a rule is broken | Enforcing boundaries on every pull request |
What should go in a rules file?Link to What should go in a rules file?
Keep it to what the code cannot tell the agent. Name the layers and who owns them, the imports that are off limits, and where new code of each kind should live. Claude Code reads CLAUDE.md, and it can read a repository's AGENTS.md in its place. AGENTS.md is an open format for guiding coding agents.
Claude Code's docs also say it treats these files "as context, not enforced configuration." A rules file steers the agent. It does not stop it, and it goes stale when the code moves. Stale CLAUDE.md and AGENTS.md files covers how to keep one honest.
When are docs and search enough?Link to When are docs and search enough?
For small repositories and single file changes, often. A short architecture doc plus grep answers most questions when everything fits in a few files. Search is also the right tool any time you need an exact string. Where it runs out is structure: a caller in another file may share no words with the function it calls, so a text match can miss it.
Where does a semantic index help?Link to Where does a semantic index help?
A semantic index splits files into chunks and returns the chunks closest to your question. It is good at "find something like this" across a lot of prose. For code structure, similar text is not the same as connected code, which why vector search isn't enough for coding agents walks through.
What does a code knowledge graph add?Link to What does a code knowledge graph add?
A code knowledge graph is built from the source itself. Functions, classes and files are nodes. Calls, imports and inheritance are edges. When an agent asks who calls a function, the answer comes from walking those edges, with the file and line of each caller, so there is nothing to guess.
This is the part of the stack Graphify does. You connect a GitHub or GitLab repository, Graphify builds the graph from the default branch, and your agent queries it over the hosted MCP server at https://api.graphify.com/mcp. Tools such as graphify_find, graphify_callers and graphify_impact answer where something lives, who calls it and what a change reaches. Every edge is tagged EXTRACTED, INFERRED or AMBIGUOUS, so the agent can tell what is written in the source from what was resolved. Graphify rebuilds the graph on every push to the default branch, so the map moves with the code. How Graphify works has the full flow.
How do you enforce the rules?Link to How do you enforce the rules?
With a check that runs on every pull request. Architecture tests and dependency linters turn a rule like "the UI layer never imports the database" into a failing build. ArchUnit does this for Java, dependency-cruiser for JavaScript and TypeScript, and Import Linter for Python. The agent learns the rule from your rules file, sees the real structure in the graph, and the check catches anything that still slips through.
How do you set this up in an afternoon?Link to How do you set this up in an afternoon?
- Write a short
AGENTS.mdorCLAUDE.md: the layers, who owns them, and two or three imports that are off limits. - Sign up at app.graphify.com/signup, connect your repository and switch on indexing. The Free plan covers 3 repositories and needs no card.
- Add the Graphify MCP server to your agent. Graphify MCP has the config for Claude Code, Cursor, Codex, VS Code and more.
- Add one line to your rules file telling the agent to ask the graph before it greps for structure. Tell your agent to use the graph has a block you can copy.
- Add one architecture check to CI for the boundary you care about most.
- Test it. Ask the agent what calls a function you know well, and what a change to it would reach. Check the answer against what you know.
Using Claude Code? Graphify and Claude Code covers what the graph adds to it and when Claude Code alone is enough. If your code has to stay on your machine, the open-source Graphify CLI builds the graph locally with uv tool install graphifyy.
What do people ask about agents and architecture?Link to What do people ask about agents and architecture?
Why do AI coding agents hallucinate about my architecture?Link to Why do AI coding agents hallucinate about my architecture?
Each session starts with a fresh context window, so the agent only knows the files it has opened and the instructions it was given. When a question reaches past those files, such as who calls a function in another package, the agent fills the gap with a likely guess.
Is a CLAUDE.md or AGENTS.md file enough?Link to Is a CLAUDE.md or AGENTS.md file enough?
It is the right place for decisions the code cannot show, such as which layer owns billing. It is not a map of every caller and import, and it goes out of date when the code moves. Pair it with a source the agent can query for structure.
What is the best way to give an agent the real structure of a codebase?Link to What is the best way to give an agent the real structure of a codebase?
Give it a code knowledge graph it can query over MCP. The graph is built from the source, so callers, imports and dependencies come back as edges with a file and line, not as a guess. Graphify builds and hosts that graph and rebuilds it on every push to the default branch.
How do I stop an agent from breaking architecture rules?Link to How do I stop an agent from breaking architecture rules?
Write the rule down for the agent, then enforce it in CI with an architecture test or dependency linter such as ArchUnit for Java, dependency-cruiser for JavaScript and TypeScript, or Import Linter for Python. Instructions guide the agent. A failing check blocks the change.
Start with Graphify at app.graphify.com/signup.