How a team keeps understanding the code its agents write
-
What to read first in an area of the codebase you have never opened
Ninety minutes, one unfamiliar area, a ticket you have to ship. The reading order that pays off fastest puts recorded decisions, assumptions and known limitations ahead of the code, and treats the blanks in the record as information.
Read → -
Our agents' context file claimed a thousand nodes. The real number was 77.
A hand-maintained context file rots like a comment, except it is injected into every agent session as authoritative and never re-checked. Ours overstated a graph by more than an order of magnitude for weeks, and it mis-scoped real work before anyone noticed.
Read → -
Reviewing the plan is not reviewing the decisions
A 417-point launch thread argued that human attention should move upstream to plan review. One of the founders disagreed with the commenter, and was right — the trade-offs that shape a system surface during implementation, after the plan is approved.
Read → -
We deleted our LLM judge instead of tuning it
The reflex when a judge underperforms is to rewrite the prompt. Measure its lift over the gate it sits on first. Ours scored 0.71–0.94 times that gate and hid 96.7 percent of a sampled cull wrongly.
Read → -
How to onboard an engineer into a codebase that agents wrote
There is no author to ask and the README describes a system that has moved. A two-week plan built on the decisions in merge order, read against a map, with a test at the end that tells you whether it worked.
Read → -
The rule teams kept for prolific humans and dropped for agents
A comment in this month's self-driving codebases thread named the rule nobody ever wrote down: volume of code has to be matched by somebody reading it. Agents got an exemption no one voted for.
Read → -
Six questions to ask before you approve a pull request your agent wrote
The diff tells you whether the change is correct. It does not tell you whether anyone still understands the system afterwards. Six questions that sit above the diff, in the order that pays off fastest.
Read → -
Why your architecture diagram changes completely after one small commit
Layered layout re-solves the whole drawing, so one node moves everything. We measured it across eight versions of a repo: 26 of 26 nodes moved without a canonical layout, 0 of 26 with one.
Read → -
Going back to coding by hand is a fix for one person, not for a team
A developer abandoned six months of agent-written work and started typing again. It worked, and it does not transfer. What a thirty-person team can take from the thread, and what it has to solve another way.
Read → -
The harness is not enough, and neither is going back to reading every line
Dex Horthy's talk on why lights-off software factories fail lands on a training fact, not a skill issue. His remedy is to read every line again. For a team, that only works if the reasoning survives the merge.
Read → -
A merged pull request is not evidence that anyone understood it
Every ownership tool you have rests on one assumption, that whoever wrote the code understands it. Agents broke that assumption, and the honest response is to stop scoring people by it.
Read → -
Most of what your agent built has no "why", because there never was one
We extract the reasoning behind agent-written changes and refuse to invent it. Measured on our own repo, 62 percent of decisions carry no alternative and no trade-off. The reasoning was not lost. It never formed.
Read → -
How to find out who on your team actually understands each part of the codebase
Git history tells you who worked where. It stops telling you who understands what the moment agents write the code. A method for building the honest picture, area by area, without quizzing anyone.
Read → -
I keep approving agent PRs I never actually reasoned about
A Claude Code hook that makes the same agent write down why it opened a PR — Decisions, Trade-offs, Assumptions, Limitations. Local, MIT, nothing uploaded.
Read →