ai-readiness repo checklist (the bare minimum)

TL;DR
coding agents are like a new hire thats also left out of every important meeting. they see a repo's code and its commit history, but everything else (team coding standards, naming rules, insight into why a service talks to another one the way it does, etc) lives somewhere they can't read. I've set up a lot of repos for claude code and other coding agents at this point, and this post are the starting point conventions I keep coming back to.

my (non-exhaustive, always in-progress) basic conventions:

• an AGENTS.md (or CLAUDE.md) that routes the agent to the right files instead of explaining everything inline
• rules written as one-liners. with the most important ones first
• anything that has to hold is enforced by a hook, a validator, or a script, not by the text
• a running list of the bugs that actually happened (and a clean up for this to expire outdated items), each with what generalizes from it
• a status file that's the source of truth on where the project stands, with updating it required in the acceptance criteria of every coding task
• a scratchpad directory for agents' temp work, so it never lands in the real docs
• repo-local skills for the work I repeat, with descriptions that say what they're NOT for (this one heavily should depend on the project, because it might be overkill for the majority of projects)

the model isn't the bottleneck, its the context. and catching a violation when the code is generated is always better than catching it during review.

lessons learned: a rule in prose is a suggestion, and a stale rule is worse than a missing one.

a coding agent opens your repo and sees exactly 2 things: the code and the commit history. everything else, it guesses. these are the standards I use so it doesn't have to. they assume claude code, but most carry over to any agent that reads an instructions file at the repo root.

the instructions file

• write an AGENTS.md, and make CLAUDE.md a stub that points at it — every agent reads the same file, and the 2 can't drift.
• route, don't explain. 4 parts: a structure map, the build and test commands, the key rules, related repos. nothing else.
• mark the read-first files in the structure map. one line per file or directory, bold on the one that has to be read before anything else:

- `docs/architecture.md` — **read before changing anything in `src/`.** how the services talk to each other, and why
- `docs/status.md` — **read first.** what's done, in progress, and next
- `src/api/` — HTTP handlers, one file per resource
- `scripts/` — build, test, and seed scripts; use these instead of running tools directly

• point to docs instead of pasting them in. a standard that lives in a doc gets one line saying the doc exists and when it applies.
• scope rules to the files they apply to. shell-script standards go in a .claude/rules/ file scoped to **/*.sh, so they only load when the agent touches a script.

rules

• one-liners, absolute ones first, under a heading that says they can't be broken: "Treat the local database as production."
• every rule carries its reason. a rule without one gets followed literally and broken the first time a case doesn't fit.
• tell the agent what to do when a rule seems wrong: "If you find yourself wanting to violate one, that's a signal to stop and ask."

enforcement

a rule in prose is a suggestion. anything that has to hold gets enforced by something that doesn't depend on the agent remembering it.

• hooks for the rules that matter. a hook runs before a tool call and can deny it. mine block test runners outside the project's scripts, git push during automated workflows, and cd in shell commands.
• every deny says what to do instead, and points back at the instructions file:

blocked_runners="jest|eslint|tsc|vitest|mocha|prettier"

if echo "$command" | grep -qE "(^|[;&|]\s*)(npx\s+|pnpx\s+)?(${blocked_runners})(\s|$)"; then
  # deny with: "Do not run test runners directly. Use the project's npm/pnpm scripts
  # instead (e.g., 'npm run test:unit', 'npm run lint'). Check CLAUDE.md for the correct commands."

• validators for structure, with failures that name the fix: "filename does not match $shape. Rename to '$sugg'." the agent reads the message and repairs it itself.
• scripts for anything deterministic. faster, testable, and they don't spend context. if the agent does the same 4 steps the same way every time, those steps are a script.

a list of what broke

• keep a "things that have caused real bugs" section, one entry per mistake that actually happened.
• end each entry on what generalizes: a .includes() check matched 'att' inside 'attention', so always use word boundaries.
• add an entry whenever a line of text would have prevented the mistake.
• expire entries that no longer apply. an outdated entry is a stale rule.

project status and scratch space

docs drift from the code the moment nobody is required to update them. so status gets one home, and updating it is part of done.

• one status file is the source of truth, docs/status.md: what's done, what's in progress, what's next, and known gaps. it's marked read-first in the structure map.
• updating it is in the acceptance criteria of every coding task. a task isn't done until the status file matches the code:

## acceptance criteria
- [ ] endpoint returns 404 for unknown IDs, with a test
- [ ] `docs/status.md` updated to match

• enforce it, don't just ask. a CI check or a stop hook that fails when src/ changed and the status file didn't.
• agents get a scratchpad for temp work, a gitignored scratch/ directory for plans, notes, and one-off scripts. the instructions file says so, so temp work doesn't land in the repo root or the real docs.
• nothing in the scratchpad is a source of truth. anything worth keeping moves into the status file or the docs before the task closes.

skills

only when the project earns it — for most repos this is overkill.

• a skill for any multi-step task you've explained twice, in .claude/skills/.
• descriptions name the trigger phrases and end with what the skill is NOT for, so similar skills don't get confused:

name: add-endpoint
description: Add a new REST endpoint with its handler, validation, and tests. Use when asked to
  "add an endpoint" or "expose X over the API". NOT for changing the database schema (use
  write-migration).

• the skill name matches its folder name, checked by a validator.

when it doesn't work

an agent loses MCP access with no error. the tools: allowlist in agent frontmatter doesn't support wildcards — mcp__server__* is read as a literal tool name. restrict with disallowedTools: instead. permission rules in settings.json do support wildcards, which is why it's easy to assume frontmatter does too.

the agent confidently follows an outdated rule. a stale rule is worse than no rule, because the agent trusts it. keep one source file other agents point at instead of copies, and put the anti-drift instruction in the file itself: "when either side changes, re-sync so the two don't drift."

limits

none of this makes the agent right, only informed, and hooks and validators catch only what someone wrote a check for. it's per-repo too — conventions shared across repos need a shared home, like a plugin, or they drift.