Honest Engineering

On the Claude Code source and the Last 10%

The Claude Code CLI source became readable last week through an accidental sourcemap publish. The polite thing would have been to not look. The second most polite thing would have been to look but not write about it. I have now done neither, which makes this the third most polite thing, which feels about right for the internet. Everyone has seen the discourse. What is visible is just the CLI layer, not the full system, but even a partial view tells a story. As someone who has spent 15 plus years thinking about the last 10% gap, this one was hard to walk past.

Before I get into it though, it’s only right to admit that everything below is my reading of what I can see in the CLI source and my best guess at why these choices exist. I have a function somewhere in my past called processDataMaybe() that survived three sprints before anyone asked what the maybe was for. The names we give things under pressure are a pretty accurate record of the problems we were too busy to fully solve, which means my side projects’ commit history is officially “too embarrassing to show”. This is not a gotcha. It is pattern recognition from someone who has been there, and it is worth naming because every team building quickly will eventually face the same tradeoffs.

Five names from the codebase

TelemetrySafeError_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS
AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS
DANGEROUS_uncachedSystemPromptSection()
writeFileSyncAndFlush_DEPRECATED()
resetTotalDurationStateAndCost_FOR_TESTS_ONLY()

The first thing I noticed about all five is that they are unmistakably human. AI coding assistants do not write I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS. They do not reach for DANGEROUS_ as a prefix. A human looked at each of these situations, understood that something was unresolved, and made the deliberate choice to name the gap rather than smooth over it. Thats a form of craft in itself. The alternative, generating code that looks finished while the problem sits underneath it, is tidier. It is also less honest, perhaps?

Each of these names is doing a job that something else in the system was supposed to do. The technical term for this is "temporary solution." The historical record suggests the technical term is optimistic. The first two are standing in for a code review gate or an automated PII scanner. DANGEROUS_ is standing in for an architectural decision that would either remove the function or wrap it so the risk is not caller-dependent. DEPRECATED is standing in for a tracked removal ticket and a migration path. FOR_TESTS_ONLY is standing in for the dependency injection that would mean this function never needed to live in the production codebase at all. The people who wrote them were being careful. They knew the risks, understood the limitations, and named the problem into visibility because they could not resolve it at the design level quickly enough. That is the last 10% gap in one of its most recognizable forms where the team has done 90% of the right thing, and the remaining 10% is being held together by a naming convention that was never designed to carry that weight.

I found 40+ instances of this pattern across 20 production files:

if (process.env.NODE_ENV === 'test') {
  // production code changes behavior here
}

From what the source actually shows, analytics are explicitly disabled in test mode via isAnalyticsDisabled() in src/services/analytics/config.ts, which returns true when NODE_ENV equals test. Session cost and duration logging is skipped via an early return in src/setup.ts. The GrepTool changes its sort order from modification time to alphabetical for deterministic test output in src/tools/GrepTool/GrepTool.ts. The git file watcher runs at 10ms instead of 1000ms in src/utils/git/gitFilesystem.ts. The auth layer reads the API key from a file descriptor rather than the normal path in CI and test environments in src/utils/auth.ts. The behaviors are different in each case, some skip work, some change speed, some change output order, but the common thread is that the production code is aware it is being observed and adjusts accordingly. It is on its best behavior. The tests are meeting a slightly tidier version of the app.

So what would have made these unnecessary, or at least less load-bearing

The FOR_TESTS_ONLY function and the NODE_ENV branches are the same admission in two different forms. The code itself has absorbed the testing concern rather than the architecture handling it cleanly. What this creates is two programs that look like one. Every test that passes through one of these branches is passing on a version of the code that does not fully match what users run, and the gap between them grows without any obvious signal.

For the I_VERIFIED names, the technically correct TypeScript answer is a branded type with a smart constructor. A TelemetrySafeMessage type whose only constructor runs the detection logic means the compiler refuses to let you build the error with an unverified message. The honest counterargument would be that detecting whether a string contains a filepath or a code snippet is hard to automate reliably. A branded type backed by a flawed validator creates false confidence. A 60-character name that says a human verified this at least does not pretend the machine got it right.

For DANGEROUS_, the name is doing the work of access control. The structural fix is removing the function or wrapping it so the dangerous path is not directly reachable by callers who should not be near it. A name that warns is better than no warning, and it is not the same as a system that makes the mistake structurally harder. (It is, however, the same as a sign on a door that says DANGEROUS instead of a lock.)

For DEPRECATED, a suffix in the function name is visible to anyone reading the file and invisible to any tooling that tracks removal work. A deprecation without a ticket, an owner, and a target date maybe?

For FOR_TESTS_ONLY and the NODE_ENV branches, the answer is dependency injection at the boundary. When analytics, git, and auth are passed as parameters rather than reached for as globals, the test passes a fake and production passes the real implementation. The production codebase does not need to know it is being tested. The function FOR_TESTS_ONLY would not need to exist.

None of these are complicated fixes. They are all the kind of work that feels like overhead during a fast build cycle and obvious in retrospect. That is the last 10% problem in its most common shape. The gap between working and correctly designed gets filled with something that holds, and after enough time the names start doing jobs they were not built for.

The obvious version of this observation is about moving fast and cutting corners. The more interesting version is about what AI-assisted development is actually changing. AI tools are genuinely good at the 80-90%. They generate implementations, fill in boilerplate, handle the patterns a human would spend hours on at a pace that has shifted what teams can build. What they are not doing is making the last 10-20% decisions. The boundary calls, the ownership questions, the architectural judgment about whether a function should exist at all, whether a dependency should be injected, whether a pattern is a temporary patch or a permanent choice because those rightfully so still require a human. Which means in codebases where AI is accelerating the 90%, the gap is not closing. More code is being generated than human design capacity can fully close behind it, and the flags accumulate at the same pace the code does.

My processDataMaybe() is still out there in some codebase, probably outlived three engineers who knew what it meant and one who definitely did not but was too afraid to ask (we’ve all been there too). The five names in this source are doing the same thing where each one is a message left by the human who was there. “I know this is not finished”. “I did not have the tools or the time to close it properly”. “I wanted the next person to know where to look”. That is honest engineering, and it is also the last 10% expressed in the only form available at the moment it needed to be expressed.

Note: Based on the CLI layer only. Anthropic’s full system likely has additional safeguards not visible here.