og.rsts.dev
← writing

Design Is the New Code

Listen 0:00 / 0:00

When agents write the code, the decisions stop living in it. Dave Rensin's Elephant-Goldfish Model, now open source from Google, says feed a deep-context session to write the design, then test that design against reviewers with no memory at all. Cross-checked against how BMad runs at team scale, and against the gap it exposed in my own factory.

Design Is the New Code
Contents

The code is becoming the part I don’t read.

That sentence would have gotten me fired fifteen years ago. Today it is a plain description of how my factory works. In the dark factory post I described a pipeline that takes a link and returns a pull request, and in the sequel I applied it to Mule flows, Spring Boot, and Angular. Both posts were about gates. Neither answered the question a careful reader should ask next: if nobody reads the code, what exactly does a human read before signing their name?

Dave Rensin has the best answer I have seen. His essay “Elephants, Goldfish and the New Golden Age of Software Engineering” (opens in new tab) describes how his team built a tool that more than 100,000 Googlers ended up using, with dozens of contributors and AI writing much of the code. Google has since let them open source the method as a plugin, the Elephant-Goldfish Model (opens in new tab), with a home at egm.dev (opens in new tab). His answer fits in four words: design is the new code.

I am going to take his patterns, check them against how a different camp runs agents at team scale, and then be honest about the hole they exposed in what I built.

The decisions moved out of the code

Rensin’s core argument is short and, once you see it, hard to unsee.

When a human writes code, they leave a trail of micro-decisions in it. Why this retry, why that boundary, why the null check sits here. Reading the code was how the next person recovered the reasoning. When an agent writes the code, the human stops making those micro-decisions. If the decisions are not captured somewhere before the code is written, they are not captured at all, and the system becomes incomprehensible to the person who is accountable for it.

He thinks we land in one of two places. Either the models produce so much code that reviewing all of it becomes a practical impossibility, or they skip source and emit binaries. “Whether in a blizzard or a binary,” the code becomes opaque. When that happens, the only artifact that matters is the design.

There is a real tension here, and I do not want to flatten it. Engineers want speed. The whole point of the factory is that the agent writes the thousand lines so you do not have to read them line by line. The institution wants something just as legitimate: someone who understands what shipped, can explain it to an auditor, and can say why it was built that way. Rensin puts the second pole bluntly: “a human will be held responsible for any action taken by an agent.” I made the personal version of that argument in You Can’t Forward the Understanding. You cannot sign what you never understood.

The design document is where those two poles stop fighting. The agent gets its speed on the code. The human gets comprehension on the artifact that is a fraction of the size. Rensin’s third “aha” is a formula, sizeof(docs) << sizeof(code), and it is the reason this works. A reviewed design is the thing a person can sign.

Interrogator, not researcher

Before the software part, Rensin starts with buying a car, and it is the most transferable idea in the essay.

The usual move is to type what you want, flip on deep research, and accept an impressive report. He calls that using a powerful tool like a toy. The better sequence has three steps. First, ask the model to interrogate you, to keep asking clarifying questions and challenging assumptions until you say stop. Second, in the same session, switch it into a skeptical fact checker and build the acceptance criteria you will use to grade the final report. Third, open a fresh session and hand it both documents: the problem and the rubric.

Notice the shape. The model’s first job is not to answer. It is to make you say what you actually mean. And the grading criteria exist before the work does.

He also names the failure that kills this: sycophancy. When the model starts telling you how brilliant your point was, it has stopped being useful. His fix is a sentence I have started using verbatim: “When you agree with me you are not being helpful.” And the cheapest debugging prompt in the essay is just “Why do you think that?”

Feeding the elephant

For software, the method gets a metaphor. The Elephant never forgets. It is the long, context-rich session where you and the model co-design a feature, and the document that session produces. The Goldfish is a brand-new session with no memory. It knows only what you put in front of it. The process for every feature is one line: feed the Elephant, test it against the Goldfish.

Feeding the Elephant has rules, and each one closes a specific failure.

No code. The prompt says so outright: “I do not want you to create code. We are not going to create code. Resist your impulse to create code.” Engineers love writing code and so do models. The design conversation dies the moment either one starts.

Correct it on minute one. Load the relevant docs or source, ask the model to describe what it learned, and fix every misunderstanding immediately. A wrong mental model in minute one is terrible code in minute ten.

Let the model propose first. This one surprised me. Rensin insists that the AI propose the first technical design, in prose and block diagrams, rather than reacting to yours. If you lead, it agrees with you and you never see what it misunderstood. If it leads, its misunderstandings are on the page where you can argue with them. Some of his sessions run two or three days.

Write the doc in sections, never in one shot. Four parts, in order: the Problem in plain English, the Technical Plan with a block diagram, the Alternatives you rejected, and the Detailed Implementation, which must list every file that will be created or changed and why.

