Agent-aware coding conventions (explicit > implicit)

Agent-aware coding conventions are conventions documented with the explicit goal of being consumed by an AI agent, not just read by a human. The principle is simple: AI agents don't pick up implicit conventions through osmosis. They don't learn by sitting in code reviews. They don't absorb culture through Slack. They follow instructions - and if the instructions are vague or assumed, the AI will make confident guesses that violate your team's actual intentions.

At L3 (Systematic), teams recognize this asymmetry and respond by making their conventions explicit. "Explicit > implicit" is not a general principle about documentation - it's a specific claim about what AI agents require. A human developer reading "use consistent naming" can infer what that means from examples in the codebase. An AI agent reading "use consistent naming" has no idea what that means 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. Conventions that are precise enough for an AI to follow are clear enough for a new human developer to follow as well. Agent-aware documentation is better documentation, full stop.

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're convention ambiguity failures that better documentation solves
• 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 the work of making conventions explicit for AI agents benefits humans more than the AI. It forces teams to surface the tacit knowledge that experienced developers have accumulated but never written down - the "everyone knows you don't do it that way" patterns that confuse new joiners and confound agents alike.

1. Categorize your existing conventions - Separate your conventions 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.
2. 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.
3. 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.
4. 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.
5. Prioritize 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.
6. 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.

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.