Making a repository ready for coding agents, with checks that prove it

What an agent does not have that your engineers do

Each Claude Code session starts with a fresh context window, and other coding agents work similarly. Apart from organisation or personal instructions and memory loaded at the start, what the agent knows about your repository is what the repository tells it, plus what it finds by searching. Your engineers carry the rest in their heads, such as the environment variable that must be set, the service that has to run before integration tests and the test that fails on Mondays.

Without that knowledge the agent guesses. GitHub's documentation for its cloud agent says Copilot can find and install dependencies by trial and error, but that this is slow and unreliable and can fail completely for private dependencies. Guesses that compile still reach review, where they look like ordinary code.

Six questions a fresh checkout must answer

We ask these against a clean clone, in a container or machine that has never seen the repository. A yes needs evidence: the command ran.

• Does one documented command install dependencies from the lockfile, without prompts or tools that exist only on laptops?
• Does one command run a fast test set that gives the same result every time, with slow or flaky suites labelled and kept out of it?
• Do databases, queues and other services start from a script or container definition, with the test data the tests expect?
• Is it written down which credentials setup needs and which ones the agent session must never receive?
• Does an instruction file list the commands, the paths the agent must not edit and the conventions reviewers enforce?
• Does that file, and the agent configuration around it, have a named owner?

Make the documented commands a CI job

Instructions go stale quietly. Someone renames a script and the instruction file still names the old one. The fix is one entry point that the instruction file names and a CI job runs from a clean checkout, so a stale instruction breaks a build instead of an agent run.

#!/usr/bin/env bash
# The one command agents and CI both run from a clean checkout.
# Named in AGENTS.md; CI runs it on every change to setup files.
set -euo pipefail
pnpm install --frozen-lockfile
pnpm build
pnpm lint
pnpm test:unit

Hosted agents add their own setup layer, which needs the same treatment. GitHub runs a copilot-setup-steps.yml workflow before its cloud agent starts, and only from the default branch. If a setup step fails, the agent skips the remaining steps and starts work in whatever state the environment is in, so a broken setup shows up as odd agent behaviour, not a red build. The workflow also runs as a normal check when it changes and can be started by hand, which makes it testable.

In OpenAI's Codex Cloud, Codex prepares and tests an environment with you, and publishing captures the prepared filesystem that new tasks start from. Changes to that prepared setup reach new tasks after you republish, and existing tasks keep their own files. Some saved configuration applies to the active setup immediately, so check which kind of change you made before you test.

What the instruction file should and should not say

Claude Code's documentation asks for instructions concrete enough to verify, such as the exact test command, and suggests keeping each CLAUDE.md under 200 lines because longer files cost context and reduce adherence. Cursor's rules documentation advises against copying style guides that a linter can enforce. What the file needs is short:

• Install, build, lint and fast-test commands, exactly as CI runs them
• Paths the agent must not edit, such as generated code, vendored dependencies and merged migrations
• Conventions reviewers enforce that differ from common defaults
• What done means: the checks that must pass and what the pull request description contains

Several tools now read AGENTS.md. Claude Code reads it when no CLAUDE.md is present, Cursor supports it in the root and in subdirectories, and GitHub's cloud agent reads AGENTS.md files next to its own instruction files. One shared file with thin tool-specific additions avoids three copies drifting apart. None of these files enforce anything: Claude Code's documentation says it treats them as context, so a rule that must hold belongs in permissions, hooks or CI.

From the answers to a working rule

The answers decide how agents may work in a repository. This is the rule we apply:

• All six answered yes: candidates for delegated tasks a reviewer can verify, with review and required checks unchanged.
• Setup works but tests are flaky or slow: interactive work only, with an engineer reading test output, until the fast test set is stable.
• A clean checkout does not build: fix that first, because an agent there spends its budget rediscovering setup.

In a hypothetical service repository, a checkout needs a local Postgres that engineers started months ago and a token for a private package registry. The fixes are a container definition for the database, a registry credential available to setup only and the agent-check script above, each as one reviewable change.

What readiness does not fix

A ready repository removes guessing about the environment. It does not make vague tasks clear, add review capacity or make agents suitable for work that needs deep domain judgement. Repositories that depend on licensed tools, special hardware or internal systems may not fit a shared hosted sandbox, but that does not rule out delegation. GitHub's cloud agent can run on self-hosted runners with access to internal resources, recommended as ephemeral single-use runners, and a self-hosted or local setup works if it is reproducible and has the same permissions, checks and review. Only when none of that is possible is interactive local use the fallback.

When agent changes pass locally and fail in CIHarness engineering