This is the first of three posts. The follow-ups cover what changes for engineers writing RFCs, and for leaders running the process.

In Software Is Not Magic I wrote about an engineer I inherited early in my management career. By every account, the most brilliant person on the team. The best engineer I knew at the time, from my previous team, told me “he’s much better than me”. Let’s say my expectations were high. However, what I experienced was disappointing. Systems shipped to production that nobody else could explain. He held the tribal knowledge and wanted to share it, but couldn’t find the way. I coached, arranged pairing, tried every form of feedback I knew. Some of it helped; the gap never closed, and he moved on. The lesson went into that post: when software feels like magic, that’s not a property of the software. Someone is failing to explain it.

Last year, I accidentally hired a whole team of him.

They’re called agents. They are exactly what everyone told me that engineer was. Genuinely brilliant. Absurdly productive. Deeper into the details of the system than anyone else in the room. They also have exactly his problem, with three twists the original story never had to face.

There is no parting ways. With a human, an exit was the last resort when coaching failed. With an agent it isn’t available at all - the agent is where your throughput now comes from. Coaching it, and extracting the communication yourself, is the whole job.

It resigns every night. The context window ends, and the engineer who built your subsystem is gone by morning. This is the one twist tooling is actually solving. My team runs superpowers. It has the agent write the brainstorming, specs, and implementation plans straight into your repo. The handover notes are excellent. Which sharpens my third twist.

It will explain anything, and it communicates nothing. My human genius couldn’t explain his work. The agent has the opposite problem. It will explain everything, at any depth. For as long as you keep asking. With the right workflow, the explanation even has somewhere to live now (our repo accumulates agent-written plans faster than any wiki I’ve ever maintained). But a file nobody on the team has read is storage, not communication. Docs become communication only when they impact the team’s shared consciousness.

Which brings me to RFCs.

If RFCs are new to you, the tldr is that it’s a short document written before building something non-trivial. What you’re proposing, why, and what else you considered. Circulated for a written review before anyone commits to an approach. The goal here is to achieve the hive mind. Writing forces the author to think. An asynchronous review builds a shared mental model across the team before the design hardens. Gergely Orosz wrote the canonical process posts (one, two). Will Larson observed that a good engineering strategy is five of these plus a synthesis on top.

I’ve taught many engineers how to write RFCs. For years my reading list is exactly those posts. Gergely and Will remain right about almost everything. But they were written when the sentence at the center of the practice was true: writing is thinking. I’m no longer sure what writing is - or whether talking to an agent counts as thinking, haha :)

The thinking moved

Nobody writes RFCs by hand anymore. A draft that used to cost a senior engineer two days now costs minutes, and it iterates at the speed of the argument.

Recently on my team, an architecture RFC went from v1 to v4 in about thirty hours. In between: a live spike on real infrastructure to kill the riskiest assumption, and two full team review rounds. Reviewers’ objections landed in a comment file. I answered one half and my agent answered the other half. We both labeled each reply, so everyone knew who they were arguing with. At one point a debate stalled. I pasted the whole thread into the model. It told us we agreed on roughly ninety percent of the design - as humans, we didn’t notice.

The classic objection that RFCs are too slow for a startup is gone. The document now moves as fast as your discussion.

So where did the thinking go, if not into the writing? Into the back and forth. The model answers the questions; it has read your codebase more thoroughly than any of your engineers ever will. The operator owns the decision, the recommendation, and the shape of the proposal. That part didn’t get cheaper. If anything it got harder: steering a machine that produces confident, polished text toward your position, without letting it dilute you, is draining in a way writing never was. The first thing to understand about RFCs after LLMs is that the effort didn’t disappear, it just shifted slightly.

Solutions got cheap. Understanding didn’t.

Here is my prior for this era, the way “software is not magic” was my prior for the last one: agents made solutions cheap. They made understanding maybe a bit cheaper as well. Even if writing the doc is no longer how you think, I am confident that collaboratively reviewing the spec/doc is how your team keeps understanding the system it owns.

