Coding Convention

A coding convention is a written, agreed rule about how the team writes code (formatting, naming, file layout, error handling), captured as a living artifact that both humans and AI agents can read and follow.

“Programs are meant to be read by humans and only incidentally for computers to execute.” — Harold Abelson

Also known as: Code Style, Style Guide, Coding Standard

Understand This First

• Naming – naming conventions are the most foundational kind of coding convention.
• Ubiquitous Language – conventions encode the team’s chosen vocabulary for the domain.
• Instruction File – the instruction file is where conventions get loaded into an agent’s context.

Context

You’re past the prototype stage. More than one person, or more than one agent, is touching the codebase. The shape of the code starts to vary file by file: one developer prefers camelCase, another uses snake_case; one wraps lines at 80 characters, another lets them run; one returns errors, another throws exceptions. The code still works, but reading it costs more attention than it should. This operates at the architectural level because code style decisions, like naming decisions, compound. Every file written in the wrong style is a small tax on every future reader.

What changed with agentic coding is the rate at which inconsistency now accumulates. A human developer absorbs the team’s style by reading neighboring files for a week. An AI agent processes whatever is in front of it on each request, and if the styles in the codebase already conflict, the agent picks one at random, or worse, blends them. By the end of a busy week, a codebase that had two competing conventions can have five.

Problem

How do you keep code consistent when the people writing it, human or otherwise, work at different times, with different defaults, on different parts of the system?

A team without explicit conventions runs on tacit knowledge. Senior developers remember the decisions made two years ago. New hires absorb the patterns by osmosis over their first few months. The system kind of works, until the senior developers leave or the team starts using AI agents that have no memory of any prior decision.

Then the codebase begins to drift. Function names get prefixed inconsistently. Imports get sorted three different ways. Error handling switches between exceptions and result types in the same module. None of this breaks the build. It just makes the code harder to read, harder to review, and harder to change safely.

Forces

• Conventions are constraints, and constraints feel arbitrary until you’ve seen what a codebase looks like without them.
• Writing conventions down takes time. Updating them as the team learns takes more time. Both feel like overhead until the day someone violates them.
• Different parts of a system have different needs. A scripts directory tolerates looser style than a payment processor, but blanket rules ignore that.
• AI agents follow whatever they encounter most often. Without an explicit reference, they’ll happily mimic the messiest file in the repo.
• Personal preferences are real. A team that fights over tabs versus spaces won’t agree on anything weightier, so the convention has to be a settled rule, not a debate that reopens on every PR.

Solution

Write the conventions down, keep them short, and put them where both humans and agents will read them.

Start with a single markdown file at the root of the repo: STYLE.md, CONVENTIONS.md, or a section inside AGENTS.md or CLAUDE.md. List the rules that actually matter for your codebase: naming patterns, file organization, error handling, logging style, import ordering, comment style, test layout.

Skip the rules your formatter already enforces. You don’t need to write down “use 2-space indentation” if Prettier handles it. Write down the things a formatter can’t catch: when to use which kind of error, how to name a feature flag, where business logic belongs versus where it doesn’t.

For each rule, give an example. A rule without an example is an abstraction that everyone interprets differently. A rule with one good example and one bad example removes the ambiguity in three lines.

Wire the conventions into the tools that read them. For human developers: a linter, a formatter, and a pre-commit hook handle the mechanical rules automatically. For AI agents: include the conventions file in the instruction file the agent loads on every session, or reference it explicitly in your prompts. The combination matters. Linters catch what they can mechanically check. The conventions file teaches the parts that require judgment. Together they cover the surface a human reviewer would otherwise have to police by hand.

Treat the file as living. When you spot a recurring problem in code review, a mistake more than one person has made, that’s a candidate for a new convention. Add it, write a short example, and now the next person (or agent) won’t make the same mistake. The convention file grows the way scar tissue grows: where the system has been hurt before.

How It Plays Out

A team of four is building an internal reporting tool. Two of them prefer Python’s snake_case, the other two came from a JavaScript background and reach for camelCase without thinking. Three months in, the codebase has functions named both ways, sometimes in the same file. A new contributor opens a PR and asks which style is correct. There’s no answer.

