What's the difference between AGENTS.md and an MCP server for agent context?

AGENTS.md is a static file the agent reads at session start, good for stable things like build commands and naming conventions. An MCP server is a live tool the agent calls during a task, good for anything that changes, like current decisions and constraints. Static file for the constitution, live tool for the case law.

Why not just paste the relevant docs into the prompt?

It works once and doesn't scale. Someone has to know which docs are relevant, they compete for context-window space with the actual task, and next week the pasted copy is stale. Retrieval and MCP exist to make that selection automatic and current.

How do agents get context about decisions that were never written down?

They don't, and that's the trap. A human absorbs unwritten rules from months of standups and reviews; an agent attends none of them. Whatever context lives only in people's heads is invisible to every agent you run, which is why teams adopting agents end up building a decision log first.

How do I give AI coding agents my team's context?

Three layers: a checked-in AGENTS.md (or CLAUDE.md) for stable conventions, retrieval for code and docs, and MCP for live, authoritative context like your team's approved decisions. Static files go stale; the durable move is giving the agent a tool it can call for current constraints before it writes code.

An agent's output quality tracks its context almost linearly. The same model that produces a perfect PR with your conventions in view produces a plausible-looking violation without them. The question is how to get team context in front of the agent reliably, on every task rather than once.

Why agents miss context humans have

A human engineer absorbs team context ambiently: standups, review comments, the hallway. An agent attends none of that and remembers nothing between sessions (the persistent memory guide explains why, and what the memory features do and don't fix). It sees its context window: the repo it can read and whatever you've wired in. It fills every gap with the most statistically common answer from training data. That answer is often exactly what your team decided against, for reasons the agent has no way to know.

So the job is context engineering: deciding what the agent sees, and keeping it true.

What actually works

Think in three layers, ordered by how often the content changes.

Layer 1: a checked-in instructions file. AGENTS.md, CLAUDE.md, or your tool's equivalent, in the repo root. Put in the stable, always-relevant stuff: build and test commands, code conventions, directory structure, known gotchas. Keep it short: it's loaded into every session, so every stale or bloated line costs you on every task. What belongs there, and what doesn't, is covered in AGENTS.md: what to put in it, and what it can't carry.

Layer 2: retrieval over code and docs. For "how does X work here" context, agents do well with search over the codebase and docs, and most coding tools ship this. It answers what is, cheaply and broadly.

Layer 3: a live tool for authoritative constraints. The dangerous context is what we decided: the architecture rules, the deprecated patterns, the calls made last week. This changes too often to live in a static file and is too authoritative to trust to fuzzy retrieval. Expose it as an MCP tool the agent calls at task start ("give me the approved decisions relevant to this work") so the agent begins already knowing the constraints. The trade-offs between retrieval and tools are laid out in MCP vs RAG.

One prerequisite cuts across all three layers: the context has to exist in writing. Teams discover, usually via an agent's confident mistake, that most of their real constraints were never written anywhere. Start the decision log before you scale the agents; the decision log template is a one-page starting point.

Which layer does each piece of context belong in?

Sort by how often it changes and how much it binds. A worked split for a typical web service:

Instructions file (Layer 1): pnpm test runs the suite; migrations live in db/migrations; never commit .env files. True for months, relevant to every task.
Retrieval (Layer 2): how the billing module computes proration, where feature flags are read, which helper formats currency. Discoverable from the code itself, so let the agent search for it.
Live tool (Layer 3): "new endpoints go through the GraphQL gateway, not REST" (decided last sprint), "don't extend the legacy ORM, we're migrating off it," "free tier is capped at 3 projects." Authoritative, recent, and invisible in the code until someone writes the code that obeys them.

A useful test: if the line would be wrong in three months, it doesn't belong in the instructions file. Layer 3 is also where violations come from, so it pairs with an after-the-fact check, covered in how to stop AI agents violating architecture decisions.

Where Lockstep fits

Lockstep supplies layer 3. It captures decisions from Slack and Notion where your team makes them (Jira, Confluence, and Google Docs are newer), the owner approves each in one click, and an MCP server briefs any agent (Claude Code, Cursor, whatever speaks MCP) on the approved decisions before it writes code, through a get_product_context tool call. When generated code drifts from a decision anyway, a PR check flags the conflict (a warning by default; blocking is opt-in). We're at design-partner stage, Apache-2.0 self-hostable. See how it works.