Part 4 · 1 chapters · ~8 min

A Legible Codebase

The properties that let a newcomer, human or agent, change code correctly: names that say what things are, visible enforced boundaries, local reasoning, fast trustworthy checks, decisions written down, and exemplars to copy, with a module README written for that reader.

5

Making code readable to engineers and agents alike

legible to a capable newcomer
  1. Names that say what things are.
  2. Boundaries that are visible and enforced.
  3. Local reasoning: one file is enough to understand a change.
  4. Fast checks that people trust.
  5. Decisions written down where they are needed.
  6. Exemplars to copy, and deprecations marked.
code
# payments/README.md: what an agent (or a new hire) needs before changing this module
## owns
Transfers to other banks: initiation, holds, provider routing, status, reversal.
## does not own
Balances (ledger/), fees (pricing/), notifications (notify/). Call their public APIs only.
## invariants
- amounts are Money (integer kobo + currency); never number
- every provider call carries the transfer's idempotency key
- a transfer in PENDING is never shown as failed; see docs/states.md
## change safely
- new provider: implement PaymentProvider (src/providers/port.ts); copy src/providers/paystack.ts
- tests: npm test -- payments ; contract tests: npm run pact:payments
- anything touching holds or reversal: assisted mode only, two reviewers (see ai-policy.md)
## decisions
ADR-012 provider routing by bank code · ADR-019 hold expiry 15 min · ADR-023 no client retries on 5xx
the payoff
Every item on this page was good engineering before agents existed. Agents raise the return on it, because they read the codebase more often than any person does, and they copy whatever is there.
A LEGIBLE CODEBASE
the properties that let a newcomer, human or agent, make a correct change without reading everything
swipe the figure sideways, or tap expand for full screen
1/6
names
Names that say what things are: transferHoldAmountKobo beats amt; a module called ledger-posting beats utils2. Agents and people both pattern-match on names; a misleading name produces a confidently wrong change.