The team spends an hour arguing in Slack, picks snake_case (it’s Python, after all), and writes a one-line rule into a new STYLE.md. They add it to their AGENTS.md file too. The next week, they bring in an AI agent to refactor a slow query module. The agent reads STYLE.md, follows the convention, and produces consistent code on the first pass. The argument doesn’t recur.

A solo developer maintains a Rust library with several thousand stars on GitHub. External contributors keep submitting PRs that don’t match the project’s style: different error handling, different module structure, different documentation tone. Each PR turns into a multi-round review where the maintainer explains the same things repeatedly.

They write a CONTRIBUTING.md with the conventions: ? operator for error propagation, modules organized by feature not by type, doc comments use the imperative mood. They link it from the README and from the PR template. The next round of contributions land closer to the target style, and code review shifts from style discussions to design discussions. Six months later, when they ask Claude Code to do a sweeping refactor across the library, the agent follows the same conventions because they’re written down where it can read them.

Consequences

Code reviews focus on logic and design instead of style. A reviewer who spots a camelCase function in a snake_case codebase can leave a one-line comment with a link to the convention file, instead of explaining the rule from scratch. Onboarding speeds up because new team members and new agents have a reference point that doesn’t require asking a senior developer. Refactoring across the codebase becomes safer because consistent code is easier to search, easier to transform mechanically, and easier to verify by eye.

The cost is the discipline of writing the conventions down and keeping them current. A convention file that’s three years out of date is worse than no file at all because it tells people the wrong thing with authority. Conventions also need to bend when they should. A rule that made sense for a 5,000-line codebase may not fit a 500,000-line one. When the rule starts feeling like it’s fighting the work, that’s the signal to revisit it, not a reason to ignore it silently.

There’s a limit to what conventions can do for you. They make consistent code easy and inconsistent code visible, but they don’t make bad code good. A well-formatted function with the wrong logic is still wrong. Conventions are about how the code looks and how it’s organized. The judgment about whether the code is right at all still belongs to the reviewer, human or otherwise.

Related Patterns

• Uses / Depends on: Naming – naming conventions are usually the largest section of a coding convention.
• Uses / Depends on: Ubiquitous Language – conventions encode which domain terms the code should use.
• Enables: Instruction File – a coding convention is a primary input to the instruction file an agent loads.
• Enables: Harnessability – consistent code is one of the structural properties that makes a codebase tractable for agents.
• Enables: Code Smell – convention violations are often the first smells a reviewer notices.
• Contrasts with: Vibe Coding – vibe coding accepts whatever the agent produces; conventions force the output to match a defined standard.

Sources

• The practice of writing coding conventions down predates software engineering as a named discipline. Brian Kernighan and P. J. Plauger argued for stylistic discipline in The Elements of Programming Style (1974), the first widely read book to treat code style as a teachable craft rather than a personal preference. Their rules (“say what you mean, simply and directly”; “write clearly, don’t sacrifice clarity for efficiency”) still hold up.
• Google’s open-source style guides (google.github.io/styleguide) are one of the most thorough public examples of an organization-wide coding convention. They cover more than a dozen languages and explain not just what to do but why each rule exists. Many teams use them as a starting point and trim down to what they actually need.
• The 2026 “naming renaissance” coverage on brokenrobot.xyz and Stack Overflow documents how AI agents have made coding conventions newly important. Both pieces report that teams without explicit style guidance see bug density rise 35–40 percent within six months of adopting AI tools, because agents amplify whatever inconsistency they find. The pattern: consistent naming and structure make agents force multipliers; inconsistent code makes them chaos amplifiers.

Further Reading

• Robert C. Martin, Clean Code (2008) – chapters 2 through 5 cover the core conventions most teams adopt: naming, functions, comments, and formatting. Opinionated and worth the disagreement.
• Addy Osmani, “How to Write a Good Spec for AI Agents” (O’Reilly Radar, 2026) – treats coding conventions as one of six areas every effective agent spec must cover, with a three-tier “always / ask first / never” framework for capturing them.