How to Enforce Team Conventions on AI-Generated PRs (2027)

Your coding agents open pull requests faster than anyone can read them, and review has turned into a loop of the same comments. Use the shared HTTP client. No raw SQL in handlers. Errors go through our wrapper. You type them on Monday and again on Thursday, and the next agent session repeats the mistake on Friday. This guide gives you a method you can start this afternoon with a spreadsheet, a markdown folder, and the CI you already run. It also covers where tools like ZeroShot fit once the manual version stops scaling. Most teams should begin with the free version.

What Enforcing Conventions on AI-Generated PRs Means

Enforcing team conventions on AI-generated pull requests means turning the unwritten rules reviewers apply into written, checkable rules. A coding agent loads those rules before it writes code. PR checks verify them before a human reviews the PR. Each failure cites the specific rule it broke, by ID, with a link to the written rule.

The method only works if you are precise about what counts as a convention. Three kinds of problem get lumped together in review comments:

• Style rules cover formatting, whitespace, and import order. Formatters and linters already handle these. If a reviewer is still commenting on them, configure the formatter instead of writing a convention.
• Correctness bugs include off-by-one errors, null handling, and broken logic. Tests catch these.
• Conventions are team-specific choices, such as "all retries use exponential backoff via lib/retry" or "handlers never touch the database directly." The code works either way. Your team has picked one way, and the agent doesn't know which.

Generic tooling misses conventions, and agents violate them most often. They also produce the code the Stack Overflow 2025 Developer Survey's top frustration describes: AI output that is "almost right, but not quite."

The core shift is about where enforcement happens. Today, human reviewers are the first line of enforcement for conventions. With this method, they become the last line. Reviewers spend their attention on intent and design, such as whether this is the right approach or the right boundary. They stop checking whether the agent remembered the logging format.

Conventions are enforced when they are written as checkable rules, loaded by the agent before it writes code, and verified by PR checks that cite the rule.

