Engineering standards for coding agents

Guide rails for every coding agent on your team.

Groundrule keeps one rulebook for your engineering team, writes it into the instructions Claude Code, Cursor, Copilot and Codex follow, and checks every change against it. Each rule rolls out in stages, on evidence from your own code.

agents4 inputs, 1 rulebook
rules · teachwritten into agent files
checks · enforcedeterministic gates
mainmerged on rule
drawingOne rulebook → every agent, every change
standards183 in 15 open packs
agent formats4, written from one source
changed by AI alone0 rules, ever
works withClaude CodeCursorGitHub CopilotOpenAI CodexGitHub ActionsGitLab CINotionConfluence
§ 01the problem

Every team already has rules. The trouble is where they live.

Your rules live in three places. All three leak.

Money in cents. Never call Stripe directly. Never log a session cookie. Coding agents write more of the code every month, and they only follow what they're told.

01.a · in people's heads

“We've said this in review a dozen times.”

The same comment, by different reviewers, on pull request after pull request. With Groundrule, write /groundrule rule once and it becomes a standard every agent reads.

01.b · in a wiki

“It's in the engineering handbook.”

Written carefully once, read rarely, never checked. Import it: AI finds each rule, cites the paragraph, and leaves the background out.

01.c · in agent files

“Which CLAUDE.md is the right one?”

Twenty repositories, twenty slightly different copies, none enforced. One rulebook syncs into every file and CI catches drift.

§ 02the method

Define, import, write. Every rule ends up as the same thing: a standard with examples and, where it can be checked, a check.

A rule, drawn to spec.

Start from proven standards, bring in the ones you already have, or describe a new one in a sentence. Whichever way it arrives, it's reviewed, given an owner and a stage, then taught to every agent and checked on every change.

  1. A
    Start from 183 maintained standards

    Packs for security, your languages, infrastructure and CI, with examples, references and a noise rating. Adopt, then tune rule by rule. Browse packs

  2. B
    Bring in what you already have

    Scan repositories for agent files, lint settings and CODEOWNERS. Import handbooks, PDFs, Notion, Confluence and Google Docs, and pull-request reviews.

  3. C
    Describe a rule in one sentence

    AI writes the standard, examples and a check, and tests the check against those examples before you see it.

fig. 02 · a standard, as every agent reads it

ACME-004blockerpayments · stage: advise

Route all Stripe calls through src/payments/gateway.ts

Never import stripe outside the gateway; call its functions instead, so retries, idempotency keys and logging stay in one place.

✕ don'timport Stripe from "stripe";
✓ doimport { refund } from "../payments/gateway";
check: regex · 6 examples passowner: @paymentssource: “We never call Stripe directly…”
§ 03rollout

Every rule has a stage. It starts where it can't hurt anyone.

Rules move forward on evidence, not hope.

Pick a stage on the scale to see what it does. Groundrule suggests the next one once a rule has had no findings for 7 days (14 before Enforce), across at least two scans of every repository. One click promotes it.

Findings appear locally and in CI, so people fix them, but nothing fails.

agent filesWritten
groundrule checkShows findings
ci resultNever fails
next stageEnforce after 14 clean days
§ 04evidence

Adherence is measured per rule, per repository, from your own scans.

See what a rule would catch before it can block anyone.

  • Adherence per rule, per repositoryFiles in scope, files clean, and up to three examples per rule, with the line.
  • An impact preview for every stage“If the organization used Enforce: 1 repository would fail.” Decide with numbers.
  • Promotion when it's earnedClean for long enough across repeated scans? Groundrule suggests the next stage.
TS-001 No console.log in application codeimpact preview
3/3applies in
2/3passing
1finding
96%files clean
if the organization used
TeachAdviseEnforce

1 repository would fail CI until its finding is fixed or excepted.

  • 1
    acme/checkout-apisrc/http/refunds.ts:4 · console.log("refunding", id, amount)
  • acme/billing-worker12 files checked
  • acme/storefront-web9 files checked
§ 05ai, supervised

AI reads; a person decides. Every proposal is labelled, scored and cited.

AI does the reading. People decide.

Import a handbook, a PDF or a page from Notion, Confluence or Google Docs. AI finds the rules in it, cites where each came from, and leaves the background out. Nothing reaches your rulebook until a person accepts it.

Acme Engineering Handbook## Data