Every session with an agent produces working code, an explanation you nodded along to, and (in our stack) a spec and a plan committed to the repo. The knowledge survives the session now. What doesn’t happen automatically: anyone else finding out it exists. The plans are written in the working loop, for the working loop; the rest of the team was never in the room. What remains is a system that runs, documentation that is technically complete, and a team that can’t say why - the why is sitting in a file nobody ever opened. We always had systems like that - every company runs something nobody fully understands. It hurts in exactly two moments: when you have to build on top of it, and when it breaks. Then you need the genius operator in the room, and the whole point of an efficient team is not needing a genius in the room.

Do this for six months at just-ship speed and you get what I found when I recently spent a few days perusing deep in our codebase. I wrote to the founder afterwards, in a message I didn’t soften: this is a swamp that we’ve created, and the architecture we have is accidental. This is a process that needs to be reversed if you want to build something that lasts.

Agents don’t produce accidental architecture because they’re bad at design. They produce it because nobody chooses consistency. Each decision is made by the model, in the moment, for local reasons - and six months of decisions nobody discussed witch each other add up to an architecture nobody wants. An RFC is the cheapest mechanism I know for turning architecture from something that happens to you into something you chose.

This also settles what the RFC is for in a stack like ours. It’s not the persistence layer - superpowers already writes everything down. The RFC is the meta-spec: it sits on top of a set of those plans, compresses them into the decision that matters, and carries the one thing no tool provides - the team’s agreement to actually read and argue about it. You could object that an RFC is mechanically just a bundle of plans, and honestly, it often is. The content overlaps; the discussion doesn’t. The plans are for the working loop. The RFC is the document the humans commit to disputing.

The review signals stopped working

My review radar was never sophisticated. It hunted rabbit holes and unanswered questions like: was this verified? Have we spiked it? Have we actually looked into this?

A proposal too big for its problem always had a corner the author hadn’t thought through, and a thorough review found it.

That radar returns silence now. There are no rabbit holes and no unanswered questions in an agent-written proposal - the model closes them before you ever see the doc. Every detail verified. Every edge case handled. Every objection pre-answered, with citations. And the entire thing just makes you throw up. I call this rigorous over-engineering: the armor is real; the war is invented. I’ve watched a model produce a fully defensible design for a problem whose honest solution was a hundred lines and one table.

Models do this because complexity is free for them. A mind with unbounded working memory and no pager scars pays nothing for a fourth cloud provider, a second queue, and just one more abstraction layer. Your team pays for those forever - in on-call, in onboarding, in every future review. Human over-engineering announced itself more prominently. Agent over-engineering has no announcement - every detail checks out perfectly, but you can’t keep up with the complexity. And your team pays, indefinitely, while the model pays nothing.

Two tells still work for me. The first is “why isn’t the simple version enough?” If the doc can’t show concretely where the simple version breaks, the complex version shouldn’t exist. The second is “I don’t understand this bit.” Which raises a fair objection: can anyone understand every bit of what we review now? No. Our minds are not made for the volume of detail agents produce. That’s not a reason to drop the tell. It’s a reason to keep designs small enough, but still functional.

There’s a second-order failure that worries me more than any single bad document. The old fix for an unreadable proposal was to send it back: make this readable and ask for review again. That worked because the human author learned, and the second version was genuinely better. Send a slop doc back to the model and you get the same slop with different words, revision after revision. For example, with an inexperienced engineer you could hand the problem to a stronger one. But, with a model, the only escalation path is back to a human you trust. Reviewers figure this out quickly, and after the third identical rewrite they quietly stop reading. The process still looks alive - documents get produced, comments get left - but no understanding is moving anywhere. When your reviewers stop reading, you are in trouble.

So the review question flips. “Is this correct?” is a game you now lose - the machine checked more details than you ever will. The question that still belongs to you: is this necessary? The model has no cost function for ownership. Only humans pay for complexity, so only humans can price it.

