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. 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.

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. When generated code drifts from a decision anyway, it gets caught at the PR. We're at design-partner stage, Apache-2.0 self-hostable. See how it works.