The Alternatives section is the one I underrated. Every option you argued down during the design becomes a guardrail. The next session, or the next contributor, that proposes the rejected approach finds the reason it was rejected already written down. That is the same move I described in Architecture Is the Prompt with decision records: the reasoning you write down becomes the context the agent works inside.

Test it against a Goldfish

Here is the part I think is new, and the part I did not have.

How do you know the document is good, and not just good inside the session that wrote it? The Elephant has hours of conversational context. It fills gaps in the doc without noticing it is doing so. So you hand the doc to something that cannot fill gaps: a fresh session with zero memory.

Rensin runs three Goldfish in sequence. The first is a comprehension test:

Read this document and the files it references. Tell me what it's
trying to accomplish, and how my system currently works as it
relates to this feature.

If the Goldfish cannot explain the system from the doc alone, the doc is missing context. Add it and repeat. The second Goldfish is a critic, told that every mistake and ambiguity it finds makes it more useful. Rensin says about 30 percent of its suggestions are highly valuable, and he loops until the findings are nitpicks. The third tests implementation readiness:

You are an experienced software engineer experienced with our
codebase. Read this document and the files it references and tell
me: Does it absolutely have all the information you would require
to successfully implement this feature in your first pass?

Only after the doc passes does a human review it, and only after that does anyone write code. The implementation prompt is almost boring: read the doc, follow the plan exactly. Because the doc lists every file, the agent stays on the rails, and if a session crashes you open a new one, hand it the doc, and you are back in thirty seconds. When the code is done, one more pass: a deliberately mean review. His actual prompt asks the model to tear the code to shreds.

The open-source plugin hardens all of this. Its architecture doc (opens in new tab) names the failure modes it targets, and the first one is the one that matters most: when a single thread interviews you, designs, and writes the code, “the model validates its own faulty assumptions instead of detecting errors.” The fix is structural. Reviewer personas live as stateless prompts in their own folder: a zoom-out reviewer that checks simplicity, YAGNI, and reuse before anything else, a naive comprehension reader, a design critic, an implementation-readiness checker, and a synthesizer that fans them out in parallel and deduplicates what comes back. There is also a drift report that compares checked-in designs to live code and flags missing features, missing fields, hardcoded shortcuts, and architectural divergence. That last one answers my first objection before I could raise it. Designs rot. This one gets checked.

Peanuts and hay for the monolith

The objection every enterprise engineer raises is the same one Rensin hears: nice for greenfield, but my codebase is millions of lines. His answer is a recursive summarization he calls feeding the elephant peanuts and hay. Start at the leaf directories, have the model write a README for each, and have a human spend five to ten minutes fixing it, because at the leaves the model is about half wrong. Then roll up one level at a time, reading only the READMEs below plus the code at that level, until you reach the root. He says it takes about a week regardless of size, and the READMEs are scaffolding. Once design docs reference every file, you can delete them.

The onboarding consequence is the part I would steal first. A new engineer’s first job is to write a design doc for their first feature that passes the Goldfish test. When it passes, they know enough of the system to contribute. That is a better onboarding exit criterion than any number of weeks of shadowing.

A second camp agrees, mostly

I did not want to write a post that endorses one method because it is new, so I checked it against a very different source: Brian Madison and Tim Dickey on “How Teams Run BMad at Scale” (opens in new tab), about the BMad Method (opens in new tab). BMad comes from the agile and product side, not from a single tool’s history. The overlap is striking.

The person is the variable. Rensin says do not outsource your judgment. BMad says the split between great and bad results is the person, not the tool, and the trap is typing one sentence and letting it fan out. Both tell you to bring your opinion and make the model challenge it. BMad’s brownfield prompt is one I have already borrowed: “What are the least obvious changes to this codebase that would eliminate this pain?”

AI amplifies. Rensin warns that without discipline “we are mass-producing our mistakes.” BMad says “AI is an amplifier of good practices and bad practices,” and that once agents write most of the code the bottleneck moves to requirements, reviews, and pipelines. Same observation, different vocabulary.

Planning is cheap. Both reject the complaint that design conversations waste tokens. The conversation is nothing next to coding the wrong thing twice. BMad adds the warning I needed: models love to gold-plate, so fight the “oh, by the way” and ship the lean version.

People at the table. Rensin’s last gate before code is a real human. BMad’s best results came from human, human, and AI together, with the requirements and architecture worked out by a couple of people rather than one person alone.

Where they pull apart is more useful than where they agree.