1Money is always stored as integer minor units (cents) with an ISO currency code. Floats are not allowed for amounts.

2Personal data (names, emails, addresses) must never be written to logs. Log the user ID instead.

## On-call

On-call rotations change every Monday at 10:00 CET. Handover notes go in the #oncall channel.

1
Store money as integer minor unitsAI · 95% · Handbook › Data · ¶ 1
2
Never write personal data to logsAI · 90% · Handbook › Data · ¶ 2
–
On-call rotationsleft out · a team fact, not a rule
  • Cited, every timeEach rule found names its document and heading, or its page, or links the review comment.
  • Secrets removed firstKeys, tokens and passwords are masked before anything is sent. You see the estimate before reading starts.
  • A budget you setA monthly cap per workspace, and a usage ledger that records counts and cost, never content.
§ 06for developers

The CLI is open source (Apache-2.0) and runs anywhere Node.js 22 does.

Four commands. Every agent, every change.

Connect a repository to your workspace with one file, or use the CLI offline with no account at all.

CLI quickstart

acme/checkout-apifig. 01
$ npx @groundrule/cli init --org acme-payments

 ✓ Created .groundrule/config.yaml
   Platform acme-payments on https://app.groundrule.dev
   Agents   AGENTS.md, CLAUDE.md, .cursor/rules/
   Detected typescript, javascript

Connects the repository to your workspace. One file, committed with the code.

§ 07boundaries

A rulebook earns trust by being predictable. These are choices, and they'll stay that way.

What Groundrule deliberately won't do.

won't · 07.1

Let AI change rules

AI proposes, with a source and a confidence. A person accepts, edits or rejects.

won't · 07.2

Keep your source

By default, checks run where your code is and send results. For repositories you turn on, we check the code in a sealed sandbox and delete it.

won't · 07.3

Block by surprise

Only rules someone moved to Enforce can fail a build, and you see what they'd catch first.

won't · 07.4

Guess at your code

Checks are deterministic: same code, same result. Judgment calls stay as guidance for agents and people.

§ 08questions

More in the documentation, or write to hello@groundrule.dev.

What people ask first.

What is Groundrule, in one sentence?

One rulebook for your engineering team, written into the instructions every coding agent reads (AGENTS.md, CLAUDE.md, Cursor rules, Copilot instructions) and checked on every change, locally and in CI.

Which coding agents does it work with?

Any agent that reads AGENTS.md, including OpenAI Codex, plus Claude Code (CLAUDE.md), Cursor (.cursor/rules) and GitHub Copilot (.github/copilot-instructions.md). Agents that speak MCP can also list the rules and propose new ones through groundrule mcp. The same rulebook also writes CodeRabbit's .coderabbit.yaml, so the reviewer and the agents read the same rules.

Does Groundrule see our source code?

Not by default. Checks run on your laptop or CI runner. A scan uploads results: counts, which rules pass, and at most three one-line snippets per rule around findings, with secrets removed. A check uploaded from CI sends its findings the same way, one line each. With --no-snippets nothing from your files is uploaded. Hosted checks are the exception you choose: an admin installs Groundrule Code Checks, a separate GitHub App and the only one with access to code, on the repositories to check and turns each on, and Groundrule reads each pull request's code in a sealed sandbox with no internet access, deletes it when the check ends, and keeps only the result.

Will it start blocking pull requests on day one?

No. At Observe and Teach nothing fails; at Advise findings show but never fail; only rules someone moved to Enforce fail a check, by default only for blockers. Groundrule suggests moving a rule forward once your own scans show it has been clean long enough.

Does AI change our rules?

Never on its own. AI finds rules in documents and review comments, drafts standards from a sentence, and writes checks it has tested against examples. Every result arrives as a proposal labelled AI, with a confidence and a citation, and a person accepts or rejects it.

Do we need the platform, or is the CLI enough?

The CLI is open source and works offline in one repository. The platform adds one rulebook across repositories, teams and owners, the catalog, the review inbox, imports, evidence, promotions and AI.

What does it cost?

A Free workspace for small teams that never expires; Team and Business per active contributor, on the pricing page; the open-source CLI and rule format free forever.

§ 09 · sign-off

Give every agent your team's rules.

Create a workspace, adopt the packs that fit your stack, and connect one repository. In half an hour your coding agents follow your standards, and you can see what a check would catch before it blocks anyone.