How to Prepare a Repository for Coding Agents: AGENTS.md, CLAUDE.md, and MCP

The Short Answer

To prepare a repository for coding agents, add four things: an AGENTS.md that answers how to install, run, test, and contribute; a committed lockfile so installs are reproducible; one command that runs the tests; and a .mcp.json that gives agents structured access to the tools your stack uses. Those four changes cover the majority of what separates a repo agents work well in from one they flail in — and none of them touch your application code.

Everything below is the expanded version: what goes in each file, the mistakes that make a config worthless, and the order to do it in if you only have an afternoon.

What Should AGENTS.md Actually Contain?

AGENTS.md is a README for agents — the file coding agents read before touching your code. The convention is supported by OpenAI Codex, Google Jules, Cursor, Factory and others, and is in use across more than 60,000 open-source projects. The failure mode is not missing the file; it is writing one that answers nothing. An AGENTS.md that says 'this is a web application, please write clean code' scores the same as no file at all, because the agent still has to discover everything itself.

A useful AGENTS.md answers, concretely:

Install and run: the exact commands that produce a working environment from a clean checkout, including required versions and environment variables (point to a .env.example, never real values).

Verification: the one command that runs the tests, plus lint and typecheck commands if they exist. This is what lets an agent check its own work instead of declaring victory.

Conventions: naming, file layout, patterns the codebase follows — the things a senior teammate would correct in review.

Boundaries: directories the agent must not edit (generated code, vendored trees, migrations), and anything that requires human sign-off.

Keep it current the way you keep CI current: when a command in AGENTS.md stops working, that is a broken build for your agents.

Do I Need CLAUDE.md Too, or Just AGENTS.md?

CLAUDE.md is Claude Code's native config file — read automatically at the start of every conversation, giving the agent persistent context it cannot infer from code alone, per Anthropic's own guidance. AGENTS.md is the cross-tool standard. If your team uses one agent exclusively, its native file is enough. If you use several — or your open-source users do — carry both, with one line in CLAUDE.md importing or restating the shared content so the two never drift.

The same logic extends to tool-specific rule files (Cursor rules, Copilot instructions): duplicate the minimum, keep the substance in one canonical place, and treat drift between them as a bug.

How Do I Configure MCP Servers for My Stack?

MCP — the Model Context Protocol — is how agents get structured access to systems beyond the filesystem: your database, your error tracker, your browser test runner, your docs. A .mcp.json committed at the repo root tells every MCP-capable agent which servers to start and how.

The principle for choosing servers: mirror what the project already depends on. If the codebase uses Supabase, an agent with the Supabase MCP server can inspect schema instead of guessing from types. If Playwright is in the devDependencies, the Playwright server lets the agent actually run and debug browser tests. If Sentry is wired in, the agent can read the production error that motivated the change request. Servers for tools you do not use are noise — they enlarge the agent's decision space without adding capability.

This is mechanical enough that it should not be hand-authored: WeaveAI Ready's scan detects the stack and generates a ready-to-paste .mcp.json as part of every report, and agents themselves can request one via Ready's own MCP server.

What Repo Hygiene Do Agents Depend On?

Agents amplify whatever reproducibility problems your repo already has, because they cannot shrug and ask a teammate. The hygiene layer that matters most:

A committed lockfile. Without pinned dependencies, an agent cannot distinguish a bug it introduced from drift the install introduced. This is the single most common high-severity finding in scans.

A configured linter and formatter. These convert style questions from judgment calls into machine-checkable rules — exactly the kind of feedback loop agents thrive on.

CI that runs on pull requests. The fix an agent proposes is only trustworthy if something independent verifies it.

Scoped ignore files. .gitignore for artifacts, plus agent-scoped ignores that keep generated code and vendored trees out of the context window entirely.

No committed secrets. A credential in history is an incident regardless of agents — but an autonomous agent reading and echoing it multiplies the exposure. Scanners treat this as an automatic cap on the score, and so should you.

What Order Should I Do This In?

If you have one afternoon: commit the lockfile, write AGENTS.md with the four answers above, expose a single test command, and add .env.example. That is the difference between an agent orienting for ten minutes versus starting work immediately.

If you have a day: add the .mcp.json for your detected stack, wire lint and typecheck into one verification command, and add the agent-scoped ignore files.

Then measure it. A scan gives you the ordered work list with file-level evidence — and re-scanning after each fix shows exactly which changes moved the score, which turns readiness from a one-time cleanup into something your team can hold steady.