Groundrule

Groundrule

将您的工程标准传授给每个编码 Agent，并在每个 PR 上进行检查。

只需用 git 中的一个小型 YAML 文件编写一次标准。Groundrule 将：

• 向您的编码 Agent 传授标准。 它会生成 AGENTS.md、CLAUDE.md、Cursor 规则和 Copilot 指令，其中只包含适用的标准，且不会改动您手动编写的内容。MCP 服务和停止钩子可让 Claude Code、Codex、Cursor 和 Copilot 在完成前检查自身的改动。
• 检查代码。 它可以在本地和 CI 中针对您的改动或整个代码库运行检查，包括确定性检查（文件、模式、依赖项、导入、布局、指标、改动集）、Semgrep，以及 Groundrule 平台上可选的 AI 检查。
• 说明原因。 每条检查结果都会指出相关标准、展示证据、说明修复方法，并标明结果来自确定性检查还是 AI。

此代码库中的所有功能均可离线运行，无需帐户。Groundrule 平台在此基础上提供共享规则手册、分阶段推出、托管检查和合规报告。

状态： 0.x。Groundrule 正在用它检查自身的代码库。文档格式为 groundrule.dev/v1alpha1，在 1.0 之前仍可能发生变化；变更会在 Discussions 中公布。

60 秒了解

快速开始

只需 30 秒，无需帐户，任何内容都不会离开您的机器：

npx @groundrule/cli init      # detects your stack, picks packs, writes .groundrule/config.yaml
npx @groundrule/cli sync      # writes AGENTS.md / CLAUDE.md / Cursor / Copilot instructions
npx @groundrule/cli check     # checks your uncommitted changes

 groundrule check · 11 standards · 2 files changed

 ✕ TS-003  No eval or new Function
   BLOCKER · deterministic (regex)
   src/app.ts:3
     eval or new Function in application code
     3: return eval(input);
   → Parse the input instead: JSON.parse, a schema, or a lookup table of allowed operations.
   → groundrule explain TS-003

 Failed  ✓ 7 passed  ✕ 1 failed  ◇ 2 guidance  · 0.1s

一项标准

apiVersion: groundrule.dev/v1alpha1
kind: Standard
metadata:
  id: DEP-008
  title: Use the platform HTTP client
  type: forbidden-tech
  owner: team:platform
spec:
  severity: warning
  requirement: Backend services must use @acme/http-client for outbound HTTP calls.
  examples:
    forbidden: ["import axios from 'axios'"]
  checks:
    - evaluator: dependencies
      forbid: [axios, got, node-fetch]
      allowInstead: ["@acme/http-client"]

更多示例见 examples/foundation。

命令

命令	功能
groundrule init	为您的技术栈创建包含相关规则包的 .groundrule/config.yaml
groundrule sync [--check] [--upload]	写入（或验证）编码 Agent 指令；--upload 会报告此代码库向 Agent 提供的内容
groundrule check [--base <ref>] [--all]	检查改动、分支或全部内容。-f json|sarif|markdown，--summary <file>
groundrule standards	列出当前生效的标准
groundrule keys generate	为检查结果创建签名密钥对（RFC 0008）
groundrule verify <run.json> --key <public.pem>	离线验证一次运行的签名
groundrule explain <ID>	了解标准存在的原因、示例、遵循方法及例外
groundrule doctor	检查配置、工具和 Agent 文件
groundrule packs	列出内置规则包
groundrule scan [--json] [--upload]	根据完整目录评估此代码库：技术栈、Agent 文件、工具，以及当前每条规则的检查结果。不会更改任何内容
groundrule propose "<rule>"	提议一条规则，供团队在平台上审核。--why、--example、--file path[:line]
groundrule mcp	通过 MCP 向编码 Agent 提供您的标准，让它们检查自身的改动并提议规则（见下文）
groundrule hooks [--agents <list>] [--remove]	让 Claude Code、Codex、Cursor 或 Copilot 在完成任务时运行检查（见下文）
groundrule login	登录您在 Groundrule 平台上的组织（需在浏览器中批准）
groundrule whoami / logout	显示或移除（并撤销）已保存的登录信息

