StepGleam logoStepGleam
Coding guide

Ship AI-written code you can still explain: own the design, make the agent show its assumptions

Decide the abstractions yourself, pin them in a sketch or diagram, have the agent describe every change and flag what it assumed, then ask it to explain the diff before you commit.

~30 minIntermediate 78/100 7 steps Updated Oct 27, 2026
Claude CodeCodexPlantUMLGit
Ship AI-written code you can still explain: own the design, make the agent show its assumptions — illustration for this Coding guide

Tools used

  • Claude CodeImplements against your design and writes the change description
  • CodexAlternative implementer for the same loop
  • PlantUMLDiagrams you review before any code exists
  • GitThe diff the agent explains before you commit
Step navigator0/7 done
0 of 7 steps done
What you'll get

A change you can explain at the level of design and assumptions, backed by docs the agent keeps in sync.

Who this is for

Developers shipping code from Claude Code, Codex or Cursor who feel the system turning into a black box.

Read this first

Before you start

A 764-comment Ask HN thread (October 2026) asked how to ship AI-written code you do not fully understand. The developers below did not answer "read less" or "read everything". They keep the design in their own hands and make the agent produce artifacts they can check. Every step quotes the person who described it. Where nobody shared a detail, such as an exact template, this guide says so instead of filling it in.

Step-by-step instructions

Step 1 of 7 · Coding

Design the abstractions yourself, let the agent fill in the units

One developer's rule: "I don't let the LLM design the code at all, I let it implement a design I have created." He decides "at the UML level, how abstractions will sit and interact", then has the agent implement the gaps. The payoff: "I may not know how each unit is implemented, but I know each unit's responsibilities and how they interact with one another." The design doc becomes a living document.

Ship AI-written code you can still explain: own the design, make the agent show its assumptions — guide thumbnail
Why this works

You can swap a weak unit later; a wrong abstraction costs a refactor every time requirements change.

Step 2 of 7 · Coding

Pin the design in a scratch pseudocode file you both edit

Another developer writes a scratch Python file next to his Rust+Tauri app because "Python reads like pseudocode, and pass and ... (Ellipsis) let me skip whatever I don't care about." Where he cares, he states method signatures, domain-model fields and invariants; elsewhere he leaves an ellipsis. It runs both ways: "I ask the agent to sketch the current system in Python, with some details elided and others spelled out. Then I edit the sketch and have the agent push the changes back into the much bigger Rust+Tauri app."

Copy-ready promptClaude Code
Sketch the current system in a scratch Python file. Spell out signatures, fields and invariants; elide everything else with ...
Why this works

English-only sessions leave out details at every level; a sketch forces precision where it matters.

Step 3 of 7 · Coding

Review the plan as rendered diagrams before any code exists

A third developer reviews plans as "rendered diagrams. Data structures, flowcharts, uml sequences, and component architecture docs." His tweak: "making the AI look the plantuml and the rendering and reviewing before presenting it to me results in much more legible designs."

Step 4 of 7 · Coding

Make the agent write a templated description of every change

One developer has the agent "Write a templated description of the change: interactions with external systems, sequence diagram, happy path, corner cases, deploy checklist, settings change, etc." Then: "I review high level choices, and not the code." He did not share the template itself; the fields above are the full list he gave.

Copy-ready promptClaude Code
Describe this change: interactions with external systems, a sequence diagram, the happy path, corner cases, a deploy checklist, and any settings changes.
Step 5 of 7 · Coding

Have the agent leave a review comment wherever it assumed something

The same developer has the agent add review threads "everywhere it made suppositions and related to untested assumptions." Each one says "what could not be teste[d], what the llm thinks, what happens if I don't change anything and release the code." For the parts he wants to be sure of, he asks the agent to build a test bench, for example "provide me the command to fetch data, and a script to anonymise it" for a before/after comparison.

Copy-ready promptClaude Code
Wherever you made an assumption you could not test, leave a review comment saying what could not be tested, what you think, and what happens if this ships unchanged.
Why this works

Assumptions are where AI-written code fails quietly; surfacing them tells you where to look.

Step 6 of 7 · Coding

Ask the agent to explain the diff before you commit, then check it

One commenter's answer to the original question: "just use AI to explain the code to you before committing." He adds that he still wants to "understand every line of code that's committed with my name on it." Another developer plans iteratively with the model, has it write tests, and says "I try to review changes myself and ask it to explain the changes." Check the explanation against the diff rather than taking it on trust.

Copy-ready promptGit
Explain this diff to me before I commit it: what changed, why, and what it could break.
Step 7 of 7 · Coding

Keep a spec in the repo and make updating it part of every change

One developer keeps "a /docs folder that holds the full specification of the code" (block diagrams, edge-case behaviour, problem statement) and makes sure "the agent follows these specs and ensures the specs are updated after every code change." Another keeps it lighter: "The README defines the expected behavior of my API endpoints and the overall program in natural language," and Claude Code tests the endpoints it touched against that.

Why this works

When someone asks an architecture question, the answer lives in a doc you reviewed, not only in the code.

End of guide · Reviewed Oct 27, 2026

Pro tips2
  • Leave an ellipsis anywhere in the sketch you genuinely do not care about; spell out the parts you do.
  • Ask for diagrams to be rendered and checked by the agent before you look at them.
Common mistakes2
  • Letting the agent pick the abstractions, then trying to understand them afterwards.
  • Treating code and tests written by the same agent as proof; one commenter asked how to catch that and the thread gave no clear answer.
FAQ2
Do I still have to read every line?
The thread is split. Some commenters insist at least one person must be able to explain every line; others review design docs and assumptions instead. The steps here work for both.
Is there a ready-made change template?
No one shared theirs. Step 4 lists every field the developer named, and nothing more.