What Is Agent Readiness? Why Good Code Still Fails Autonomous Agents

The Short Answer

Agent readiness is how productively an autonomous coding agent — Claude Code, Cursor, Codex, Droid — can operate in your repository. It is determined by the scaffolding around your source code: agent config files like AGENTS.md and CLAUDE.md, reproducible installs, runnable tests, grounding documentation, and tool configuration such as .mcp.json. It is explicitly not code quality. A beautifully engineered codebase with no lockfile, no agent config, and no single test command is hostile territory for an agent, while a mediocre codebase with clear scaffolding can be automated safely.

That distinction surprises most engineering teams the first time they measure it. One of the most-downloaded packages on npm — clean, small, expertly maintained — scores 24/100 on an agent-readiness scan. Not because the code is bad, but because nothing about the project is legible to a machine that has to install it, learn its conventions, and verify its own changes without a human explaining anything.

Why Does Agent Readiness Matter Now?

Teams are handing repositories to autonomous agents at a pace that scaffolding has not kept up with. An agent dropped into an unprepared repo spends its first minutes — and a meaningful slice of its context window — reverse-engineering answers your team already knows: how to install, how to run tests, what the conventions are, which directories are generated code.

Anthropic's own guidance is direct about the cost: model performance degrades as the context window fills, and a CLAUDE.md file exists precisely to give the agent persistent context it cannot infer from code alone. Every session that starts with orientation instead of work pays that cost again. The AGENTS.md convention — now used by over 60,000 open-source projects and stewarded under the Linux Foundation — emerged because the industry converged on the same fix: answer the agent's questions once, in a file it reads first.

What Does an Agent-Readiness Score Actually Measure?

A useful score has to be anchored in checks a machine can verify, not vibes. WeaveAI Ready runs 87 deterministic checks across 8 sections, weighted by a 170-point budget that reflects how much each area affects an agent's ability to work:

Agent configs (50 points): AGENTS.md, CLAUDE.md, rules and skills — and whether they say anything useful. A config file that exists but answers nothing scores like it does not exist.

Repo hygiene (49 points): lockfiles, linter, formatter, CI, devcontainer, license. If installs are not reproducible, an agent cannot tell its own bug from environment drift. A committed credential caps this section outright.

Grounding docs (32 points): README quality, architecture docs, llms.txt, changelog — scored on whether the documented commands would actually work today.

Testing (12 points), AI context and dependencies (12 points), and prompts, skills and MCP configuration (15 points) cover the rest: whether tests assert real behavior, whether ignore files steer agents away from generated code, and whether a .mcp.json reflects what the project actually uses.

On top of the deterministic layer, a real coding agent reads the code and judges what a checklist cannot — do the documented commands match reality, do the tests assert anything meaningful. The agent can adjust the evidence but never overrule it, which keeps scores comparable across repos and across time.

How Is Agent Readiness Different From Code Quality?

Code quality tools read your source and judge its internal properties: complexity, style, duplication, type safety. Agent readiness judges the interface between your repository and an autonomous worker. The two are orthogonal in practice.

A linter cannot tell you that your README's install command fails on a clean machine, that your tests only snapshot output without asserting behavior, or that an agent editing your project will waste twelve tool calls discovering there is no formatter configured. Conversely, an agent-readiness scan does not care whether your functions are elegant — it cares whether an agent can install, orient, change, and verify without a human in the loop.

The practical consequence: refactoring sprints do not move an agent-readiness score, and readiness fixes do not require touching source code at all. The highest-leverage changes are files most teams can add in an afternoon.

What Moves the Score Fastest?

Across scans, the same small set of fixes accounts for most of the recoverable points:

Write an AGENTS.md that answers the four questions every session starts with — how to install, how to run tests, what the conventions are, what the agent must not touch.

Commit a lockfile and make the install reproducible; this is the difference between an agent debugging your code and debugging its environment.

Expose one command that runs the tests, and make at least some tests assert behavior rather than snapshots.

Add a .mcp.json for the tools your stack actually uses, so agents get structured access — to your database, your error tracker, your browser tests — instead of guessing from source.

None of these touch application code. That is the defining property of agent readiness: it is a scaffolding problem, which means it is a solvable one.