entropy-and-garbage-collection
Entropy and garbage collection — the maintenance regime an agent-driven codebase needs to survive its own throughput. Per 2026-04-27-harness-engineering-codex-agent-first: codex reproduces the patterns it finds in the repo, including the bad ones. Throughput multiplies drift. The team’s response was not to slow down the agent — it was to encode “taste” mechanically and run a continuous cleanup loop in the background.
The framing the post commits to: technical debt is a high-interest loan; paying continuously, in small installments, beats letting it accumulate and paying painfully all at once.
The problem statement
Codex’s pattern-matching is its strength and its failure mode. Every new PR mostly looks like the existing code, by design — that’s how the agent stays consistent. But it means any unbalanced or sub-optimal pattern that snuck into the repo yesterday now influences every change today. Without intervention, drift compounds.
The team’s first attempt: humans manually cleaning what they called “AI residue” every Friday — ~20% of the team’s week. The post is blunt: that didn’t scale. So they automated it.
The two-piece automated regime
| Piece | What it is | What it does |
|---|---|---|
| Golden principles | Opinionated, mechanical rules encoded directly in the codebase | Define what the cleanup loop is looking for — the gap between “what the code does” and “what it should look like” |
| Cleanup-loop Codex tasks | Scheduled background fleet of Codex runs | Scan for drift, update quality grades (docs/QUALITY_SCORE.md), open targeted refactor PRs that auto-merge in under a minute |
The cited golden principles examples are concrete:
- Prefer shared utility packages over hand-rolled helpers — centralize invariants, so a fix lands once and propagates everywhere instead of being re-derived per file.
- Don’t YOLO-probe data shapes — validate at boundaries (see architectural-invariants parse don’t validate) or rely on typed SDKs, so the agent doesn’t accidentally build on guessed structure.
The framing the post uses for these: opinionated mechanical rules to keep the codebase legible and consistent for future agent runs. Same audience as architectural-invariants — written for the next Codex run, not for human reviewers.
Why it works as garbage collection (the analogy)
The post explicitly frames the regime as garbage-collection-shaped:
不断地以小额贷款的方式偿还债务，总比让债务不断累积，再痛苦地一次解决要好得多。
(Continuously paying off the debt in small installments is far better than letting it accumulate and solving it painfully all at once.)
Three properties make the analogy fit:
- Continuous, not episodic. The cleanup tasks run on a schedule. No “tech debt sprint” that pauses feature work.
- Small, auto-mergeable PRs. Each refactor is bounded and verifiable, so most can auto-merge on green CI. Compare a quarterly tech-debt blowout, where the PR is large enough that no single reviewer can hold it in their head.
- Captures human taste, then applies it forever. Once a principle is encoded, every line of future code is checked against it. “Human taste, once captured, applies continuously to every line of code.”
Relation to other concepts
- architectural-invariants are the unbreakable rules of the codebase — enforced by lints that block. Golden principles are softer: a cleanup task acts on them, but they don’t necessarily fail CI. The combination: invariants for the load-bearing structure, golden principles for the texture.
- codebase-as-system-of-record is what the cleanup loop reads from:
docs/QUALITY_SCORE.mdand the principles document live in the repo. Without that, there’s nothing for the loop to drift against. - verifier-loop: the cleanup PRs themselves go through the same verifier loop everything else does — just with the targeted refactor as the unit of work.
- ralph-wiggum-loop: the cleanup PRs typically don’t need it (they’re small enough to auto-merge on green), but the same review-and-fix machinery is available if a refactor PR breaks something.
- harness‘s fallback component: the cleanup loop is what catches mistakes the up-front harness didn’t prevent.
”AI residue” — the named failure mode
Worth giving the failure mode its own name since the post does. AI residue is the post-throughput accumulation of:
- Sub-optimal patterns that became templates for the next 100 PRs.
- Hand-rolled helpers that should have been pushed into a shared utility.
- Type / schema drift between modules that mostly agree.
- Stale docs the agent matches against when newer code has moved on.
- Naming inconsistency that compounds with every new file.
What the cleanup loop is for is detecting these and submitting their corrections as PRs. Without the loop, the residue is the new training data for the next agent run — i.e. the failure mode is self-reinforcing.
Open questions
- The post doesn’t quantify how big the cleanup-loop fleet is, how often it runs, or what fraction of merged PRs originate from it. A future source breaking those numbers down would help calibrate the cost.
- What happens at scale when more than one agent participates in cleanup (the post mentions codex and Aardvark both work in this codebase) is open. Two cleanup agents disagreeing on the “right” pattern is a specific multi-agent failure mode worth watching for.
- The relationship between cleanup PRs and the regular feature-work PRs in measuring throughput isn’t specified. The “~3.5 PRs / engineer / day” figure on codex presumably includes both.