Is your repo agent-ready?

An AI agent like Claude Code is only as good as the context it finds in your repo. You give it a task, and before touching anything it has to answer: what is this?, how is it organized?, how are things done here?, where do I touch?

Instrumenting a repo is answering those questions upfront, written down where the agent will look for them. An instrumented repo turns the agent into an engineer who knows your code. One that isn't leaves it guessing — and guessing is hallucinating.

This checklist measures that across 16 points in four blocks. It scans nothing: you answer, honestly, about the real state of your repo.

• Documentation (CLAUDE.md) — the map: what's there, how it's built, what rules to follow. Per feature, not just at the root.
• Configuration (.claude/) — commands, skills, validation hooks and connected tools (MCP).
• Structure & navigability — feature-based organization, clear naming, isolated vendor code. So the agent finds its way without getting lost.
• Verification & safety — tests, type-check, lint, PRs and secrets out of the code. So the agent validates its changes without breaking or leaking anything.

The most common mistake is a single giant CLAUDE.md at the root. It works on a small project, but as you grow the agent has to load the whole world's context to touch a single feature — and the important bits get lost.

The alternative is a tree of CLAUDE.md files: one at the root with the general map, and one per feature or module with the local context. So when the agent works on 'payments', it reads the payments CLAUDE.md and nothing else. Just enough context, in just the right place.

The red flag is large folders (>500 lines) without any nearby CLAUDE.md: that's where the agent improvises. Cover those first.

This checklist tells you what's missing. The next step is fixing it — and an agent can do that too.

I'm building a tool for exactly this: you paste a prompt into your Claude Code, it pulls in the flow, actually audits your repo (counts CLAUDE.md files, undocumented folders, code/doc ratios), shows you the plan and creates the missing CLAUDE.md files — reading your real code and always with your confirmation. It never touches product code.

In the meantime, use this checklist to know where to start.

You don't have to do it all at once. The order that moves the needle most:

1. Root CLAUDE.md if you don't have one — the entry map.
2. The large undocumented folders — the blind spots where it hallucinates most.
3. A validation hook (type-check + lint post-edit) — so the agent self-corrects.
4. Skills/commands for what you repeat — stop explaining the same thing every time.

With those four, most repos jump from 'not ready' to 'ready' in an afternoon.