退出代码：0 表示通过，1 表示失败，2 表示配置或用法错误。

使用 Groundrule 平台（可选）

以上所有操作都可离线完成。如果组织在 Groundrule 平台上管理标准，请连接仓库，而不是列出规则包：

npx @groundrule/cli login               # approve this computer in your browser
npx @groundrule/cli init --org acme     # writes platform: { org: acme } to .groundrule/config.yaml
npx @groundrule/cli sync                # your organization's rules, with every customization

groundrule scan --upload 会将扫描结果分享给组织，让组织了解哪些规则适用于各个仓库。它还会将你已有的内容导入为提案：来自 AGENTS.md、CLAUDE.md、Cursor 和 Copilot 文件的指令；与目录规则匹配的 ESLint、Biome、Ruff、golangci-lint、Checkstyle、PMD 和 tsconfig 设置；CODEOWNERS；以及代码当前遵循的架构，并将其作为边界规则提案，同时列出目前会违反每条规则的文件（RFC 0011；使用 --no-import 可排除这些内容）。报告包含计数，每条规则最多包含三个单行脱敏片段（安全规则不包含片段；使用 --no-snippets 时则完全不包含片段）；--json 会显示将要发送的确切内容。上传时，扫描还会测试组织自己的、带有检查的规则（包括草案），让你在发布前了解其影响。

groundrule check --upload 会将结果作为合规记录发送给组织（RFC 0007）：生效的规则（任何拥有相同规则的人都可以重新计算其摘要）、每条规则的版本、推出阶段及其是否可能导致变更失败、适用的例外，以及变更提交中声明使用的编码 Agent（根据 Co-Authored-By 页脚和机器人作者统计；仅记录计数，不会记录提交消息或电子邮件地址）。Agent 计数是声明，并非证明；使用 --no-authorship 可将其排除。

在 CI 中配置签名密钥（运行 groundrule keys generate，然后将私钥设为 GROUNDRULE_SIGNING_KEY）后，每次上传的运行都会使用 Ed25519 签名（RFC 0008）；之后运行 groundrule verify，即可离线证明运行结果未被篡改。签名涵盖所有内容，但不包括代码片段。在 GitHub Actions 中，--sigstore 会使用作业自身的身份而非密钥进行签名（RFC 0009，需要 id-token: write；此功能需主动启用，因为身份和结果的哈希值会发送至 Sigstore 的公共日志）。

各命令从平台获取的内容取决于规则的推出阶段：sync 会将 Teach、Advise 和 Enforce 阶段的规则写入你的 Agent 文件；check 会按设定运行 Enforce 规则，并将 Advise 规则作为警告。仓库在 .groundrule/standards/ 中定义的规则仍然适用。在 CI 中，将 GROUNDRULE_TOKEN 设为从 Settings → API tokens 获取的令牌。登录信息保存在 ~/.config/groundrule/credentials.json 中，只有你本人可读取。

编码 Agent（MCP）

groundrule mcp 是一个 Model Context Protocol 服务（stdio），提供四个工具：

• list_standards：列出仓库中生效的规则，让 Agent 遵循这些规则。可离线使用。
• rules_for：列出适用于 Agent 即将修改的文件（按路径或语言匹配）的规则，优先显示阻止性规则，并说明如何遵守（ADR 0010）。服务的说明会告诉 Agent 在编辑文件前调用此工具；适用于所有位置的规则仍保留在 Agent 文件中。可离线使用。
• check：对 Agent 尚未提交的更改（或从某个 base 引用开始的更改，或所有文件）运行与 CI 相同的检查。它只列出此次更改引入的问题，以及问题位置和修复方法，让 Agent 在完成前修复这些问题。在连接到其工作区的仓库中，每条规则的计数会报告给工作区（见下文）。可离线使用。
• propose_rule：当你纠正 Agent，并表示（或同意）这条规则应适用于所有人时，它会将规则连同问题出现的位置提交到你组织的审核收件箱。审核者接受之前，不会发生任何更改。需要已连接的仓库和 groundrule login。

