Why agents need architecture context
Claude Code and Cursor read your code very well. What they cannot read is everything your team decided that never became code: which of the three HTTP clients in the repo is the blessed one, why services must not call each other’s databases, what the retry convention is, which patterns were tried and rejected. An agent without that context produces plausible code that violates invisible rules — and you find out in review, or later.
An agent knows exactly one thing at write time: what is in its context window. The entire question of “giving Claude Code your architecture” is the question of what reliably lands there — and there are three levels of maturity in how teams answer it.
Level 1
Rules files: CLAUDE.md and friends
The right first step. A CLAUDE.md
(or Cursor rules file) in the repo is read at session start, lives in git, and costs
nothing. If you have none, add one today: conventions, blessed libraries, the three
rules everyone breaks. It genuinely improves output.
Its failure modes appear at team and multi-repo scale:
It forks. Every repo — and often every developer — carries its own copy, each frozen at the moment someone last paid attention. There is no reconciliation.
It rots silently. Nothing compares the file against how the system actually ships today. Stale guidance is worse than none — the agent follows it confidently.
It is one-way. The agent makes real decisions in every session — a library adopted, a boundary drawn — and none of them are recorded anywhere.
Level 2
An MCP context server
The Model Context Protocol (MCP) is the open standard Claude Code, Cursor, and effectively every serious coding tool now speak. Instead of a static file copied into each repo, the agent pulls context from one server at write time: current standards, architecture decision records, specs, and project rules — the same source for every developer, every repository, every session.
This solves the fork problem and the distribution problem in one move. Connecting a server is a few lines of configuration:
{
"mcpServers": {
"systemdox": {
"type": "http",
"url": "https://your-workspace.mcp.systemdox.com/mcp",
"headers": { "Authorization": "Bearer ${SYSTEMDOX_API_KEY}" }
}
}
}The agent then asks for what it needs — “the checks and specs relevant to this task” — rather than being handed whatever fits in a file. Full setup for Claude Code, Cursor, and other clients is in the MCP setup guide.
Level 3
A governed document plane
Serving context solves distribution. At organisational scale three governance questions remain: is the context still true? what did the agents decide? who is allowed to see what? A governed context layer — we call it the document plane — answers all three:
Staleness detection. Repository scanning flags documentation that no longer matches the code it describes — drift becomes a signal you receive, not an embarrassment you discover.
A return path. Agents record architecture decisions and keep specs current from inside the workflow — the missing half of every rules-file setup.
Scoped access. The API key is the boundary — a department’s key sees only that department’s context, so one team’s agents never read another’s specs.
Both audiences. The same knowledge publishes as a readable knowledge base for humans and structured context for agents — one source, no parallel wiki to drift.
This is what SystemDox is: standards git-first with GitHub as the source of truth, served over MCP, verified with checks in CI, and governed. Keep your CLAUDE.md — it is still the right place for repo-local quirks. The document plane is where the organisation-level architecture lives.
When to move up a level
Stay at Level 1 if…
you are one team in one repository and the rules fit on a page. A well-kept CLAUDE.md is enough.
Move to Level 2 when…
the same standards apply across several repositories, or two developers’ rules files have started contradicting each other.
Move to Level 3 when…
anyone asks “is this doc still true?”, “what did the agent decide?”, or “who can see this?” — governance questions a plain server cannot answer.