How a coding agent is kept to the rules
A coding agent follows your rules for two reasons: it reads them before it writes, and it is checked after. Groundrule does both, at four places, and the later gates exist for the times the earlier ones are not enough.
- before editAgent files and the before-edit hook
The rule is in front of the agent as it writes.
- on finishStop hook
Checks what the agent changed before it can stop.
- by handgroundrule check
Anyone can run it; the same result as the hook.
- on GitHubPull request check
CI or the hosted check; the last gate before main.
Gate 1: the agent reads the rule
Section titled “Gate 1: the agent reads the rule”sync wrote your rules into AGENTS.md and CLAUDE.md, and the agent reads those files at the start of a session. With the hooks installed, Claude Code also hears the rules for a file right before it edits that file, so the rule is in front of it at the moment it matters, not only in a long document it read an hour ago. And every agent’s hook asks Groundrule before a command, an edit or a tool call whether the team allows it: an action policy can refuse a force-push or have the developer confirm a terraform apply before it happens.
A real example. In a Spring repository with the security pack, a developer asked Claude Code to add an AWS access key as a string constant. The agent answered:
I’ll avoid hardcoding the AWS key since that would violate rule SEC-003 and leak a credential; instead I’ll load it from an environment variable.
It wrote a class that reads the key from the environment and explained why. The rule shaped the code before anything was written. Most of the time, this is where the story ends.
Gate 2: the stop hook
Section titled “Gate 2: the stop hook”When the agent says it is done, the hook runs groundrule check on the files the agent changed in that task. If a blocker is found, the agent is not allowed to stop; it gets the finding and fixes it first. If nothing is found, the hook stays silent and the agent finishes as usual. In the example above, the last line of the agent’s reply was:
Verification: the Groundrule check passes with no blocking findings.
Had the agent written the key anyway, the check would have failed on SEC-003 at the line, and the agent would have replaced it before finishing. Either way, the key never lands in the repository.
In a repository connected to a workspace, each hook run also reports its counts per rule to the workspace, never a path or code. That is the “stopped in the agent loop” number on the dashboard.
Gate 3: the check by hand
Section titled “Gate 3: the check by hand”Anyone can run the same check at any time:
npx @groundrule/cli check --base origin/mainThat is also the way to ask an agent to clean up: “Run groundrule check –base origin/main and fix every blocker it reports.” The agent runs it, reads the findings and the remediation text, and fixes the lines. With the MCP server connected, it can run the check itself without the shell.
One detail: check looks at changed lines by default. A violation that was already on the branch, in a line the current task did not touch, is not that task’s finding. --base origin/main or --all catches it.
Gate 4: the pull request
Section titled “Gate 4: the pull request”CI, or Groundrule’s own hosted check, runs the check against main on every pull request. This is the gate a developer cannot skip by not installing anything, and the one that can disable the merge button. The pull requests page covers the choices.
Hooks and MCP, in one line each
Section titled “Hooks and MCP, in one line each”Hooks happen to the agent: automatic, every task, whether or not the agent asks. MCP is something the agent chooses to use: it can list the rules, ask which apply to three files, run a check mid-task, and, connected, propose a rule when a developer corrects it and says “make that a rule for everyone”. Together they cover both cases.