All guides

Agent context

How AI coding agents get context about your codebase

Coding agents only write good code when they understand your repository: build commands, conventions, architecture, and the docs that explain them. This guide covers the main ways teams feed that context - static rule files, repo instruction Markdown, search/RAG, and MCP - and where each approach breaks down.

Last reviewed: July 2026

Why agent context matters

A general-purpose model does not know your auth middleware, package layout, or the command that actually runs tests in CI. Without project context it invents plausible patterns from training data - often wrong for your stack.

Context is everything you inject so the agent can act like a teammate who already onboarded: conventions, verified commands, architecture notes, API shapes, and "do not do this" guardrails.

The main ways teams supply context today

Most teams mix several of these. Knowing the tradeoffs keeps you from stuffing the entire monorepo into every prompt.

  • IDE rules and system prompts: Cursor rules, custom instructions, and similar files apply standing guidance. They are easy to start and easy to let go stale.
  • Repo instruction files: AGENTS.md and CLAUDE.md tell agents how to work in this repository - commands, layout, PR expectations. Write once, many tools can read them (with caveats - see our comparison guide).
  • Open files and @-mentions: Developers manually attach the files they think matter. Precise for a single task, not a scalable memory of the system.
  • Search and RAG over the repo: Chunked retrieval pulls similar code or docs into the prompt. Useful for "find me something like X," weaker for stable conventions and doc gaps.
  • MCP servers: Model Context Protocol servers expose tools and resources the agent can query on demand - docs search, conventions, issue trackers, browsers - without pasting everything up front.

Static context vs queryable context

Static context is push-based: you decide what goes into the rules file or system prompt before the task starts. It is simple and cheap until the file is wrong or too large.

Queryable context is pull-based: the agent asks for what it needs mid-task. MCP tools and good repo search work this way. They scale better for large codebases because you do not burn the whole context window on every turn.

In practice you want a small static layer (always-on commands and hard rules) plus a queryable layer (living docs, conventions, and gap lists for your private code).

What good private-repo context looks like

Public library docs (for example via a docs MCP for open-source packages) solve only half the problem. Your agent still needs private-repo truth:

  • Conventions: How this team names modules, handles errors, structures packages, and writes tests.
  • Verified commands: Install, build, lint, and test commands that actually work in this repository.
  • Architecture and domain docs: What the system does, where the boundaries are, and which services own which data.
  • Gaps and drift: What is undocumented or out of date, so the agent does not treat a missing page as "there is nothing to know."

Common failure modes

Context systems fail in predictable ways. Designing against them matters more than picking a fashionable tool name.

  • Stale rules: AGENTS.md still documents the old test runner. The agent confidently runs the wrong command.
  • Context bloat: Too many MCP servers or a huge rules dump floods the model with tools and text it cannot prioritize.
  • Wrong retrieval: RAG returns a similar but outdated module, and the agent copies patterns you already removed.
  • No citations: The agent asserts conventions without a path back to source or docs, so humans cannot verify.

How-to

How to improve AI coding agent context

  1. 1

    Write a short AGENTS.md

    Capture build and test commands, layout, and non-negotiable conventions. Keep it scannable. If you use Claude Code, point CLAUDE.md at the same source of truth.

  2. 2

    Add only the MCP servers you need

    Start with two or three: often a docs/context server for your repo, plus whatever you debug against (errors, browser, database). Avoid connecting everything at once.

  3. 3

    Prefer queryable docs over pasting folders

    Let the agent fetch conventions and architecture pages on demand instead of stuffing large trees into every chat.

  4. 4

    Keep the source of truth current

    When code merges, regenerate or repair the docs and instruction files those agents read - otherwise you automate the wrong instructions.

Where Moxie Docs fits

Moxie Docs indexes your GitHub repository into living, source-cited documentation and serves that context over a first-party MCP server - conventions, docs, gaps, and verified commands scoped per repository. Pair it with a thin AGENTS.md for standing rules; let MCP handle the deep, current picture of your private code.

See the Moxie Docs MCP serverCompare plans

FAQ

Frequently asked questions

Quick answers to the questions developers ask about AI coding agent context.

How do AI coding agents get context about my codebase?+

Through a mix of open files, IDE rules, repo instruction files like AGENTS.md or CLAUDE.md, search/RAG over the repository, and MCP servers that expose tools and docs the agent can query during a task.

What is the best way to give Cursor or Claude Code project context?+

Use a short standing instruction file for commands and hard rules, then connect a queryable source of private-repo docs and conventions - ideally via MCP - so the agent can pull accurate detail without bloating every prompt.

Is AGENTS.md enough for agent context?+

AGENTS.md is a strong front door for commands and conventions, but it cannot hold your entire architecture and it drifts if nobody updates it. Most teams combine a lean AGENTS.md with searchable or MCP-served living docs.

What is MCP context for coding agents?+

MCP (Model Context Protocol) lets an agent call external tools and read resources through a standard interface. A codebase docs MCP can return conventions, documentation pages, and gaps on demand instead of embedding the whole repo in the system prompt.

Why does stale documentation hurt AI agents more than humans?+

Humans notice when a page feels wrong and ask a teammate. Agents treat retrieved text as authoritative and will confidently apply outdated patterns at scale until someone stops them.

Keep reading

Related guides

Get started

Give your agents real codebase context.

Connect a repository and Moxie Docs generates living documentation and serves it to your agents over MCP. 14-day free trial, no charge today.

Connect GitHubView pricing