The Agent-Ready Repository: Fast Checks, Clear Boundaries, Short Instructions

Put the same coding agent in two repositories with the same task and you’ll often get very different results. The model is the same. The difference is how much the repository helps the agent find its way, check its own work and stay inside the lines. Most of what makes a repository agent-ready also makes it easier for a new hire, which is a good way to justify the work.

1. One command that runs the agreed checks

An agent’s most useful capability is running a check and reading the result. Give it one command that runs everything that matters:

make check    # or: npm run check, just check, ./scripts/check

It should run formatting, lint, type checks and tests, exit non-zero on any failure, and print failures in a form that’s easy to act on. Then say in the instruction file that the task isn’t done until make check passes.

Without that, agents guess. They run part of the test suite, miss the linter, or decide their change is “complete” from reading the code. With it, the agent can attempt repairs against the same checks a reviewer will run. Passing those checks is evidence about their coverage, not proof that the change is correct.

2. Make the feedback fast

An agent iterates the way a person does: change, check, read, change again. If the check takes twelve minutes, it gets run once at the end, or not at all.

• Make it possible to run the tests for one package or file (make test PKG=billing), and document how.
• Keep unit tests free of network and cloud dependencies so they run in seconds, locally, in a sandbox.
• Separate slow integration tests behind their own command, run in CI.

Measure how often the checks run during a task and which defects they catch. A 30-second suite is useful only if it exercises the behavior being changed; keep the slower checks in the release gate.

3. Boundaries the agent can see

Agents take the path of least resistance. If generated code, vendored dependencies and infrastructure definitions all look like ordinary source files, the agent will edit them as readily as anything else.

• Mark generated files with a header (“GENERATED, do not edit; run make gen”), and add a CI check that fails if they differ from a fresh generation.
• Use CODEOWNERS for sensitive paths such as infra/, auth/ and billing/, and enable required code-owner review in branch protection or a ruleset. The file alone requests reviewers; it does not prevent merging.
• Put high-risk rules in CI, not only in prose. A policy check that fails the plan on unconditioned iam:PassRole (example) protects you when the agent doesn’t read, or doesn’t follow, the instructions.

4. Short, specific instructions

Repository instruction files (AGENTS.md, or CLAUDE.md for Claude Code) can supply recurring guidance. Loading, scope and precedence depend on the tool and the working directory; confirm which instructions it actually loaded. Keep it short and specific:

# AGENTS.md

## Commands
- `make check`: must pass before a task is complete
- `make test PKG=<name>`: fast tests for one package

## Layout
- `services/<name>/`: one deployable service each; no cross-service imports
- `infra/`: Terraform only. Never create resources outside it.
- `gen/`: generated; edit the `.proto` files and run `make gen`

## Rules
- Money is integer cents (`int64`), never floats.
- Every IAM role needs a comment stating its blast radius.
- New HTTP endpoints need an entry in `docs/api.md`.

Leave out anything the code already makes obvious, aspirations (“write clean code”), and specialised procedures that matter only occasionally. Those belong in skills, which load only when the task needs them (more on that split).

5. Code that explains itself locally

Agents read files, not your team’s shared memory. The patterns that help:

• Consistent structure across similar modules. If every service has the same layout, an agent that has seen one understands them all.
• Types at boundaries. Typed request and response models, typed config. Type errors are feedback the agent gets for free.
• Comments that explain why, next to surprising code. “Reconcile an unknown payment outcome before retrying; preserve the approved operation ID” explains the invariant. Enforce it in tests and the execution layer as well. A lower retry count alone does not prevent duplicate effects.
• Examples near abstractions. A short usage example in the docstring of an internal library saves the agent (and people) from reverse-engineering it.

6. Somewhere safe to run things

Agents that can run the application and its tests do much better than those that can only read code. Give them a sandbox: a dev container or a docker compose setup with local stand-ins for databases and queues, and no production credentials anywhere in reach. The agent can then reproduce bugs and verify fixes instead of guessing.

Where this stops

An agent-ready repository makes good results more likely and bad ones easier to catch. It doesn’t replace review. It changes what review is for: checking intent and design, while still checking whether the automated checks cover the changed behavior. If your reviewers are still spending their time on formatting and failing tests, the repository isn’t finished.