developmentL3 SystematicCoding Agent Usage

Agent-aware coding conventions (explicit > implicit)

How to rewrite your team's coding conventions to be machine-readable - precise, example-driven, and structured for AI consumption rather than human reading.

·CLI agents (Claude Code, Codex) are the primary coding interface for 50%+ of feature work
·Per-team or per-repo rules files exist and are maintained with code review
·Coding conventions are written as explicit, agent-parseable rules (not implicit tribal knowledge)

·Agent usage is tracked per developer and per repository
·Agent instruction files follow a standardized template across the organization

Evidence

·CLI agent session logs or telemetry showing primary usage
·Rules files in repository with commit history showing regular updates
·Coding conventions document cross-referenced from agent instruction files

What It Is

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.

Why It Matters

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.

Tip

Run an "implicit convention audit" by asking a new team member (or using an AI agent with no CLAUDE.md) to implement a small feature from scratch. Every place where their implementation differs from "what we would have done" is an implicit convention that needs to be made explicit.

Getting Started

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.
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.
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.
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.
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.
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.

Tip

Write your conventions in the imperative voice: "Use X, not Y." Avoid hedged language like "generally prefer" or "typically should." Agents interpret hedging as permission to deviate. If a convention has genuine exceptions, enumerate the exceptions explicitly rather than using hedged language.

6 steps to get from here to the next level

Common Pitfalls

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.

Mistakes teams actually make at this stage - and how to avoid them

How Different Roles See It

BobHead of Engineering

Bob is frustrated that AI-generated code consistently fails code review on the same issues. Reviewers keep leaving comments like "we don't use this pattern," "this library is deprecated," and "this should use the centralized error handler." The same AI mistakes repeat across developers and across weeks.

What Bob should do: These repeating review comments are a diagnostic: they're exactly the implicit conventions that need to be made explicit. Bob should create a "convention backlog" - a list of every repeating AI misfire observed in the last month of code review. He should then task one developer per team to convert that list into explicit rules in the team's CLAUDE.md. This is a 2-3 day effort per team and should eliminate the repeat review comments within two weeks. Bob can measure success by tracking whether those specific review comments decrease after the conventions are updated. A decrease in repeat AI misfires is a direct ROI metric for convention documentation work.

What Bob should do - role-specific action plan

SarahProductivity Lead

Sarah has been tracking code review cycle time and has noticed that PRs with significant AI involvement take longer to merge than expected - not because the code is functionally wrong, but because it consistently violates style and pattern conventions. Reviewers spend time on style corrections that feel avoidable.

What Sarah should do: This is the explicitness gap in measurable form. Sarah should track "AI convention violation rate" - the percentage of AI-involved PRs that receive at least one convention-related review comment. This metric directly measures how explicit your CLAUDE.md is. Set a target: reduce AI convention violation rate from current baseline to under 10% within 90 days by systematically making conventions explicit. Sarah can show this to stakeholders as "context engineering quality improvement" - a leading indicator that predicts faster review cycles and lower rework cost. The financial story: every convention violation caught in review represents time that could be eliminated by better CLAUDE.md documentation.

What Sarah should do - role-specific action plan

VictorStaff Engineer - AI Champion

Victor has been doing this informally for months. When he notices the AI making the same mistake twice, he immediately adds an explicit rule to CLAUDE.md. His team's AI misfire rate is dramatically lower than other teams, and his code reviews are mostly about logic rather than style.

What Victor should do: Victor should systematize his informal practice into a team process. His proposal: when any developer on the team gets an AI convention misfire in code review, they are responsible for adding an explicit rule to the team's CLAUDE.md before the PR merges. This creates a direct feedback loop: code review surfaces implicit conventions, convention violations trigger explicit documentation, explicit documentation prevents future misfires. Victor should also write a guide for the team on "how to write a good convention rule" - the four-part structure (rule, rationale, positive example, negative example) with examples from the team's actual CLAUDE.md. This institutionalizes his practice without depending on his individual effort.

What Victor should do - role-specific action plan