Machine-readable engineering conventions for AI agents

Every engineering team has conventions. How branches are named, what goes in a PR description, how comments should read, when a spec is required. On most teams those conventions live in people's heads, a wiki page nobody opens, and review comments repeated week after week. AI coding agents never see any of that. They follow their training defaults, which means generic naming, chatty comments and commit messages in a style your team never agreed to.

The fix is to make your engineering conventions machine-readable for AI agents, and to put them where the agent will actually read them. I lead a team of 7+ engineers, and our conventions are served to AI coding agents from a conventions server: an MCP server that every engineer's agent connects to. This post covers how to structure the rules and how to serve them.

Why agents ignore your conventions

A coding agent knows two things: what it learned in training and what's in its context right now. If your rule about branch names isn't in the context, the agent can't follow it, no matter how sensible the rule is.

That has a cost on a team. The reviewer ends up correcting the same things in every agent-assisted PR: a missing spec reference, a comment that restates the code, a branch named after nothing in particular. Each correction is small. Together they eat review time and train people to stop reading closely.

Writing the rules down for machines turns those repeated comments into context the agent gets before it writes a line.

Group the rules by platform

A single giant conventions document has the same problem as a single giant prompt: the model loses the specific rule in the noise, and you burn context on rules that don't apply. Our server groups conventions by platform:

• Backend: API structure, error handling, database access, migrations.
• Frontend: component structure, state handling, styling rules.
• Flutter: app architecture, widget patterns, how testing works.
• Integrations: third-party APIs, webhooks, credentials handling.
• Shared: the rules that apply everywhere, like specs, branches, PRs and comments.

When an agent works on a Flutter screen, it pulls the Flutter and shared rules. It never has to wade through backend migration rules to find the comment style.

Write rules an agent can check

Vague rules produce vague behaviour. "Write clean code" gives an agent nothing to act on. Each rule should be specific enough that you could tell from a diff whether it was followed. The shared rules on my team are a good example of the shape:

• Spec first. Before implementing a feature or a non-trivial fix, the spec is settled. A new feature gets a new spec, and a change to something that already shipped amends the spec that owns it. This is the agent-facing version of the Spec-Driven Development process I rolled out across my team.
• Branch per spec. Every change gets its own branch, named after its spec number and a short slug, so any branch traces back to the document that justifies it.
• PR workflow. Everything merges through a pull request with a real description, and the agent asks before opening one.
• Comment style. Short comments in a human voice, explaining why something is the way it is. Never restate what the code already says.

Each rule says what to do, and where it helps, why. The why matters more for agents than you'd think: a model that understands the reason applies the rule sensibly in cases the rule didn't spell out.

Conventions can also cover tooling. Ours include using Marionette, which lets an agent drive a Flutter app running in debug mode, tap through screens and read logs while it tests a change. I wrote more about that in letting an AI agent test your Flutter app.

Serve them from an MCP server

There are a few ways to get conventions into an agent's context:

1. A root instructions file in each repo. Simple, versioned with the code, and most coding agents read one. The downside is copies drift across repos.
2. Per-directory instruction files. Better scoping, more files to keep in sync.
3. A conventions server. One source of truth, served over the Model Context Protocol, so any MCP-compatible agent in any repo gets the same rules.

My team uses the third. Every repo and every engineer's agent connects to the same server, and an agent asks it for the rules relevant to the platform it's working on. When a rule changes, it changes once, and every agent picks it up on its next session.

A small instructions file in each repo still has a job: it tells the agent the server exists and to check it before writing code.

Keep people as the owners

The conventions are team decisions, so they get the same care as code:

• Changes go through review. Rules live in version control, and a change to a rule is a reviewed change. A silent edit to a convention changes every engineer's tooling at once.
• Agents can suggest, people decide. If an agent spots a gap, the right move is for it to record a proposal for a human to look at. It should never edit the active rules.
• Silence is allowed. When a convention says nothing about a question, the agent should say so and use judgement. An agent that invents a rule and presents it as team policy is worse than one with no rules.

Where I'd start

Collect the review comments you've left more than twice and rewrite each as a specific rule with a one-line reason. Group them by platform, put them in one place every agent can read, and treat changes to them like code changes. Repeated review comments are the best source of new rules you'll find.