Never Delegate Understanding

On March 31, 2026, version 2.1.88 of Claude Code was unintentionally leaked via npm. A missing .npmignore caused a source map file to be included in the package, exposing the compiled source. Security researcher Chaofan Shou spotted it. For those of us working on AI systems, it was an unprecedented opportunity to see the inner workings of a world-class AI orchestration harness. At the time, there were only a handful of companies in the world with the capability to build something like it.

I quickly got my hands on a copy and started exploring.

I was surprised by how unsurprised I was. What I found was a clean, well-thought-out architecture. A production application much like those I’ve worked on throughout my career. There was no real magic behind the scenes, nothing that would fundamentally change the way I approach engineering. But there were good patterns and principles throughout it that I still draw on today.

Of everything I took away from reading the source, one principle stuck with me more than anything else: “Never delegate understanding.” It is, in hindsight, the single most important guardrail against AI debt accumulating silently in a codebase.

It appears verbatim at src/tools/AgentTool/prompt.ts:112 and in paraphrase at src/coordinator/coordinatorMode.ts:259. Both are runtime system prompt text, injected whenever the orchestrator spawns a sub-agent. Not comments. Not documentation. Live instructions shaping agent behavior in the moment.

At first I didn’t understand why it warranted that level of emphasis. After several months of building my own orchestration systems, I do.

What “never delegate understanding” means

The principle governs how an orchestrator works with sub-agents. If you’re unfamiliar with that model, think of it as an engineering lead and their junior developers. The orchestrator is the higher-reasoning model, the one that sees the full arc of a project and communicates directly with the user. Much like a lead engineer who talks to product or the customer when designing a new feature. The sub-agents are the junior engineers: tasked to specific, well-defined portions of work specced out by the orchestrator.

There are real advantages to delegating out to sub-agents. It preserves the orchestrator’s context window. It speeds up the total wall clock time of a build by parallelizing work. But like delegating to developers, it’s not without risk.

As a lead engineer, if you were delegating an important chunk of work to a junior, you would do the upfront work to make sure the task is well-defined and the expectations clear. You’d hand it off and let the junior engineer exercise some autonomy to achieve the goal. But when they finished, you wouldn’t just accept it without looking at the code. Even if the feature technically worked, even if it had the functionality requested at a surface level, it is your job to do a comprehensive PR review: look for code quality issues with maintainability, composability, and performance. And to make sure that you have full understanding of what was delivered, including the portions you delegated.

The Anthropic team figured out quickly what happens when this step gets skipped. The orchestrator delegates work to a sub-agent. The sub-agent does its task and reports it done. The orchestrator moves on knowing the task was complete but not understanding how it was done. Over time, it loses the arc of what it’s building. It lacks the knowledge to be an effective engineering partner. The entity primarily responsible for authoring the code doesn’t understand the details of what was written. Sometimes it doesn’t even know they exist.

The anti-pattern is visible in the source. Bad: Agent({ prompt: "Based on your findings, fix the auth bug" }). Good: Agent({ prompt: "Fix the null pointer in src/auth/validate.ts:42..." }). The difference is whether the orchestrator has done the synthesis work first or is pushing that burden downstream.

The architecture has a structural forcing function: the coordinator cannot run tools directly, so it must synthesize what comes back from a sub-agent in order to continue. But Anthropic chose not to rely on that structure alone. The “never delegate understanding” enforcement is prompt-level. No hard code gate blocks a vague delegation. They decided the principle needed to be stated explicitly and repeatedly as a behavioral reminder, because structure alone wasn’t enough.

The parallel that keeps nagging at me

For the past several months I’ve been building AI orchestration systems, careful to codify the same discipline into the workflows I design. The results are worth it. Agents keep track of the full arc of what they’re building without burning their context on the mechanical portions of the work.

But lately I’ve been drawing another parallel, one I think is more important.

We are like an orchestrator. We work with Claude Code as our sub-agents, delivering features in epics that span several tickets across many different agents and context windows. We are the ones who hold the full arc of what we’re building, not over the course of a session, but over the course of months and quarters.

And like orchestrator agents, we cannot afford to delegate understanding.

The failure mode is one I see crippling many developers now, and it’s worse than the same failure in agents. It is easy to pick up a coding agent and get something that works. Developers, product managers, technical PMs, and designers describe what they want, look at the outputs, and as long as the application does what they asked for, they move forward. They merge. They never look back.

Many of the people now generating code are treating that code like a black box — the same pattern that produces product debt at the other end of the pipeline. They see what goes in and what comes out. That works, right up until the moment it doesn’t. The longer you do this, and the more code you build like this, the larger the problem is when something finally needs your understanding. You find out that the codebase you’ve been building is one you don’t understand. Whole sections of it are opaque to you, portions you delegated and never reviewed beyond checking the output. You might know what the application does, but you don’t understand how it works. For that reason, you are continually generating inferior product. The same way an engineering lead who blindly accepts every junior developer’s PR ends up with a codebase filled with inconsistencies, bugs, and a lack of continuity.

Anthropic named this problem inside a harness built to prevent their own agents from falling into it. The mantra is “never delegate understanding,” and I think it’s time that we as agentic developers start adopting it for ourselves.

Use coding agents to amplify your workflow. Spec out well-defined tasks, or even complex ones. But never delegate understanding. Force those agents to explain the architecture to you. Review the code so that you know what they’re building. Make sure you are still able to navigate and understand the product you’re building, so you don’t end up with a broken codebase you can’t maintain or fix. This is what AI-native product development looks like in practice: not just generating code faster, but keeping the human in the loop where it counts.