Written coding conventions

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.

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.

1. 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.
2. 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.
3. 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."
4. 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.
5. 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.
6. 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.

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.