The short version: an AI coding agent starts every task nearly blind to your system's shape. CLAUDE.md and AGENTS.md are plain-text files that hand the agent standing context; MCP lets it pull live context on demand. Give it an accurate architecture map through either channel and the quality of its work goes up sharply. This post explains what each one is, when to use which, and how to keep the map from going stale.

Why your agent keeps guessing

Watch a coding agent work and you'll notice it spends the first chunk of every task orienting: grepping for files, opening configs, inferring what talks to what. It's reconstructing your architecture from raw source, one file at a time, from zero, every single session. It has no memory of the map you carry in your head.

The gap agents fall into: the code is visible, but the context that matters isn't.

That reconstruction is lossy. The agent can see that api/ imports a Postgres client; it can't see that there are three databases and this one is the analytics replica you must never write to. It can see a stripe import; it can't see that billing is owned by a different team and changes there need review. The gap between "what's in the code" and "what a senior engineer knows about the system" is exactly where agents make confident mistakes.

The fix is to stop making it guess. Hand it the map.

The two channels: standing context vs. live context

There are two ways to give an agent context, and they're complementary.

Standing context (a file read every session) and live context (queried over MCP).

CLAUDE.md and AGENTS.md: the onboarding doc

These are just Markdown files in your repo. The agent reads them automatically at the start of a session, so they're the right home for things that are true across many tasks: the tech stack, the directory map, key conventions, and, crucially, the architecture. What are the services? What depends on what? Who owns which piece? What must never be touched?

AGENTS.md is the emerging cross-tool convention; CLAUDE.md is the same idea for Claude-based workflows. Many teams keep both, often with one pointing at the other.

A strong architecture section in one of these files reads less like prose and more like a briefing:

Copy## Architecture
 
- web (Next.js)  → api          — owned by @frontend
- api (Node)     → db, cache     — owned by @platform
- db (Postgres, primary)         — DO NOT run migrations without review
- analytics-db (Postgres, replica) — READ ONLY
- worker         → db, queue     — owned by @platform
 
Payments flow through `api` only. Never call Stripe from `web`.

Notice how much of that an agent could not have inferred from the code alone. That's the value.

MCP: asking a teammate a question

The Model Context Protocol lets an agent call out to a server for context at the moment it needs it. Where AGENTS.md is a document the agent reads once, MCP is a live connection it can query mid-task: "list the services," "what's downstream of api," "what does this cost." It's ideal when the data is large, changes often, or is better queried than dumped into a file.

The two work best together: put the durable big picture in AGENTS.md, and wire up MCP for the live, queryable detail.

The catch nobody mentions: the map has to be true

Here's the trap. A hand-written AGENTS.md architecture section is a diagram in disguise, and it drifts exactly like every other diagram. You write a beautiful architecture briefing on Monday, ship three services by Friday, and now your agent is confidently reasoning about a system that no longer exists. A wrong map is worse than no map, because the agent trusts it.

So the real problem isn't "how do I write an AGENTS.md." It's "how do I keep the architecture in it accurate without hand-editing it forever." And that lands you right back on the core principle: the map should be generated from a source of truth, not maintained by hand.

Closing the loop with a living map

This is the part where the two ideas meet. If your architecture already lives as structured data (nodes, edges, ownership, spend), then both agent channels come almost for free:

• Standing context: export the map to CLAUDE.md / AGENTS.md and commit it. Regenerate on change so it never drifts.
• Live context: serve the same map over an MCP server so agents can query services, dependencies, and cost in real time.

That's exactly how we built Canopy: your architecture is a structured map, and it exports CLAUDE.md / AGENTS.md and serves a read-only MCP server with tools like get_architecture, list_services, get_spend, and find_dependencies. One source of truth, both channels, always current.

You can absolutely hand-roll this. The point isn't the tool, it's the shape: one accurate, structured map, delivered to your agents through both a file and a live connection.

FAQ

What is a CLAUDE.md file?

CLAUDE.md is a Markdown file in your repository that gives Claude-based coding agents standing context about your project: the stack, conventions, directory layout, and architecture. The agent reads it automatically at the start of a session so it doesn't have to reconstruct everything from source.

What's the difference between CLAUDE.md and AGENTS.md?

They serve the same purpose, persistent context for AI coding agents, but AGENTS.md is the emerging tool-agnostic convention adopted across many agents, while CLAUDE.md is oriented at Claude workflows. Many teams maintain both, and the content overlaps heavily.

When should I use MCP instead of an AGENTS.md file?

Use AGENTS.md for stable facts the agent should always know. Use MCP for context that's large, frequently changing, or better queried than dumped into a file, like live service inventories, dependency graphs, or cost data. In practice you use both: a file for the big picture, MCP for live detail.

How do I stop my agent context from going out of date?

Don't hand-maintain the architecture section. Generate it from a structured source of truth (a data-backed architecture map) and regenerate on change, or serve it over MCP so the agent always reads the current state. Hand-written architecture docs drift; generated ones don't.

Does giving an agent architecture context actually improve its output?

Yes, noticeably. Much of an agent's early effort goes into inferring system shape, and its worst mistakes come from inferring it wrong. Supplying an accurate map removes that guesswork, so the agent spends its budget on the actual task and makes fewer architecture-level errors.

Canopy turns your architecture into structured data and exports it straight to CLAUDE.md, AGENTS.md, and MCP, so your agents always have the real map. Explore Canopy from 8StarLabs.