Agent Readiness

Most attempts to improve an agent start with the words: “A better prompt, a longer CLAUDE.md, another skill”. When results stay flat, the artifacts pile up: prompt collections nobody can rank, documentation graveyards agents do not read, skills that never trigger. The pattern behind all three is the same mistake: communicating harder instead of removing the need to communicate. The question that unlocks progress is not “how do I tell the agent better” but “how do I build an environment where telling is unnecessary.”

This reframe matters most for the codebase itself. An agent’s quality is bounded by the environment it works in, and that environment has exactly four surfaces:

Context: what the agent can see. Not just source: production logs, issue trackers, decision records.
Tools: what it can do, per Giving an Agent Tools and the ACI.
Verification: how it knows the work is correct, per Verification & the Outer Loop.
Memory: what survives the session, per Knowledge Base and the Execution Ledger.

When an agent repeatedly produces wrong output, the gap is almost never phrasing. Diagnose against the surfaces before touching the prompt. Six named failure modes cover most cases: context starvation (the agent cannot see what it needs), context poisoning (stale or irrelevant material competes with signal; note this is starvation’s opposite, so the fix is widen access but prune what is always-on), verification gap (no fast deterministic check exists, the highest-frequency and highest-leverage gap in practice), tool poverty (a recurring workflow has no affordance), spec drift (a vague request quietly became the wrong task), and lossy handoff (knowledge died between sessions).

What a ready repository looks like

Readiness reduces to a short audit, each item either machine-checkable or falsifiable:

Verification in seconds. A change can be checked by a command that runs in under a minute. A 45-minute CI pipeline the agent cannot trigger produces hallucinated success instead of feedback.
The repository describes itself. Setup, test, and run commands are documented, and CI validates that the documentation still works. Docs that test themselves cannot rot silently.
Standards are mechanised. A style guide in prose is a suggestion; a lint rule that fails the build is a standard. Agents respect what the environment enforces, which is the same structural-over-textual argument made throughout Security and Guardrails.
Blast radius is bounded. Protected branches, feature flags, kill switches. The agent can be wrong cheaply.
Everything is reversible. One-command rollback to an immutable artifact.
Work arrives well-scoped. Tickets state the change, the acceptance criteria, and the affected area, which is exactly what Ticket Enrichment exists to produce.
Agents are first-class users. Their workflows are designed, not improvised per session; their friction is treated as a bug.

Ratcheting a legacy codebase

The objection is always the same: our codebase would fail every item. The answer is not a funded rewrite; it is a ratchet. Snapshot the current state as a baseline, then make CI fail only on regression from that baseline, never on pre-existing violations. Coverage floors, file-size caps, dependency counts, dead-code totals: each can only improve. Set the baseline from the worst current reality rather than from ideals, because a build that is red on day one gets its check disabled by day three.

Agents themselves are the workforce for the tedious part. Characterisation tests (capture what the code currently does, verify green on unmodified code, then refactor under that net) are exactly the boring, mechanical, verifiable bulk work the autonomous loop is good at.

Set expectations honestly: for a large brownfield system, the realistic twelve-month outcome is engineers who are substantially faster, not autonomous feature delivery. The readiness ratchet is what moves the ceiling after that.

Where this sits in the system

Readiness is the adoption-side complement to this book’s runtime controls. The Controls ladder governs how much autonomy an agent gets; readiness governs how much autonomy the environment can safely support. The two rise together, and the Knowledge Base adoption sequence gives the corresponding ramp for the knowledge layer.