developmentL2 GuidedContext Engineering

Written coding conventions

Documenting your team's semantic coding decisions - not just style rules - gives AI agents the judgment framework they need to suggest code that fits your architecture, not just code that compiles.

·CLAUDE.md or equivalent exists with project description, tech stack, and top conventions
·Written coding conventions document exists and is referenced from agent instruction files
·Agent instruction files are committed to the repository (not local-only)

·CLAUDE.md includes explicit prohibitions (banned libraries, anti-patterns)
·Agent instruction files are reviewed as part of the standard PR process

Evidence

·CLAUDE.md, .cursorrules, or .github/copilot-instructions.md in repository root
·Coding conventions document accessible from agent instruction files
·Commit history showing agent instruction file updates

What It Is

Most teams have two kinds of coding standards: the ones enforced by linters and formatters, and the ones that live in senior engineers' heads. ESLint catches var declarations and missing semicolons. Nothing catches "we don't put business logic in controllers" or "repositories should return domain objects, never raw database rows" - except code review, which is slow, inconsistent, and unavailable to AI agents.

Written coding conventions are the second kind: documented semantic decisions about how code should be structured, organized, and extended. They answer questions like: When should I create a new service vs. extending an existing one? Where does validation logic live? How should modules communicate with each other - direct calls, events, or a message bus? What patterns are explicitly off-limits and why?

At L2 (Guided), these conventions are written down in a form accessible to AI agents, typically in CLAUDE.md, a .cursorrules file, or a separate CONVENTIONS.md referenced from CLAUDE.md. The writing of conventions is itself a team exercise - it surfaces disagreements, forces clarity, and creates alignment. Teams that have done this exercise often discover that their "shared" conventions were not nearly as shared as they assumed.

The scope of written conventions is narrower than a full style guide but deeper than linter rules. It covers the decisions that require judgment - the ones that can't be expressed as a regular expression check. These are precisely the decisions that AI agents get wrong most often at L1.

Why It Matters

When AI agents generate code without explicit conventions, they default to the most statistically common patterns in their training data. For widely-used frameworks, this often produces reasonable code. For your specific architectural decisions - which are, by definition, specific to your organization - the defaults are wrong.

Prevents architecture erosion - every agent that generates code in your codebase either reinforces your patterns or degrades them; conventions tip the balance
Reduces review burden - reviewers spend less time correcting pattern violations and more time evaluating logic
Accelerates junior developer onboarding - written conventions answer the questions they'd otherwise need to ask senior engineers
Aligns team understanding - the exercise of writing conventions surfaces implicit disagreements that would otherwise manifest as inconsistent code
Creates computable guardrails - at L3, written conventions become the basis for lint rules, automated checks, and agent validation

The relationship between written conventions and AI tools is bidirectional: well-written conventions make AI suggestions better, and bad AI suggestions - when reviewed - reveal which conventions haven't been written down yet. Every time a developer says "the agent keeps suggesting X when we always do Y," that's a convention waiting to be written.

Tip

Start by writing down the five most common corrections you make in code review. If you're correcting the same pattern repeatedly, it's a convention that should be explicit. Move from your head to the CLAUDE.md.

Getting Started

Distinguish conventions from style rules - Style rules are enforced by tooling (Prettier, ESLint, Black). Conventions are semantic: they can't be caught by a regex. Make sure your written conventions focus on the latter.
Interview senior engineers - Ask each senior engineer: "What patterns do you push back on in code review?" and "What would a new engineer most commonly get wrong in this codebase?" These answers are your raw material.
Structure conventions as rules, not guidelines - Weak: "Try to put business logic in services." Strong: "All business logic must live in service classes. Controllers are only permitted to parse requests and delegate to services. Any business logic found in a controller is a bug."
Explain the why, not just the what - "Don't use raw SQL in controllers" is a rule. "Don't use raw SQL in controllers - all database access must go through the repository layer, which provides connection pooling, query logging, and test isolation" is a convention with teeth. The reasoning helps agents and developers apply the rule in novel situations.
Commit to CLAUDE.md (or a linked file) - Conventions that aren't in the agent's context window don't help. If your conventions document is long, maintain it as CONVENTIONS.md and reference it from CLAUDE.md with a summary of the most critical rules.
Review and update quarterly - Assign a rotation for "conventions maintenance." After each sprint, add any new pattern that came up in code review. Remove conventions for patterns that have been officially replaced.

6 steps to get from here to the next level

Common Pitfalls

Writing conventions that are too abstract. "Write clean code" and "follow SOLID principles" are not conventions - they're aspirations. Conventions need to be specific enough that a developer (or agent) can determine whether a given piece of code follows them or not. If the rule can't be applied mechanically to a concrete example, make it more specific.

Covering everything at once. The goal is a working conventions document that gets used, not a comprehensive manifesto that takes months to write and is then ignored. Start with the 10 most important rules. Add more over time as you discover gaps.

Not maintaining conventions alongside code evolution. When you refactor a module or adopt a new pattern, update the conventions file. A conventions document that describes the old architecture actively misleads agents and developers. This is the same documentation rot problem as README staleness - but with more impact because agents follow these rules closely.

Storing conventions outside the repository. Conventions documents on Confluence, Google Docs, or internal wikis are not accessible to AI agents. The document needs to be in the repository, referenced from CLAUDE.md, so that agents pick it up automatically.

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

How Different Roles See It

BobHead of Engineering

Bob has noticed that code review takes longer for PRs that include AI-generated code. Reviewers are spending significant time pushing back on pattern violations that the AI consistently makes. His senior engineers are frustrated that their architecture decisions aren't being respected - by the AI or, increasingly, by junior developers who copy what the AI produces.

What Bob should do: Bob should frame writing coding conventions as the solution to two problems at once: improving AI suggestion quality and reducing code review burden. He should sponsor a "conventions sprint" - two afternoons where senior engineers on each team document the top 10 architectural rules for their codebase. The goal is not a perfect document; it's a committed document. Bob should then measure the before/after on code review throughput and AI suggestion quality after one quarter. If the conventions are well-written, both should improve measurably.

What Bob should do - role-specific action plan

SarahProductivity Lead

Sarah is tracking developer time allocation and discovers that code review is consuming a growing share of engineering time - not because there's more code to review, but because more corrections are needed per PR. When she investigates, the pattern points to AI-generated code that violates architectural conventions that were never written down.

What Sarah should do: Sarah should quantify the "convention violation tax": how many review comments per PR are pattern corrections vs. logic reviews? If she can show that 40% of review comments are "don't do it this way, do it this other way" corrections, and that a written conventions document could eliminate most of those, she has a direct ROI case. The conventions sprint investment (estimate: 2 days per team) pays back in reduced review overhead within a month. She should also connect this to AI ROI: AI tools that consistently violate conventions add review burden; properly configured tools with written conventions remove it.

What Sarah should do - role-specific action plan

VictorStaff Engineer - AI Champion

Victor is exhausted from code review. He writes the same 10 review comments every week - the same architectural corrections, the same pattern guidance, the same "don't do this, do that" feedback. He's started to wonder if there's any point to having AI tools if they're generating more review work than they save.

What Victor should do: Victor's review comments are his conventions list. He should take his 10 most frequent comments, formalize them as written rules (with reasoning), and commit them to CLAUDE.md. Then he should test: run a few agent sessions with the updated context file and compare the suggestion quality. If the conventions are well-expressed, the agent should stop making those specific errors. Victor should then propose automating the most mechanical conventions as lint rules (moving from L2 to L3: conventions become enforced guardrails) and reserve his review capacity for architectural decisions that require human judgment.

What Victor should do - role-specific action plan