Agents follow what they're told. Tell them everything.
An agent writes good code for the codebase it imagines. Groundrule describes the one you actually have: the gateway to use, the logger, the floats you never use for money. Then it checks the result before it lands.
sync writes each format from the same rules, scoped to the repository's languages and paths.
AGENTS.md
OpenAI Codex and every agent that reads AGENTS.md
CLAUDE.md
Claude Code, importing AGENTS.md
.cursor/rules
Cursor, one rule file per scope, with globs
copilot-instructions.md
GitHub Copilot, plus path-specific instructions
One rulebook, written the way each agent reads.
These are sync's real outputs. Anything you write outside the markers stays exactly as you wrote it.
# Checkout API, notes for coding agents Run `pnpm test` before pushing. <!-- groundrule:begin --> <!-- Generated by Groundrule from `.groundrule/`. Edit the standards there, then run `groundrule sync`. --> ## Engineering standards These are this repository's engineering ground rules. Follow them in every change. Before you finish a task, run `npx @groundrule/cli check` and fix what it reports. For the reasoning and examples behind a rule, run `npx @groundrule/cli explain <ID>`. ### Everywhere - **ACME-004** Route all Stripe calls through src/payments/gateway.ts · _blocker_ Never import 'stripe' or call api.stripe.com outside src/payments/gateway.ts; call the gateway's functions instead, and add new operations there if needed. - **SEC-001** No private keys in the repository · _blocker_ Never commit private keys. Load them at runtime from a secret manager or the environment. <!-- groundrule:end -->
The managed block. Anything you write outside the markers stays exactly as you wrote it. Rules are grouped by where they apply, with examples where the standard has them.
<!-- groundrule:begin --> Engineering standards for this repository are in AGENTS.md: @AGENTS.md <!-- groundrule:end -->
Claude Code follows @imports, so CLAUDE.md points at AGENTS.md instead of spending context on a second copy. Without an AGENTS.md target, the full rules go into CLAUDE.md.
--- description: Engineering standards for src/payments/** globs: src/payments/** alwaysApply: false --- <!-- Generated by Groundrule from `.groundrule/`. Edit the standards there, then run `groundrule sync`. --> # Engineering standards: src/payments/** - **ACME-001** Call payments through the gateway · _warning_ Never call Stripe directly; go through `src/payments/gateway.ts`.
One rule file per scope. Rules for the whole repository always apply; rules for some paths get globs, so Cursor loads them only when it edits those files.
--- applyTo: "src/payments/**" --- <!-- Generated by Groundrule from `.groundrule/`. Edit the standards there, then run `groundrule sync`. --> # Engineering standards: src/payments/** - **ACME-001** Call payments through the gateway · _warning_
Repository-wide rules go to .github/copilot-instructions.md. Rules for some paths go to .github/instructions/groundrule-<scope>.instructions.md with applyTo.
Write, check, fix. The check takes a fraction of a second.
The agent writes, the check catches, the agent fixes.
- Fast enough to run every timeEvery generated file tells the agent to run the check before it finishes.
- An explanation on demand
groundrule explain ACME-004prints why the rule exists, the examples, and how to comply. - The same check in CIWhatever slips past the agent stops at the pull request, at the stages you chose.
$ npx @groundrule/cli check --all groundrule check · 43 standards · 14 files (full audit) ✕ GHA-003 Do not interpolate untrusted event data into scripts BLOCKER · deterministic (regex) .github/workflows/ci.yml:8 8: - run: echo "${{ github.event.pull_request.title }}" → Move the expression into the step's env: block (e.g. TITLE: ${{ github.event.issue.title }}) and use "$TITLE" in the script, always double-quoted. ⚠ TS-001 No console.log in application code warning · deterministic (regex) src/http/refunds.ts:4 4: console.log("refunding", id, amount); → Replace it with the project's logger, or remove it. Failed ✓ 31 passed ✕ 1 failed ⚠ 5 warnings · 0.0s
Two tools: list_standards and propose_rule.
Live rules, and a way to propose new ones.
groundrule mcp is a Model Context Protocol server. list_standards gives an agent the rules in effect, with each rule's stage. propose_rule sends a rule to your inbox when a developer corrects the agent and says it should apply to everyone.
claude mcp add groundrule -- npx -y @groundrule/cli mcp
Run it once in the repository. The server reads the same rulebook as sync and check: your organization's, with the repository's own standards.
{
"mcpServers": {
"groundrule": { "command": "npx", "args": ["-y", "@groundrule/cli", "mcp"] }
}
}In .cursor/mcp.json in the repository, or in Cursor's global MCP settings.
{
"servers": {
"groundrule": { "command": "npx", "args": ["-y", "@groundrule/cli", "mcp"] }
}
}In .vscode/mcp.json. VS Code calls the list servers, rather than mcpServers.
- you
We never log full card numbers here. Mask all but the last four, and make that a rule for everyone.
- agent
Fixed in src/http/refunds.ts. Proposing it to the team.
propose_rule { rule: "Never log full card numbers; mask all but the last four digits.", file: "src/http/refunds.ts", line: 4 } - groundrule
Proposed to Acme Payments. Reviewers will see it in the inbox.
The documentation covers each format and every option.
About agents.
Which agents read which file?
AGENTS.md is read by OpenAI Codex and the growing list of agents that support it. Claude Code reads CLAUDE.md (which imports AGENTS.md), Cursor reads .cursor/rules, and GitHub Copilot reads .github/copilot-instructions.md and .github/instructions. Choose the targets in .groundrule/config.yaml; onboarding picks them from the agents your team uses.
Which rules reach the agent files?
Rules at Teach, Advise and Enforce that apply to the repository's languages and paths, with your organization's and team's changes applied. Rules at Observe stay out, as do rules turned off.
Does an agent need network access to follow the rules?
No. The agent files are plain text in the repository. Only the MCP server and sync talk to Groundrule, and only with a token you created.
What does an agent send when it proposes a rule?
The rule, the reason and an example if given, the file and line if given, and the agent's name. Nothing else from the repository. A rule needs at least 10 characters; proposing the same rule again counts as a vote.
Teach your agents in ten minutes.
Sign in from the CLI, connect a repository and run sync. Your agents read the rules on their next task.