Today's front page had an Ask HN titled "How to deal with shipping AI-written code you don't understand?" — 246 points and nearly 400 comments. That ratio is the story. People aren't asking whether the code works. They're asking what happens afterward, when it works and nobody can say why.
That question lands at a layer we haven't covered. Custody (#65) asked whether the asset is in your hands. Provenance (#64) asked whether the bytes are the bytes you think. Comprehension asks the one that actually determines whether you can operate the thing: do the people who own this system understand it well enough to change it under pressure?
Why comprehension is a layer, not a feeling
Every system has two costs. The one you pay to build it, and the one you pay every time reality changes and the system has to answer for itself. AI assistance attacks the first cost hard and the second cost quietly. The bill arrives as a shape, not a number: incident response gets slower, changes get riskier, the on-call rotation gets quieter in the wrong way.
Comprehension debt is not "bad code." Bad code you can read and hate. Comprehension debt is code that reads fine, passes tests, ships, and has no human who can predict what it will do in a situation the tests don't cover.
- Green tests are not understanding. A test asserts that behavior you thought of once still holds. It says nothing about the path nobody thought of. When the model wrote both the implementation and the test, you have two artifacts agreeing with each other, which is not the same as either being right. Coverage measures the questions you asked, not the ones you didn't.
- The debt compounds in the debugging phase, not the writing phase. Generation is fast and review is slow, so we optimize the part that was never the bottleneck. The cost shows up months later, at 2am, when the fix requires knowing why the retry loop has that particular backoff and the only honest answer is "it was in the diff and it looked right."
- Ownership is a legal fact, not a technical one. Once it's in your repo and your name is on the commit, "the model wrote it" is not a defense anyone accepts — not your incident review, not your customer, not a regulator. You inherit the obligation to explain it whether or not you inherited the understanding.
- The reverts tell the truth. Another post today: "The reverts will continue until morale improves" (192 pts). Reverts are comprehension failing in public — someone shipped a change whose blast radius nobody modeled, and the fastest recovery was to undo it. A team that reverts often isn't careless. It's a team discovering, repeatedly, that it doesn't know what it deployed.
What actually helps
None of this argues for writing everything by hand. It argues for putting the understanding cost somewhere deliberate instead of letting it accumulate invisibly.
- Make the explanation the artifact. Require a short written model of any non-trivial AI-assisted change: what it does, what invariant it preserves, what it assumes about the world, and how you'd know it broke. If nobody can write three sentences, the change isn't ready, however green the tests are.
- Review for the model, not just the diff. A diff review asks "is this line correct?" A comprehension review asks "can I predict this module's behavior in a case the author didn't consider?" If you can't, that's the finding — not a nitpick.
- Keep a human-authored skeleton. Interfaces, data models, invariants, and failure modes should be written by someone who will be paged. Let generation fill in the middle. The skeleton is what makes the middle reconstructable.
- Instrument before you need it. Traces, structured logs, and per-call cost attribution turn "it did something weird" into a question with an answer. Agentic observability tooling is showing up on the front page for a reason (today: "Agentic Monitoring," a YC launch that finds errors in agent traces). Buy the visibility before the incident, not during it.
- Budget the explanation, not just the tokens. Token usage may be plateauing, but review capacity is the real constraint and it doesn't scale with model throughput. If a team ships 3x the code with the same reviewers, it has chosen to understand a third as much.
- Practice the re-derivation. Once a quarter, take a critical module and have someone who didn't write it explain its behavior and change it. If that fails, you don't have a codebase — you have an executable rumor.
The uncomfortable trade
There's a version of this argument that turns into "slow down," which is useless advice in a market that won't slow down. The workable version is narrower: you can outsource the typing, but not the ownership. Speed is a legitimate advantage, and comprehension is the price of keeping it after the first incident.
Teams that get this right don't write less AI-assisted code. They spend their saved time on the parts that only humans can do — deciding what the system should guarantee, and being able to prove it under pressure.
The one-line version
Code you can't explain isn't leverage, it's a liability with a delay timer. The model can write it; only you can own it.
Next in the series: what happens when the thing that generates your code is also the thing that grades it — the evaluation layer.
Top comments (0)