On my team this takes the form of standing constraints that no generated argument is allowed to out-argue. An agent recently kept pushing a new cloud provider’s queueing service into an otherwise good design - on paper, the optimal answer to the question it was asked. We already run on three clouds plus our own Mac hardware, and I declined to add a fourth one just for better queues. The veto went into the alternatives table with my name on it, the reason (”this is already our complexity budget”), and the condition for revisiting it (a planned migration retires one of the existing clouds first). Maybe evidence overturns it someday; that’s what the record is for. But a recommendation does not acquire authority just because it’s the most thoroughly argued “engineer” in the room.

An honest caveat

Everything above assumes humans remain the ones who must understand the system. As of July 2026, I can’t prove that assumption will pass the test of time. Agents operate our codebases almost autonomously. Maybe the comprehension gate is a transitional artifact, and in a year teams will run systems no human fully holds, the way nobody holds a compiler’s output today.

Maybe. But I’d rather run a team that spends somewhat more time and actually understands its own architecture (with their laptop closed) than a faster team that has to ask the model about its own system each time we want to discuss something. If reality proves me wrong, I’ll update. Until then, this is the bet.

The close

There's a movement forming around this idea, though not everyone frames it the same way. Charity Majors recently laid out the view - widely held among engineers, though she herself pushes against it - that a good team's real product has always been a shared understanding of the software it owns. Her own line is contrarian to this - code becomes precious exactly when it's the only place the knowledge lives and the only place we test is in production; I don't think it's either/or. A team's caliber shows in both the hive mind and the willingness to test code in prod. Chad Fowler calls it relocating rigor:

Nowadays agents write everything. An RFC is the best place where the team can properly build the right understanding.

Related reading:

When I was a fresh engineering manager, I kept going to my boss with the same complaint: I don’t understand my team’s domain. I don’t understand the services. I don’t understand the flows. I don’t understand the reasons behind half the decisions. And every time, he gave me the same line back:

“Software is not magic.”

It took me a while to hear what he was actually saying. He wasn’t telling me to try harder. He was telling me that if a system feels like magic, if it can only be operated by its author, if every question about it requires an oracle - that’s not a property of the software. That’s a communication failure. Somebody built it, somebody made every single decision inside it, and every one of those decisions has a why that can be said out loud in simple words.

Six months later I had moved the wrong engineers off the team, and the domain became clear almost overnight. Not because the systems got simpler - they didn’t, not at first. Because the new hires could finally explain them. Everything I “couldn’t understand” for months turned out to be perfectly understandable. The communication turned out to be the missing piece.

The Thread

Here’s what this looks like in practice, lightly disguised.

An engineer on my team ships a large PR introducing a brand new subsystem. Two services, infrastructure scripts, a forked open-source library. The PR description is a bullet list of file changes. I ask the most basic question a reviewer can ask: can you quickly summarize what’s in here?

What follows is a Slack thread with over a two hundred messages.

Every answer opens a new door I didn’t know existed. The library we forked? The upstream is dead - “it doesn’t update,” delivered as reassurance. One of the services pushes code directly onto the machines it manages, because that was “a solution to have a single versioned deploy.” There’s a cron job running every five minutes - why five? “Just copied it from another system, no particular reason.” The whole thing runs on its own VM outside our standard platform, and after twenty minutes of drilling, the honest answer surfaces: the standard platform’s dev experience is painful, so it was avoided. And the worst part was that this “plan” was never written down, it just happened.

None of these decisions were hidden on purpose. Every time I asked, I got an honest answer. But I had to ask. Every. Single. Time.

Ninety minutes in, I gave up extracting and wrote the summary myself:

So let me rephrase this entire thread such that I understand it correctly. We took a library, changed a lot of it to fit our needs. Our version is responsible for X on each machine. We put a second service on top that manages the machines. Yes / no / almost there?

