Code written to be read by agents

Code is written to be read by agents: explicit over implicit, obvious over clever. This is a claim about the code first and the documentation second. An agent arriving at a function has whatever it can read plus whatever it was told, and nothing else. It did not sit in the design review, it does not know that the third parameter is always a user id by convention, and it cannot ask the person who wrote the decorator what the decorator does. Everything it needs must be either visible at the point of use or written down.

The consequence is that the properties that make code agent-legible are mostly ordinary good practice, applied more strictly than a human-only codebase requires. Explicit types rather than inferred ones at module boundaries. Names that say what the thing is rather than names that are short. Behaviour that follows from the code in front of you rather than from a registration that happened at import time in another file. Dependencies passed in rather than resolved from ambient state. Clever code is not wrong, but it costs an agent more than it costs a human, because a human can afford to be curious and an agent will simply proceed on its best guess.

The same asymmetry applies to the conventions themselves. AI agents do not pick up implicit conventions through osmosis. They do not learn by sitting in code reviews or absorb culture through Slack. They follow instructions, and if the instructions are vague or assumed, the agent will make confident guesses that violate your team's actual intentions.

At L3 (Systematic), teams recognise this asymmetry and respond on both fronts: they write code that reads plainly, and they write down the rules that govern it. "Explicit over implicit" is not a general principle about documentation - it is a specific claim about what agents require. A human reading "use consistent naming" can infer what it means from examples in the codebase. An agent reading it has no idea and will apply generic patterns from its training data.

The transformation is practical: take each implicit convention - things everyone "just knows" - and rewrite it as a precise, example-driven rule. "Use camelCase for variables" becomes "Use camelCase for all variable and function names. Use PascalCase for class names and React component names. Use SCREAMING_SNAKE_CASE for module-level constants. Examples: getUserById, UserProfile, MAX_RETRY_COUNT." The second version is actionable for an AI agent; the first is not.

This work is also valuable independent of AI. Code obvious enough for an agent to modify safely is code a new joiner can modify safely, and conventions precise enough for a model to follow are precise enough for a person to follow. Writing for agents is mostly writing for the least-contexted reader, which every codebase acquires eventually.

The quality of AI agent output is directly bounded by the quality of explicit conventions. This is the core L3 insight:

• Eliminates the largest source of agent errors - most agent mistakes at L2 are not model failures; they are ambiguity failures that plainer code and stated conventions solve
• Cleverness is charged to every future edit - implicit magic, dynamic dispatch and behaviour registered at a distance are read once by their author and re-derived by every agent that touches the file afterwards, at full cost each time
• Scales tribal knowledge - implicit conventions locked in senior engineers' heads are finally captured in a form that benefits every developer and every AI agent
• Reduces review friction - when conventions are explicit and the AI follows them, reviewers stop finding style violations and focus on logic and design
• Makes conventions enforceable - explicit conventions can be referenced in automated checks and lint rules; implicit conventions cannot
• Directly measures context quality - the rate of agent misfires (convention violations in AI-generated code) is a direct measure of how explicit your conventions are; improving explicitness decreases misfire rate

The counterintuitive insight is that writing for agents benefits humans more than it benefits the agents. It forces teams to surface tacit knowledge that experienced developers accumulated and never wrote down, and it puts a visible price on the clever construct that only its author fully understood - the "everyone knows you don't do it that way" patterns that confuse new joiners and confound agents alike.

1. Find where the code hides its behaviour - Before touching the documentation, list the constructs in your codebase whose effect is not visible where it happens: metaprogramming, import-time registration, implicit dependency resolution, dynamic dispatch on strings, inherited behaviour several levels up. These are the places agents get things confidently wrong, and each is a decision about whether the cleverness is still earning its keep.
2. Categorise your existing conventions - Separate them into naming, file structure, patterns (how to implement common things), anti-patterns (what not to do), and architectural decisions (why things are structured the way they are). Each category needs a different kind of explicit documentation.
3. Rewrite for precision - For each convention, add: the rule statement, the rationale (why), a positive example (do this), and a negative example (not this). Four-part structure. The negative example is particularly valuable for AI agents.
4. Add example-driven rules - AI agents respond especially well to concrete code examples. Replace abstract statements with code snippets: instead of "handle errors consistently," write the pattern with try/catch structure, error type hierarchy, and logging call.
5. Test against an agent - After rewriting a set of conventions, ask an AI agent to implement a small task that exercises those conventions without showing it the CLAUDE.md first. Then show it the CLAUDE.md and ask again. Compare the two outputs. The difference measures the convention's explicitness value.
6. Prioritise by misfire frequency - Not all conventions are equally important to make explicit. Start with the ones where AI agents most frequently go wrong. Use code review comments from the last quarter as a source: every "the AI generated X instead of Y" comment is a convention to make explicit.
7. Review with both humans and agents - Have a senior engineer review the conventions for accuracy and have an AI agent attempt to follow them on a test task. Both perspectives surface different gaps.

Writing conventions for human readers, not agent consumers. Human-oriented documentation tells a story: historical context, tradeoffs, the road not taken. Agent-oriented conventions give rules: do this, not that, here's an example. Both are valuable, but they're different artifacts. Keep them separate. Your engineering handbook is for humans; your CLAUDE.md conventions are for agents.

Assuming the AI will infer from code examples. Some teams write "follow the pattern in src/components/Button.tsx" instead of stating the pattern explicitly. This works for humans who can read the component and extract the pattern. AI agents often fail to extract the correct pattern or apply it incorrectly to different contexts. State the pattern; then reference the example as confirmation.

Documenting the cleverness instead of removing it. When a construct is hard for an agent to follow, the reflex is to write a paragraph explaining it. Sometimes that is right. Often the honest accounting is that the construct saves its author a few lines once and costs every subsequent reader, human or machine, a re-derivation. Prefer the plainer implementation, and keep the explanation for the cases where the cleverness genuinely pays.

Making conventions so prescriptive they become brittle. Explicit doesn't mean exhaustive. A convention that covers every edge case becomes unreadable and unmaintainable. Write the core rule explicitly; acknowledge that edge cases exist and require judgment. The goal is to eliminate the common misfire, not to eliminate all human judgment.

Treating this as a one-time cleanup. Conventions evolve with the codebase. A convention that was correct for your React class component era is wrong now that you've migrated to hooks. Convention maintenance must be an ongoing process tied to significant architectural decisions. Add "update CLAUDE.md conventions" to your definition of done for any PR that changes a major pattern.