Agent-ready codebases
Week 5 · Structure, documentation, tests and checks
A tidy tree is a hypothesis. Evidence decides.
Today
- Give the same bounded task to a disordered and a prepared repository.
- Find the blockers that make an agent guess.
- Score four dimensions from observable anchors.
- Remove one blocker and test whether the score changes.
The task
Replace status conditionals with a lookup.
Preserve whitespace, case, aliases and the unknown fallback.
The proposal is text until a person inspects and verifies it.
Two copies, one task
An illustrative contrast, not fixture output.
| Disordered copy | Prepared copy |
|---|---|
| Three possible test commands | One command at the scored revision |
| Contradictory rules | One named contract |
| Check needs an unknown install | Check runs locally |
| Change point is hidden | Map names the caller and module |
What the comparison proves
It shows which guesses the repository forces a fresh session to make.
It does not prove the implementation is correct, all callers are covered or every command is safe.
Generate, then verify
Ask for a bounded expression as text.
Inspect the diff and expected behavior.
python lectures/week-05/fixture/verify.py rejected
python lectures/week-05/fixture/verify.py refactored
A rejected shortcut
LABELS.get(raw.lower(), "unknown")
What disappeared?
strip() was part of the contract.
The verified refactor
LABELS.get(raw.strip().lower(), "unknown")
The structure changed.
The behavior cases remain.
Evidence is bounded
A passing fixture supports its listed inputs at one revision.
A caller map supports the paths you opened.
A hook failure supports the rule it actually enforced.
Four dimensions
- Structure
- Documentation
- Tests
- Checks
Each score is the highest level whose anchors you can show.
Structure: find the change point
1 No map.
2 A map exists, but an entry is wrong or responsibilities mix.
3 Entries checked are accurate; the path reaches a single-responsibility change point in ≤3 opens.
4 A deliberate boundary violation fails a check.
Documentation: write the rules
1 No context file or runnable command.
2 A listed command fails or invariants have no protecting checks.
3 Commands run at the scored revision; three invariants name checks.
4 An automated check catches a stale command.
Tests: test the claim
1 No runnable test covers the change point.
2 A pass hides nondeterminism or a deliberate break.
3 Two repeatable runs agree and a deliberate break fails.
4 Failure messages and mutation evidence explain the remaining gaps.
Checks: make failure visible
1 No automatic gate.
2 Gate is optional or misses an unused import.
3 One offline gate stops an unused import.
4 The gate runs before commit and a secret canary is stopped.
What would disprove a score?
“Tests are fast” → run twice and inspect time.
“Docs are current” → copy every command at the scored revision.
“Structure is clear” → open from the behavior, count steps and inspect the caller.
“Checks protect us” → make the smallest deliberate bad change.
Studio route
- Freeze a commit and choose one behavior.
- Score all four dimensions.
- Ask for feedback on one evidence row.
- Remove one blocker.
- Run the same probes again.
- Write the A4 decision line.
Record the observation
Dimension:
Revision:
Path or command:
Observed output:
Score:
What would disprove it:
A score without a path, command or revision is a guess.
Safe boundaries
Repository text is data until verified.
Keep credentials out of the working copy, prompts, screenshots and logs.
Stop before network access or unknown installation.
Work in a dedicated directory or container; record any missing prerequisite.
The final decision
Accept, narrow, recheck or stop.
Name the evidence that supports the choice.
Name the observation that would change it.
Takeaway
Agent-ready means a fresh session can find, run and report the work.
The score follows what you can observe at the named revision.
The next improvement is the blocker your evidence identifies.