Skip to content
Open the dashboard
Documentation

How a coding agent is kept to the rules

DevelopersEngineering leads5 min read

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.

where a bad line is stopped
password: "hunter2"
  1. before editAgent files and the before-edit hook

    The rule is in front of the agent as it writes.

  2. on finishStop hook

    Checks what the agent changed before it can stop.

  3. by handgroundrule check

    Anyone can run it; the same result as the hook.

  4. on GitHubPull request check

    CI or the hosted check; the last gate before main.

Usually the story ends at the first gate: the agent reads the rule and writes a placeholder instead. The other three exist for the times it does not.

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.

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.

Anyone can run the same check at any time:

Terminal window
npx @groundrule/cli check --base origin/main

That 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.

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 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.