在每个仓库或每位用户的 Agent 中添加一次：

claude mcp add groundrule -- npx -y @groundrule/cli mcp          # Claude Code

{ "mcpServers": { "groundrule": { "command": "npx", "args": ["-y", "@groundrule/cli", "mcp"] } } }

对于 Cursor，JSON 格式的配置放在 .cursor/mcp.json 中；对于 VS Code，放在 .vscode/mcp.json 中（作为 servers）；也可以放在 Agent 的 MCP 设置中。提案会包含规则、原因，以及（如有提供）文件和行号；不会发送仓库中的其他内容。

Agent 完成时进行检查（钩子）

groundrule hooks 会添加一个停止钩子，让 Agent 每次完成任务时都运行检查，无论它是否记得运行：

npx @groundrule/cli hooks        # Claude Code, plus Codex, Cursor and Copilot if the repository uses them

Agent	文件	检查失败时
Claude Code	.claude/settings.json	阻止 Agent 完成，并告知它需要修复的内容。另一个钩子会在 Agent 编辑文件前告知它适用于该文件的规则，每个会话中每个文件一次（ADR 0010）
Codex	.codex/hooks.json	相同；每位开发者使用 /hooks 信任该钩子一次
Cursor	.cursor/hooks.json	通过后续消息告知需要修复的内容
Copilot（CLI 和云端 Agent）	.github/hooks/groundrule.json	Agent 会再进行一轮，并获知需要修复的内容

现有设置和钩子会保留。该钩子每轮只询问一次，因此无法修复问题的 Agent 不会被无限次要求继续；它也不会让 Agent 执行失败：如果未配置 Groundrule，它就不会执行任何操作。提交这些文件，让每位开发者的 Agent 都运行该钩子；再次运行 --remove 可移除钩子。

工作区会了解什么。 在配置中包含 platform: 的仓库里，当此计算机已登录时，钩子和 MCP check 工具会在 Agent 得出答案后向工作区发送报告（RFC 0012）：Agent 名称、发现问题的规则及其出现次数、已检查的文件和规则数量，以及 Agent 是否被阻止。绝不会发送路径、行号、代码片段，也不会发送 Agent 或你编写的任何内容。报告会在两秒超时后发送，所有失败都会被忽略，因此不会拖慢 Agent，也不会改变检查结果。工作区会用它来显示在提交创建前捕获了多少问题。platform.reports: none 可关闭此功能；groundrule doctor 会说明当前适用的设置。离线仓库不会发送任何内容。

检查项

评估器	来源	用途
files	确定性	必需或禁止的文件（CODEOWNERS、.env）
regex	确定性	代码中禁止或必需的模式
dependencies	确定性	禁止的包（npm、Maven、Gradle、pip、Go、Cargo）
change-set	确定性	关于更改的规则（“实体更改需要迁移”）
semgrep	静态分析	你已有的 Semgrep 规则
llm	AI	关于更改的问题，由 Groundrule 托管的检查回答（RFC 0013）；仅供参考，绝不会导致更改失败。在本地和 CI 中均报告为未运行

规则包

groundrule packs 会列出随附的规则包（安全、TypeScript/Node、React、Python、Java/Spring、Go、Docker、Kubernetes、Terraform、GitHub Actions、HTTP API、测试、AI Agent 卫生规范）。你所在组织自己的规则包也以相同方式使用：github:your-org/engineering-standards//packs/backend@v1。

GitHub

Metricall-AI-Lab/groundrule-action@v1 会检查每个拉取请求、生成作业摘要，并将检查结果上传到代码扫描。源代码位于 action/。

开发

pnpm install
pnpm check

请参阅 CONTRIBUTING.md。Groundrule 会检查自身：请参阅 .groundrule/。

许可证

Apache-2.0。“Groundrule”是商标；请参阅 GOVERNANCE.md。