Coding Agents Need the Knowledge Teams Keep in Their Heads

What Cherny said

Boris Cherny, Head of Claude Code at Anthropic, argues that teams should “automate, and encode domain knowledge as infrastructure”. Domain knowledge means the project-specific rules and reasoning that experienced contributors carry in their heads.

Cherny’s examples range from automated tests and code checks to CLAUDE.md files, skills, and documentation. A skill is a reusable set of instructions that an agent loads for a particular kind of work.

His test is demanding. If a reviewer rejects a change because it used the wrong framework or architectural pattern, Cherny calls that a failure of automation. The repository should have given the agent enough guidance to avoid the mistake.

This is not just a recommendation to write better prompts. Cherny wants teams to redesign their codebases so agents and new contributors can work with less private explanation.

Why the take carries weight

Cherny created Claude Code and now leads the product at Anthropic. His argument offers a clear view of where coding-agent workflows may be heading.

The codebase becomes more than the place where software lives. It also becomes a working map of how the team makes decisions, checks changes, and avoids known mistakes.

Cherny is making that case from inside a coding-agent company. BuilderWithin’s question is whether the workflow principle holds beyond any one product.

What Cherny gets right

Repeated corrections are expensive. If an agent keeps making the same mechanical mistake, another reminder wastes time and leaves the next session exposed.

A durable check is better. A lint rule is an automatic check for a code pattern. A test verifies expected behavior. Continuous integration, often shortened to CI, runs those checks whenever code changes.

Those systems help human contributors too. They turn a lesson from one review into protection for every later change.

Cherny’s proposal also answers part of a problem BuilderWithin covered three days ago. Coding agents can let teams ship without building shared understanding. Writing down stable knowledge gives the team and its agents a common reference.

The strongest part of Cherny’s argument is this shift from correction to prevention. When a mistake repeats, improve the system around the agent instead of perfecting the next prompt.

Where the argument goes too far

Not all team knowledge can become a rule. Product tradeoffs, changing customer needs, and architectural judgment often depend on context that no static file can settle.

Instructions can also become their own source of failure. A recent study of 100 open-source repositories found at least one configuration problem in 91 of them. The researchers commonly found duplicated lint rules, bloated context, misplaced skills, and conflicting instructions.

That study catalogs warning signs rather than proving that every flagged file makes agents worse. Still, it shows that capturing knowledge is not enough. Teams must decide where it belongs and keep it current.

Cherny also sets “zero additional context from the prompter” as the goal. That is too absolute. A coding agent that never asks a question may be acting with false confidence, not complete understanding.

The better goal is to eliminate repeated explanation. New decisions and genuine ambiguity should still bring a human into the loop.

Put each lesson in the right place

Do not add every correction to one giant CLAUDE.md file. Sort the lesson by what it needs to do:

• Put repeatable code failures in a test, lint rule, or CI check.
• Put stable architecture and project conventions in maintained documentation.
• Put task-specific procedures in a skill that loads only when needed.
• Keep product tradeoffs and uncertain decisions with a human reviewer.

Start with the last five times you corrected a coding agent. If the same issue appeared twice, ask whether a durable check or short document could prevent it.

Then assign someone to maintain that source. A stale rule can be worse than no rule because it gives the agent confident but outdated direction.

Cherny is right that knowledge trapped in one person’s head limits both people and agents. The practical target is not a codebase that needs no human context. It is a codebase that stops asking humans to repeat what the system could reliably enforce.

End of article