How to enforce coding standards on AI-generated code in CI
Teaching a coding agent your standards is necessary and not sufficient. An instruction file is context, not enforcement: the agent follows it most of the time, and the exceptions ship. The standard has to be checked on the change itself, in CI, by something that gives the same answer every run. This page is about what that looks like and how to introduce it without a week of red builds.
Deterministic first, AI second
Section titled “Deterministic first, AI second”Two kinds of check exist, and they are good at different things.
| Deterministic checks | AI review | |
|---|---|---|
| Examples | A forbidden package, a file that must exist, a pattern that must not appear, an import across a layer boundary, a file over a size limit | “Does this change handle the failure case?”, “Is this name misleading?” |
| Same answer every run | Yes | No |
| Can block a merge honestly | Yes | No: a non-deterministic verdict that blocks a merge is a coin flip with authority |
| Cost | Milliseconds, no model | A model call per change |
| Explains itself | Rule, file, line, fix | A paragraph |
The rule: anything that can be expressed as a deterministic check should be, and only deterministic checks block. AI review is for what cannot be expressed that way, and its findings are advisory. In Groundrule, the evaluators regex, files, dependencies, imports, layout, metrics, change-set and Semgrep rules are deterministic and may fail a change; the llm evaluator is advisory and never does. Checks lists every option.
What a finding must say
Section titled “What a finding must say”A check that says “lint failed” teaches nobody. Every finding should carry the rule, why the rule exists, the file and line, and the fix. That is what lets an agent fix it unattended and lets a reviewer skip it. It is also what makes the check defensible when someone asks why their merge was blocked.
✕ SEC-003 No access tokens in code BLOCKER · deterministic (regex) src/config.ts:14 → Read the token from the environment or a secret manager. → groundrule explain SEC-003Check the change, not the repository
Section titled “Check the change, not the repository”A repository with ten years of history has thousands of existing violations. If the check runs against everything, it fails on day one and gets turned off by Thursday. Run it on the changed lines of the pull request, against the base branch, so a change is judged by what it introduced. Legacy violations are reported separately, as a number to bring down, not a gate.
In Groundrule this is npx @groundrule/cli check --base <ref>, which the GitHub Action runs for you with the pull request’s base. enforcement.scope: changed-lines and enforcement.legacy: report in .groundrule/config.yaml are the defaults for this.
What should block
Section titled “What should block”Not every standard deserves to stop a merge. A useful split:
- Blocker: a break is a security or correctness problem that is cheaper to prevent than to fix. Tokens in code, disabled TLS verification, string-built SQL, a domain module importing infrastructure.
- Warning: a break is wrong but survivable; the finding is shown and the merge proceeds. Missing lockfile,
console.login application code. - Guidance: context the agent should have, not something to check. “Prefer
@ts-expect-errorover@ts-ignore.”
Severity is a property of the rule. Whether the rule is switched on at all, and how far, is a separate dial, which is what makes rollout possible.
Roll out in stages
Section titled “Roll out in stages”The failure mode of standards enforcement is a big-bang switch: forty rules, three hundred findings on the first morning, and a team that routes around the check. The alternative is a stage per rule:
- Observe: the rule runs and is counted, nothing is shown to anyone. You learn how often it would fire.
- Teach: the rule is written into the agent files. Agents start following it; the check still does not fail.
- Advise: the check reports findings as warnings on pull requests.
- Enforce: a blocking rule now blocks.
A rule moves forward when the evidence says it is clean: so many days, so many pull requests, zero or near-zero new findings. Then nobody is surprised when it starts blocking, because the code already passes. Rollout stages covers how stages work per organization, team and repository, and Scans, the inbox, and when to switch a rule on covers the evidence.
Let the agent fix it before the pull request
Section titled “Let the agent fix it before the pull request”The cheapest place to catch a violation is before the commit exists. A stop hook that runs the same check when the agent finishes a task, and sends it back to fix blockers, means CI mostly confirms what the agent already did. Check when the agent finishes sets this up for Claude Code, Codex, Cursor and Copilot with one command.
A minimal setup
Section titled “A minimal setup”npx @groundrule/cli # a first look at what the checks find, then one question: # it writes the config, the agent files and the hooksThen the GitHub Action on pull requests:
- uses: actions/checkout@v5 with: fetch-depth: 0- uses: Metricall-AI-Lab/groundrule-action@v1Everything above works offline and without an account. A connected workspace adds staged rollout, a shared rulebook across repositories, and a report of what was checked and what was stopped; see Only the CLI, or a workspace?.