Groundrule

Groundrule

エンジニアリング標準をすべてのコーディングエージェントに教え、すべてのPRでチェックします。

標準を一度だけ、Gitに小さなYAMLファイルとして記述します。Groundruleは次のことを行います。

• コーディングエージェントに教えます。 適用される標準だけを含む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]	コーディングエージェントへの指示を書き込み（または検証し）ます。--uploadは、リポジトリがエージェントに提供する内容を報告します
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	設定、ツール、エージェントファイルをチェックします
groundrule packs	バンドルされたパックを一覧表示します
groundrule scan [--json] [--upload]	このリポジトリをカタログ全体に照らして調査します。スタック、エージェントファイル、ツール、および各ルールが現時点でどう機能するかを確認します。変更は行いません
groundrule propose "<rule>"	プラットフォーム上でチームがレビューするルールを提案します。--why、--example、--file path[:line]
groundrule mcp	MCP経由でコーディングエージェントに標準を提供し、変更のチェックやルールの提案を可能にします（下記参照）
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 を使用します。レポートには件数と、ルールごとに最大3件の、1行に収まる編集済みスニペットが含まれます（セキュリティルールでは含まれず、--no-snippets を指定した場合は一切含まれません）。--json を指定すると、送信される内容を正確に確認できます。アップロード時には、チェック機能を持つ組織独自のルールも、ドラフトを含めてスキャンされるため、公開前にその影響を確認できます。

groundrule check --upload は結果をコンプライアンス記録として組織に送信します（RFC 0007）。記録には、有効だったルール（同じルールを使う人なら誰でも再計算できるダイジェストとして記録）、各ルールのバージョン、ロールアウト段階、変更を失敗にできるかどうか、適用された例外、変更に含まれるコミットが申告するコーディングエージェントが含まれます。最後の項目は Co-Authored-By トレーラーとボットの作成者から取得されます（件数のみを記録し、コミットメッセージやメールアドレスは記録しません）。エージェント数は申告であり、証明ではありません。含めない場合は --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 のルールをエージェントファイルに書き込みます。check は Enforce のルールを設定どおりに実行し、Advise のルールは警告として扱います。リポジトリで .groundrule/standards/ に定義したルールも引き続き適用されます。CI では、Settings → API tokens で取得したトークンを GROUNDRULE_TOKEN に設定します。サインイン情報は ~/.config/groundrule/credentials.json に保存され、自分だけが読み取れます。

コーディングエージェント（MCP）

groundrule mcp は、4 つのツールを備えた Model Context Protocol サーバー（stdio）です。

• list_standards：リポジトリで適用されるルールを返し、エージェントがそれに従えるようにします。オフラインで動作します。
• rules_for：エージェントが変更しようとしているファイル（パスまたは言語で指定）に該当するルールを、まずブロックするルールから返し、遵守方法も示します（ADR 0010）。サーバーの指示により、エージェントはファイルを編集する前にこのツールを呼び出します。どこでも適用されるルールは、エージェントファイルに記載したままにします。オフラインで動作します。
• check：エージェントの未コミットの変更（または base 参照以降、あるいは all ファイル）を対象に、CI と同じチェックを実行します。変更によって導入された項目だけを、場所と修正方法とともに一覧表示するため、エージェントは作業を終える前に修正できます。オフラインで動作します。ワークスペースに接続されたリポジトリでは、ルールごとの件数がワークスペースに報告されます（下記参照）。
• propose_rule：エージェントを修正し、そのルールを全員に適用すべきだと伝える（または同意する）と、そのルールが出てきた場所とともに、組織のレビュー受信箱にルールを提案します。レビュー担当者が承認するまで、何も変更されません。接続されたリポジトリと groundrule login が必要です。

リポジトリまたはユーザーごとに一度、エージェントに追加します。

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

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

JSON 形式の設定は、Cursor の場合は .cursor/mcp.json、VS Code の場合は .vscode/mcp.json（servers として）、またはエージェントの MCP 設定に記述します。提案にはルール、理由、指定されていればファイルと行が含まれます。リポジトリからそれ以外の情報が送信されることはありません。

エージェントの作業終了時にチェックする（フック）

groundrule hooks はストップフックを追加し、エージェントが忘れていた場合も含め、タスクを終えるたびにチェックを実行します。

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

エージェント	ファイル	チェックに失敗した場合
Claude Code	.claude/settings.json	エージェントは作業を終えられないようにされ、修正すべき内容が伝えられます。もう一つのフックは、ファイルごと、セッションごとに一度、編集の直前にそのファイルのルールをエージェントに伝えます（ADR 0010）
Codex	.codex/hooks.json	同様です。各開発者は /hooks でフックを一度信頼します
Cursor	.cursor/hooks.json	修正すべき内容がフォローアップメッセージとして送信されます
Copilot（CLI とクラウドエージェント）	.github/hooks/groundrule.json	エージェントは修正すべき内容を受けて、もう一度処理します

既存の設定とフックは維持されます。フックはターンごとに一度だけ確認するため、何かを修正できないエージェントがいつまでも処理を続けることはありません。また、エージェントが失敗することもありません。Groundrule の設定がなければ、フックは何もしません。すべての開発者のエージェントで実行されるよう、ファイルをコミットしてください。--remove を指定すると、フックを削除できます。

ワークスペースが学習する内容。 設定に platform: があるリポジトリで、このコンピューターがサインインしている場合、エージェントが回答を得た後に、フックと MCP の check ツールがレポートをワークスペースに送信します（RFC 0012）。レポートには、エージェント名、問題が見つかったルールとその検出回数、チェックしたファイルとルールの数、エージェントが停止されたかどうかが含まれます。パス、行、スニペット、エージェントまたはユーザーが書いた内容は一切含まれません。送信はタイムアウトが 2 秒に設定され、すべての失敗は無視されるため、エージェントの処理が遅くなったり、チェックの結果が変わったりすることはありません。ワークスペースはこの情報を使って、コミットが存在する前にどれだけの問題を検出できているかを表示します。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 エージェントの衛生管理）を一覧表示できます。組織独自のパックも同じ方法で使えます：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 を参照してください。