Why AI-Generated PRs Break Conventions (and Why Review Alone Doesn't Fix It)

AI-generated PRs break conventions because every agent session starts from zero, and review comments never reach the next session. Coding agents are stateless across sessions by default. Unless your conventions are loaded into the context window through an instruction file, a skill, or the prompt, the agent falls back on patterns common in its training data. That means public-internet code, not your codebase.

Several other forces make this worse:

• Conventions live in reviewers' heads. Each reviewer enforces a slightly different subset. The agent gets inconsistent feedback, and none of it persists.
• Review comments are write-only. A comment fixes one PR. Bacchelli and Bird's 2013 Microsoft study found that knowledge transfer is one of the main outcomes of code review. With agents, that transfer reaches nobody, because the next session starts blank. The same comment comes back.
• Agents produce more than reviewers can read. The SmartBear/Cisco review study found that defect detection drops sharply past roughly 200–400 lines per sitting or 60–90 minutes of review. Agents routinely produce bigger diffs than that. Tired reviewers start rubber-stamping, and conventions erode without anyone deciding to drop them.
• Instruction files rot or bloat. One rules file grows until it is too long to use. The "Lost in the Middle" research (Liu et al., 2023) showed that models retrieve information less reliably from the middle of long inputs. Rule 47 of 80 effectively disappears, and nobody knows which rules still matter.
• There is no feedback signal. Without tracking, the team can't tell which conventions are violated most. People guess which rules to write down.

The symptoms are easy to spot once you look for them:

• Duplicate utility functions, such as a third formatDate helper
• Internal libraries bypassed in favor of raw fetch, direct SQL, or hand-rolled retries
• Inconsistent error handling, with ad-hoc error classes in every module
• New dependencies added without anyone approving them
• Tests in the wrong layer, the wrong directory, or with the wrong naming

This is not a small slice of review work. Mäntylä and Lassenius (IEEE TSE, 2009) found that roughly 75% of defects found in code review are evolvability issues, meaning structure, maintainability, and convention, rather than functional bugs. Most of your review effort already goes to the category this method targets.

The Method: 6 Steps to Enforce Conventions on AI PRs (No Tools Required)

You can run the full method with a spreadsheet, a markdown folder in the repo, and your existing CI, for a budget of zero and about one afternoon to start. Each step feeds the next. Written rules become skills, skills get checks, checks produce data, and data decides which rules to add or retire.

Step 1: Write conventions as checkable rules

Each rule gets six fields:

• an ID (CONV-014)
• a one-line rule
• a "how to check" line
• one good example and one bad example
• a rationale
• an owner

## CONV-014: Outbound HTTP uses lib/http
Rule: All outbound HTTP calls go through lib/http.client.
Check: No direct imports of fetch, axios, or node-fetch outside lib/http/.
Good: const res = await http.client.get(url, { timeout: 5000 })
Bad:  const res = await fetch(url)
Why: lib/http adds retries, tracing, and request IDs. Raw calls lose all three.
Owner: @platform-team

Apply one test to every rule: could two reviewers independently agree whether a diff violates it? If not, rewrite the rule or drop it. Write the rule as a positive, specific instruction rather than a vague prohibition. Include the rationale every time, because agents handle edge cases better when they know why a rule exists.

Step 2: Map each rule to a skill the agent loads

Group rules by task, not by topic. Typical tasks are "adding an API endpoint," "writing a migration," and "adding retries." Put each group in a short, task-scoped skill file in the repo, for example skills/add-endpoint/SKILL.md. Reference the skills from your agent's instruction file: the AGENTS.md conventions file, or an equivalent such as CLAUDE.md, .github/copilot-instructions.md, or Cursor rules.

The Agent Skills format uses progressive disclosure. The agent reads only each skill's short name and description up front, and loads the full skill when the task matches. That is why many small skills beat one giant file. Keep each skill short enough to read in a minute. Keep AGENTS.md itself short: a project overview, build and test commands, and pointers to the skills.

Step 3: Add PR checks that cite the convention

Route each rule to the cheapest reliable check. The order, from cheapest to most expensive, is:

1. formatter
2. linter rule
3. pattern-matching rule
4. CI script
5. PR-template checkbox
6. human reviewer

Every failure message names the rule ID and links to the rule. A Semgrep rule makes this straightforward:

rules:
  - id: conv-014-use-lib-http
    pattern-either:
      - pattern: fetch(...)
      - pattern: axios.$METHOD(...)
    paths:
      exclude: [lib/http/]
    message: 'CONV-014: use lib/http, not fetch. See docs/conventions/http.md'
    severity: ERROR

A check that says "error on line 42" teaches nothing. A check that says CONV-014 tells the agent and the human which convention applies and where to read it.

Step 4: Require the agent to state which skills it used

Add a "Conventions applied" section to .github/pull_request_template.md:

## Conventions applied
- Skills: add-endpoint, outbound-http
- Rules: CONV-003, CONV-014, CONV-021

Reviewers check the list against the diff. A missing list, or a list that doesn't match the code, is itself a review finding.

Step 5: Track review comments that repeat

Reviewers prefix every convention comment with the rule ID, such as CONV-014:, or with NEW: if no rule exists yet. Once a week, spend 15 minutes logging them in a spreadsheet with five columns: date, PR, rule ID or NEW, short description, and author type (agent or human).

Step 6: Promote repeated comments into rules and skills

Use a fixed threshold. Any NEW comment seen three or more times in two weeks becomes a written rule, mapped to a skill and a check. Retire a rule when a check already guarantees it and it has had zero violations for a quarter.

Which enforcement mechanism fits which convention

Convention type	Best enforcement mechanism	Example
Mechanical / syntax	Formatter or linter	Import order
Structural pattern	Pattern-matching rule or CI script	No direct DB access from handlers
Contextual / architectural	Agent skill + cited human review	New services register with the internal service mesh
Judgment	Human reviewer with written rationale	Is this abstraction premature?

The spreadsheet template and weekly cadence

• Sheet 1, Conventions register: ID, rule, check type, skill file, owner, last violated
• Sheet 2, Comment log: date, PR, rule ID or NEW, description, author type
• Sheet 3, Promotion decisions: week, candidate, count, decision, rationale

Run a weekly 30-minute convention review led by one rotating owner. The agenda has four items: top repeated comments, promotions, retirements, and stale skills. Treat the register like code. Keep it in the repo and change it through PRs.

Worked Example: Turning the Top 10 Repeated Review Comments into Cited Checks

This is an illustrative scenario with round numbers, not a customer case study. It shows how the six steps play out on a realistic first pass.

Setup. A team of six engineers merges about 30 agent-authored PRs a week. They export four weeks of review comments and get about 300. Roughly 130 of them are convention comments rather than design or bug comments. That ratio is in line with the evolvability research cited above.

Clustering. The team groups the 130 comments by meaning, not wording. "Use our client," "why raw fetch?" and "lib/http please" all land in the same cluster. The top ten clusters account for about 95 comments.

Cluster	Comments	Decision	Mechanism	Why
Bypassing shared HTTP client	16	Rule	Pattern rule (Semgrep)	Purely syntactic: forbidden imports outside lib/http
Ad-hoc error types	13	Rule	Skill + cited reviewer check	Agent must know when to use which wrapper error
Raw SQL in handlers	12	Rule	Pattern rule	Detectable: query calls inside handlers/ paths
Missing request-ID logging	10	Rule	Skill + cited reviewer check	Depends on which code paths are request-scoped
Magic config values	9	Rule	Pattern rule	Direct env access outside config/ is matchable
"Make it more readable"	9	Dropped	None (judgment)	Two senior reviewers couldn't agree on a checkable version
Wrong test directory / layer	8	Rule	Skill + cited reviewer check	Unit vs. integration choice needs context
Duplicate utility functions	7	Rule	Skill + cited reviewer check	Agent needs to know what lib/utils already provides
Unapproved dependencies	6	Rule	CI script (allowlist)	Diff the lockfile against an approved list
Missing feature flag	5	Rule	PR-template checkbox	"User-facing" is a judgment the author declares

The dropped cluster is part of the method. "Make it more readable" failed the two-reviewer test, so it stays a judgment call and comes out of the register. Saying no keeps the register trustworthy.

Rollout. The team spends one afternoon writing the nine rules, then one day adding three Semgrep rules, the allowlist script, four task-scoped skills, and the template changes. The PR template gets a "Conventions applied" section and the feature-flag checkbox.

Measurement. After four more weeks, the team reads the same comment log. In this scenario:

• Repeat comments on the nine promoted conventions fall from about 86 to about 20.
• About 100 of roughly 120 agent PRs list the skills they used.
• The CONV-014 HTTP check fires the most, around 20 times.

The way to read that last number matters most. A check that fires constantly is a signal about the skill, not the check. Here, the team finds that the outbound-HTTP skill wasn't referenced from the "add third-party integration" task in AGENTS.md. Agents doing integrations never loaded it. The team fixes the skill reference first. Tightening the check would have produced more failures without fewer mistakes.

Second-order decisions. During the trial, two NEW clusters cross the three-in-two-weeks threshold: pagination parameters named inconsistently, and background jobs missing idempotency keys. Both enter the promotion queue. The loop keeps running after the first pass, and that ongoing loop is what keeps the rules current.

Common Mistakes When Enforcing Conventions on AI Code

Most failed convention programs fail because the rules are vague, unowned, or bloated, not because the checks are weak. These are the mistakes to watch for:

• Writing aspirations instead of rules. "Write clean code" can't be checked. Agents and reviewers interpret it differently, and every PR becomes an argument.
• One giant instructions file. Context bloat dilutes the rules that matter. Split the file into task-scoped skills and keep AGENTS.md as a short index.
• Checks that fail without citing a rule. Both the agent and the human fix the symptom and learn nothing about the convention behind it.
• Trusting the self-reported skill list. A listed skill is a claim, not proof. Spot-check the diff against it, especially on large PRs.
• Enforcing on agent PRs but not human PRs. The rules diverge. Human code that breaks conventions becomes the example the next agent copies, so the codebase teaches the wrong pattern.
• No owner per rule. Unowned rules go stale and start contradicting each other. The agent then follows guidance nobody believes in anymore.
• Promoting every comment. One-off preferences turn the register into noise. Respect the repetition threshold.

Some problems sit outside what any tool can fix:

• genuine team disagreement about a convention
• missing rationale, where nobody remembers why a rule exists (an architecture decision record helps here)
• reviewer fatigue that has hardened into approving everything
• an architecture that is itself inconsistent, so the agent sees three valid patterns and picks one

No product resolves a convention the team hasn't agreed on, ZeroShot included. Settle the disagreement in a meeting, write down the decision, then enforce it.

When the Manual Method Stops Scaling

Linters catch syntax. Architectural conventions need context a linter doesn't have. That context includes which service owns what, why a pattern exists, and what the last similar change looked like. Skills and cited review supply that context. The manual tracking around them is where the method strains as volume grows.

The limit comes from how the method works, not from a benchmark. Manual tagging and tallying holds up while one person can read every convention comment in the weekly review. It breaks down when agent PR volume, the number of agents, or the number of repos grows past that. At that point comments go untagged, skills drift away from what reviewers actually enforce, and nobody can see which sessions skipped which skills.

These are the signals that you've crossed the line:

• The comment log has more untagged comments than tagged ones.
• The "Conventions applied" sections are copy-pasted boilerplate that no longer matches the diffs.
• Sessions can't be handed between teammates without someone re-explaining the context.
• The weekly review runs long because nobody trusts the numbers.

If none of these apply, keep running the spreadsheet. If several do, it's time to look at tooling.

ZeroShot: Session Monitoring That Enforces Skills on Every PR

ZeroShot is agent session monitoring for the coding agents a team runs. It automates the parts of the method that break first at volume:

• Capturing lessons. ZeroShot turns sessions and PR reviews into reusable skills, so the skills largely write themselves. For example, a rate-limiting approach a teammate worked out in one session becomes a skill the next session loads.
• Enforcing skills. It blocks PRs that skip the required skills and produces PR reviews that cite your conventions. This replaces copy-pasted "Conventions applied" sections and manual spot-checks.
• Session visibility. You can see any session and hand it off to any teammate without re-explaining context.
• The feedback loop. A daily Slack report shows what shipped overnight, the time and money saved, and which skills to sharpen. That replaces most of the weekly manual tally.

ZeroShot works with every coding agent, uses open-source skills, and can run fully locally so code never leaves your machine. It is SOC 2 Type II, GDPR, and HIPAA compliant. You can get started in three ways:

• a free Mac app, with no account required
• an Intel Mac build
• the CLI: curl -fsSL https://tryzeroshot.com/install.sh | sh

Team plans are available through a demo. ZeroShot reports that pilot teams, over a 90-day window, saw 3.7x faster delivery, 90% less wasted token spend per task, and 67% less PR review time.

Other tools that support the method

Tool	Role in convention enforcement	Cites rule IDs?
ZeroShot	Turns sessions and reviews into skills, blocks PRs that skip skills, cited PR reviews, session handoff, daily report	Yes, in PR reviews
CODEOWNERS + branch protection	Routes PRs to convention owners. Requires checks and owner review before merge	Indirectly, through required checks
Semgrep (pattern-matching analysis)	Structural rules with custom messages	Yes, through the message and metadata fields
Danger-style PR scripts	Enforce PR template sections such as "Conventions applied"	Yes, in custom failure text
AGENTS.md and agent instruction files	The load point that points agents to skills	No (a load point, not a check)

FAQ: Enforcing Conventions on AI-Generated Pull Requests

How do you make an AI coding agent follow team conventions?

Write each convention as a checkable rule with an ID, an example, and a rationale. Put it in a short task-scoped skill file the agent loads before writing code, and reference that file from AGENTS.md or your agent's equivalent. Back the rule with a PR check that cites the rule ID when it fails.

Isn't a linter enough?

No. Linters enforce syntax and local patterns. Architectural conventions need context that only a written skill or an informed reviewer provides. Examples include which library to use, which layer owns data access, and when a feature flag is required. Use linters for what they can catch, and skills plus cited review for the rest.

How many conventions should we write down?

Start with the ten most repeated convention comments from the last four weeks of review. Add new rules only when a comment repeats three or more times in two weeks. Retire rules that a check already guarantees and that have had no violations for a quarter.

Should AI-generated PRs be reviewed differently from human PRs?

The conventions should be identical. The difference is that AI PRs should state which skills and rule IDs they applied, and reviewers should verify that claim against the diff.

What's the difference between AGENTS.md and a skill?

AGENTS.md is the always-loaded entry point. It holds the project overview, build and test commands, and pointers to deeper docs. Skills are task-scoped instruction files, such as "adding an API endpoint" or "writing a migration," that the agent loads only when the task matches. Keep AGENTS.md short and route detail to skills.

How do we know enforcement is working?

Track repeated review comments by rule ID. If repeats for a promoted rule don't fall within a few weeks, the skill is unclear or isn't being loaded. Fix the skill before tightening the check.

Do we need a paid tool to do this?

No. A spreadsheet, a markdown folder in the repo, a PR template, and existing CI checks are enough to run the full method. Tooling becomes worthwhile when volume makes manual tagging and session visibility unreliable.

Sources and Further Reading

• Code review (Wikipedia)
• Lint (software) (Wikipedia)
• GitHub Docs: About code owners
• GitHub Docs: About protected branches
• GitHub Docs: Creating a pull request template
• Architecture decision records
• AGENTS.md
• Mäntylä & Lassenius, "What Types of Defects Are Really Discovered in Code Reviews?", IEEE TSE, 2009
• Bacchelli & Bird, "Expectations, Outcomes, and Challenges of Modern Code Review", ICSE 2013
• Liu et al., "Lost in the Middle: How Language Models Use Long Contexts", 2023
• Google Cloud DORA, Accelerate State of DevOps Report 2024
• ZeroShot

Stop raw-dogging agents

Every repeated review comment is a convention your agents haven't been given yet. Start with the spreadsheet this week. When untagged comments outnumber tagged ones, or nobody can tell which sessions skipped which skills, ZeroShot turns your sessions and reviews into skills, enforces them on every PR, and cites the rule when something slips.

Stop raw-dogging agents. Download ZeroShot free. It's a free Mac app with no account required, or you can install the CLI in one line.