How detailed should the spec be? Rensin demands every file in the implementation plan, up front. BMad’s newer version plans loosely, treats the top-level requirements as intent rather than spec, and builds one story at a time so you can pivot. They also expect the spec’s altitude to rise as agents improve. My resolution is that the Goldfish decides. The readiness test asks whether a stranger could implement this on the first pass. If the answer is yes at a higher altitude, stop writing. Detail is a cost you pay to pass the test, not a template to fill.

What shape should context take? Rensin grows a hierarchy of READMEs. BMad moved away from carefully sharded documents toward small, well-named, dated files with no index, because a model with ripgrep finds the right one among thousands. Both are reacting against the same thing: one bloated document nobody can load.

How much process per change? Rensin runs the full protocol on every feature. BMad calls itself scale-adaptive. Tell it you are building a to-do app and it tells you to just one-shot it. I land with BMad on this one, and I think Rensin would too in practice: the number of Goldfish passes should scale with blast radius. A copy change does not need a critic. A change to how money moves needs all of them.

Who owns what? BMad argues that the epic, seven to eleven slices delivered all the way to production, is now the unit one developer owns, ideally on their own worktree. I like that, and it composes cleanly with Rensin: the design doc is the epic’s contract. One owner, one doc, many stories built against it. As a small honest aside, this post was drafted on its own worktree for exactly that reason. Another branch was already in flight.

The Elephant-Goldfish loop. Full description below.

Image description

The Elephant-Goldfish loop: a deep-context Elephant session drafts the design doc, a swarm of zero-context Goldfish reviewers tests it for comprehension, critique, and readiness, a human approves it, an agent implements against it, a mean review tears the code apart, and a drift check feeds divergence back into the design

The gap in my own factory

Here is the uncomfortable part. When I read Rensin’s description of context pollution, I recognized my own pipeline.

Claude Buddy, the open-source tool I built, already enforces a foundation, then a specification, then a plan, then tasks, then implementation. Every feature leaves a paper trail. That is an Elephant, and a decent one. The blog factory has its own: an approved plan before anything is written, and a stack of gates after. But in both, the reviewers usually read the spec inside, or downstream of, the same session that wrote it. They inherit the drafting context. They share its blind spots. That is precisely the failure the Goldfish exists to catch, and I did not have one.

So I am changing three things.

Every spec gets a comprehension Goldfish. A fresh subagent with no conversation history reads the spec and the files it references, and explains back what it thinks the feature does. If its explanation is wrong, the spec is wrong, no matter how clear it felt while I was writing it.

Readiness becomes a gate, not a vibe. Before tasks are generated, a second zero-context reviewer answers Rensin’s readiness question. If it needs to ask, the answers go into the spec, not into the chat.

Drift gets checked. Specs that ship sit next to the code they describe, and a scheduled pass compares the two. A design that no longer matches the system is worse than no design, because it lies with authority.

None of these needs a smarter model. They need a reviewer that has not heard my side of the story.

Speed you can sign

Rensin closes his software section with a line worth repeating: “The job is intent. The job is architecture. The job is design judgment.” And his part on predictions makes the management point that BMad also makes in its own way. We are all managers of agents now, and good managers set outcomes and guardrails, not keystrokes. You know you are managing well when you can look away for longer and longer and things are still in order when you look back.

That is the reconciliation I keep coming back to. The engineers get their speed, because the agent writes the code against a plan it cannot wander from. The institution gets its comprehension, because the plan is short enough to read, was tested by readers who could not fill its gaps, and is checked against the code after it ships. Neither side has to lose. The design is the control plane, and the control plane is what lets you say yes to the speed.

What I have not solved

A Goldfish is only as good as the files it is allowed to read. Point it at the wrong ones and it will pass a doc that is missing exactly what matters.

A 30 percent hit rate from the critic is valuable, and it also means 70 percent of findings are noise someone has to triage. That person is still you. The plugin’s synthesizer helps; it does not make the cost zero.

The “blizzard or a binary” future is a prediction, and Rensin himself asks you to read it skeptically. Today the code still exists and still matters, which is why the mean review and the gates from my last two posts are not going anywhere.

And design docs are prose, so they inherit every weakness of prose: ambiguity, optimism, and the author’s assumptions about what the reader knows. The Goldfish narrows that gap. It does not close it.

Run one Goldfish this week

You do not need the plugin to start. Take the next spec or design doc you were about to hand to an agent. Open a brand-new session with no history. Give it only the doc and the files it names, and ask it to explain what the feature does and how the system works today.

Read the answer carefully. Every place it gets wrong is a place your doc was relying on your memory instead of its own words. Fix those, run it again, and then let the agent write the code.

If this was useful, read You Can’t Forward the Understanding for why comprehension is the part you cannot delegate, and The Factory Writes the Flow for the gates that sit downstream of the design.

Find me on X @orestesgarcia (opens in new tab) or LinkedIn (opens in new tab).