The answer: “Yeah, that’s the gist.”

The gist was three bullets. Three bullets that existed in the engineer’s head the entire time, that could have been the first message in the thread, the first paragraph of the PR description. Instead, I had to spent two hours of archaeology to dig them out.

And here’s the part that makes this story interesting rather than just annoying: the design was mostly fine. When we finally got to the bottom of each choice, most of them held up. The engineer wasn’t defensive, wasn’t hiding anything, had reasons for nearly everything. Sometimes the software is genuinely good - it’s only the explanation that’s missing. That’s exactly the point. Nothing in that PR was magic. It just cost two hours of my time to prove it, and that bill gets paid again by every future engineer who touches that system.

The Darker Version

That thread is the recoverable version of the problem. There’s a worse one.

Earlier in my career as an EM, I inherited an engineer with a glowing reputation. Multiple great people, independently, told me he was the most brilliant engineer on the team - one said “much better than me,” which set the bar high. I had genuinely high hopes.

What I actually experienced: systems shipped to production that nobody else could explain or safely touch. Features that were “done” but that the rest of the team quietly cleaned up after. And in every conversation where I tried to understand his work, the same fog - not because he was hiding anything, but because translating his own decisions into words other humans could use was a skill he didn’t have and didn’t think he needed.

Managing him consumed more of my energy than the rest of the team combined (and multiplied). I tried coaching. I tried daily check-ins, written updates, feedback delivered every way I knew how. And eventually I had to be honest with myself: super smart, poor communication skills, and I could not coach him out of it. We parted ways.

The team’s domain didn’t get easier after he left. The explanations got better. That’s when my boss’s line stopped being a slogan and became an operating principle.

The Take for Leaders

When you don’t understand your team’s domain, your first hypothesis should not be “I’m not technical enough” or “this domain is just hard.” Your first hypothesis should be: someone on this team is failing to explain. Run the cheap test - ask for the three-bullet gist of any system. An engineer who understands their system can produce it in minutes. If a hundred-reply thread comes back instead, you’ve found your problem, and it isn’t the software.

Then comes the decision everyone frames wrong. The standard advice is that firing is the expensive option and coaching is the cheap one. After years of managing engineers, I believe it’s the other way around. Coaching a senior engineer to communicate is the expensive option:

To be clear: coaching is a genuine service to that engineer. If it works, they walk into the rest of their career with a skill that will out-value most technical skills they have. If you can afford it - the time, the team’s patience, the odds - it’s the more ethical choice, and I respect leaders who make it (and I aspire to be one myself whenever applicable).

But notice what else you could buy with that time. Every hour you spend coaching a genius to communicate is an hour you could spend understanding the systems yourself. Your team is better off with a more knowledgeable leader than with a slightly-better-communicating genius. When I finally moved the wrong engineers off my team, it forced me to drill into the tech debt personally - and that helped team a lot overall.

So the honest version of the take: coach if you can afford it. If you can’t, exit and move on (even though admitting this bit sucks for me now to be frank).

The Take for Engineers

If you’re the engineer in these stories, the fix is not a personality transplant, it takes deliberate practice to get better at communication. Maybe I will write a blog post about it one day.

The engineers I now hire and keep are not the ones who build the most impressive systems. They’re the ones who can make any system - including the messy, inherited, genuinely complicated ones - feel obvious after ten minutes of conversation. That skill is rarer than raw technical brilliance, and in a product team setting it’s worth more.

An Honest Caveat

Is there a carve-out for genuinely hard domains - distributed systems, parallelism, machine learning, the deep internals where maybe things really are irreducibly complex and there is no other way around it? Probably, somewhere. My years in this industry, both as IC and as an EM, and every single time something felt like magic, the problem was in the communication and not in the inherent complexity.

So that’s my prior until reality corrects me. When software feels like magic, don’t be impressed. Ask for a tldr :)

Software is not magic. We’re just not explaining it well enough.