A repository scanned into a CLAUDE.md an AI agent can actually follow — then kept honest with drift detection and a deterministic readiness check. Offline, reproducible, no keys required.
Public · synthetic demoTeams paste a half-written CLAUDE.md once and never touch it. The code moves, the file doesn't, and the agent starts confidently following rules that are no longer true. This turns setup into a liability. The fix isn't a longer prompt — it's a generated, checkable, maintained context file.
fixtures/sample_repo_py/
src/orders_etl/{extract.py, transform.py}
tests/{test_extract.py, test_transform.py}
requirements.txt
Fully synthetic — the point is the setup method, not the code.
A deterministic scan (language, package manager, test framework, module + public-function map) writes a complete CLAUDE.md / AGENTS.md package:
## Repository Map - Language: Python · Package manager: pip · Test framework: pytest - src/orders_etl/extract.py — public functions: extract_orders - src/orders_etl/transform.py — public functions: normalize_total ## Build Command python -m compileall -q src ## Test Command python -m unittest discover -s tests -v ## Coding Rules docstring on every public function · one test file per module · credentials in env only ## Prohibited don't read/commit .env · don't weaken assertions · don't mutate input in extraction ## Definition of Done · CI smoke test · Error recovery — all included
Re-running the generator produces a byte-identical file — deterministic, reviewable, diffable.
When the repo changes, the tool flags exactly which committed claims are now false, and refreshes them:
build_command Previous: python -m compileall -q src Current: python -m build → the printed rule is now false modules Previous: [extract.py, transform.py] Current: [io.py, transform.py, validate.py] → extract.py removed; io.py + validate.py added
This is the retainer case: a maintained CLAUDE.md, not a fire-and-forget one.
| Layer | Checks | Result |
|---|---|---|
| Completeness | Map · Build · Test · Rules · Prohibited · Scripts · CI · DoD · Recovery | 9/9 |
| Command validation | build + test commands actually execute on the repo | 2/2 |
| Machine-checkable rules | module tests · public-function docstrings · no hard-coded secrets | 3/3 |
The score covers only the enumerated deterministic checks — it is not a benchmark of AI-agent output quality.
Generation, drift, and scoring are code (AST + file walk + regex), so results are reproducible and reviewable. Command validation actually runs the generated build and test commands against the repo. An optional LLM pass only polishes prose — it never makes the pass/fail decision.
· The readiness percentage measures only enumerated deterministic checks. It is not a benchmark of agent output quality. · The before/after is a single illustrative scenario, not measured model performance — no claim is made that an LLM will reliably produce either outcome. · Language detection and conventions are scoped to the synthetic Python fixture. · The secret detector is a narrow pattern check, not a security audit.