Codebase agent readiness checklist
Most agent failures trace back to the same boring stuff: a bloated AGENTS.md, stale commands, no linting, secrets in the wrong place. This checklist covers all of it. Work through it once and your codebase is ready.
What's inside
AGENTS.md structure
A bloated AGENTS.md is a tax on every message you send. One of my projects went from 21,500 tokens to 750 after a cleanup pass. The checklist covers what belongs in the file, what to cut, and how to split context hierarchically across a monorepo.
Scripts as interface
Agents already read package.json. A well-named script (db:generate, db:migrate) is clearer than four paragraphs of prose in AGENTS.md. The checklist covers
which scripts to expose and which to leave out.
Permissions and secrets
Common ways secrets leak into logs or prompts, what least-privilege tool access looks like in practice, and the permission mistakes I see on almost every codebase.
Infrastructure
Deterministic tools beat prose rules. Linting, type checking, and tests give the agent immediate feedback instead of letting it guess and commit broken code. The checklist covers what to set up and how strict to make it.
CI hooks and drift prevention
AGENTS.md drifts. On a recent client project, the file still referenced Kysely after the team had migrated to Drizzle. The agent ran the wrong migration command for weeks before anyone noticed. The checklist covers the CI checks and CODEOWNERS rules that catch drift before it compounds.
Team rollout
Who owns the AGENTS.md, how to onboard the rest of the team, and how to run a review cadence that stays realistic over time.
Good fit if
- You're setting up agents on a codebase for the first time and want to do it right.
- You have agents running but they keep making the same mistakes or running stale commands.
- You're a tech lead trying to standardize the setup across the team.
- You want to understand the full picture before committing to a bigger engagement.
Read first (free)
The checklist is the condensed, actionable version of my writing on this. If you want to understand the reasoning before buying, these three posts cover it:
- Your AGENTS.md can be shorter now What to keep, what to cut, and hierarchical setup.
- The infrastructure around your agent Linting, type checking, tests, scripts as interface.
- Coding agents at team scale Drift prevention, ownership, maintenance cadence.