coverctl

coverctl

あらゆる言語に対応するエージェントループ向けカバレッジガバナンス — CI 後に読むダッシュボードではなく、コミット前に AI コーディングエージェントが呼び出すカバレッジです。

Python、TypeScript/JavaScript、Java、Rust、Go、C#、C/C++、PHP、Ruby、Swift、Dart、Scala、Elixir、Shell に対応 — .coverctl.yaml は 1 つ、MCP のインターフェースも 1 つです。Go 専用のカバレッジツールではありません。

使い始める ↓ · 言語 ↓ · 動作例 ↓ · MCP ツール ↓ · CLI リファレンス ↓ · このツールの目的 ↓ · コミュニティ ↓

「AI エージェントはコードをすばやくリリースしますが、編集中はカバレッジポリシーを把握できません。問題に気づくのは CI の実行後で、そのときにはコンテキストが失われています。そして同じエージェントが、今度は推測で修正しようとします。」

すべての言語で同じポリシーモデルを使用します。ランナーを自動検出し、パスをドメインごとにまとめ、コミット前に最低基準を適用します。モックを多用するレイアウトや特殊なレイアウトでは、.coverctl.yaml に domains: ブロックを明示的に指定する必要がある場合があります。

coverctl は Go 専用のカバレッジ CLI ではありません。各言語のネイティブなカバレッジランナーの上にポリシーと MCP を提供します（go test -cover / pytest --cov との比較）。

使い始める

brew install klarlabs-studio/tap/coverctl

Claude Code に接続します（~/.config/claude-code/mcp.json）：

{
  "mcpServers": {
    "coverctl": {
      "command": "coverctl",
      "args": ["mcp", "serve"]
    }
  }
}

エージェントに次のように尋ねます：「coverctl check を実行して、後退したドメインを教えてください。」

Cursor / Cline / Claude Desktop / Aider / Continue / OpenCode やその他の MCP クライアントについては、docs/src/content/docs/mcp.mdx を参照してください。MCP 対応クライアントならすべて動作します。coverctl mcp serve はデフォルトでエージェントモード（3 つのツール：check、suggest、debt）で実行されます。ツールを 9 つすべて使用するには --mode=ci を指定します。

インストールが最初から最後まで正しく動作することを確認します：

coverctl mcp doctor   # PASS/FAIL per step with remediation

エージェントループでの動作例

見やすさのために表示しています。クライアントによってツール呼び出しの表示形式は異なる場合があります。

You:    Add the email-validation feature to the api domain.

Claude: I'll add EmailValidator + tests under src/api/.

  [edits: src/api/email.ts, src/api/email.test.ts]

  Tool call → coverctl check
  Result   → passed: false; failing: api (78.2%, required 80%)
             uncovered: src/api/email.ts:42-58 (error paths)

  Tool call → coverctl suggest api
  Result   → uncovered files: email.ts (16 lines), retry.ts (4 lines)

  Two error branches in EmailValidator.validate are uncovered.
  I'll add cases for empty-input and malformed-domain so api meets
  the 80% threshold before we commit.

以前は CI で 8 分後に発覚していたリグレッションが、同じエージェントのターン内で修正されます。

エージェントがうまく対応できること： check の出力をそのまま読み取り、suggest を呼び出して未カバーのファイルを見つけ、debt を呼び出して最小の修正を優先順位付けし、再度 check を実行して確認します。

注意点： 失敗を「修正」するために、エージェントが .coverctl.yaml のしきい値を下げることがあります（これは修正ではありません）。新たに check を呼び出さずに、カバレッジが上がったと主張することがあります（幻覚です）。拒否時の error_code を無視し、同じ入力で再試行することがあります。

coverctl は決定的な構造化シグナルを返しますが、エージェントの 修正 には人による確認が必要です。契約の全容については、docs/src/content/docs/mcp.mdx を参照してください。

これが存在する理由

AI コーディングエージェントは、カバレッジが見えない状態でコードを書きます。エージェントが編集し、あなたがコミットすると、リグレッションが数分から数時間後に CI で表面化します。同じセッション内で軌道修正するには遅すぎます。ダッシュボード（Codecov、Coveralls）や言語標準のランナー（go test -cover、pytest --cov、nyc）は、事後に数値を読む人間を対象としており、編集中にポリシーを適用するエージェント向けではありません。

coverctl はエージェントのループ向けに構築されています（Go のカバレッジツールを置き換えるものではありません）。

• コミット前にリグレッションを検出します。 カバレッジのフィードバックは、CI の失敗から数分後ではなく、エージェントの編集ターン中に得られます。最重要指標はコミット前に検出したリグレッションです。
• MCP 経由でエージェントから呼び出せます。 MCP を使用します。これは現在 Anthropic、OpenAI、Google、Microsoft、AWS が統括する、マルチベンダー対応のエージェントツール標準です。現在 MCP に対応するすべてのクライアントで動作し、今後リリースされるものにも変更なしで対応します。
• 多言語のガバナンスを単一の設定で実現します。 1 つの .coverctl.yaml で、15 言語にわたるドメインごとのしきい値を適用します。Go リポジトリでは、ほかの場所で pytest を呼び出すのと同様に go test を呼び出す場合があります。その後、同じドメインポリシーを適用します。エージェントはあらゆる言語を扱うため、カバレッジガバナンスも同様に対応する必要があります。
• ローカルファーストです。 ソースがマシンの外に出ることはありません。エージェントは SaaS API 経由ではなく、stdio 経由で coverctl を呼び出します。アカウントもアップロードも不要で、エージェントがアクセスできる範囲にサードパーティの依存関係はありません。
• MCP のインターフェースを堅牢化しています。 入力と出力のサニタイズにより、テストランナーのフラグやカバレッジプロファイル内の悪意あるファイル名を通じたプロンプトインジェクションを防ぎます（Lethal Trifecta）。

CLI と MCP サーバーは Apache-2.0 ライセンスで、今後も無料です。リポジトリをまたいだカバレッジ履歴を追跡するホスト型レイヤーはロードマップにあります（docs/strategy/monetization-decision.md を参照）。これは追加機能であり、有料の壁ではありません。

MCP ツール

エージェントモードでは、確実にツールを選択できるよう、3 つのツール（check、suggest、debt）を公開します。CI モード（--mode=ci）では、残りのツールも追加されます。

ツール	モード	目的
check	エージェント＋CI	カバレッジを取得しながらテストを実行し、ポリシーを適用します。ドメインごとの合否、ファイル、警告を返します。
suggest	エージェント＋CI	しきい値（current／aggressive／conservative）を提案します。
debt	エージェント＋CI	ドメインごとのカバレッジ不足を示し、優先順位を付けて取り組むべき箇所を提示します。
init	CI	プロジェクト構成を自動検出し、ドメインポリシーを含む .coverctl.yaml を作成します。
report	CI	テストを実行せずに、既存のカバレッジプロファイルを分析します。
record	CI	傾向を追跡するため、現在のカバレッジを履歴に記録します。
compare	CI	2 つのカバレッジプロファイルを比較します。差分、改善またはリグレッションがあったファイル、ドメインの変更を返します。
badge	CI	SVG カバレッジバッジを生成します。
pr-comment	CI	カバレッジレポートを GitHub／GitLab／Bitbucket の PR に投稿します。

MCP リソース（読み取り専用のコンテキスト）

URI	内容
coverctl://debt	カバレッジの負債を JSON 形式で示します。
coverctl://trend	記録された履歴に基づく傾向を示します。
coverctl://suggest	しきい値の提案を示します。
coverctl://config	検出されたプロジェクト設定を示します。

セキュリティ境界

coverctl は、Lethal Trifecta の脅威モデルに従い、双方向の MCP トラフィックを信頼できないものとして扱います。

• 入力境界。 エージェントモードでは、型付きの機能（packages、tags、race、short、run、timeout）を受け付け、任意の runner testArgs は拒否するため、coverctl を汎用コマンド実行 MCP サーバーとして使用できません。危険なフラグ（--rootdir、--cov-config、-D、-I、--require、--init-script、--node-options、...）も、多層防御のため拒否されます。エージェントモードでは、別のポリシーファイルを選択したり、チェック対象を一部のドメインに絞り込んだり、coverageScope を狭めたり（測定範囲を縮小すると、未テストのドメインが隠れるおそれがあります）、fromProfile でテスト実行を省略したり、増分チェックを使用したり（差分が空の場合、自動的に合格します）することはできません。リポジトリの .coverctl.yaml が正とされ、検証ではポリシー全体を対象にテストを実行する必要があります。拒否応答では、安定したスキーマに従って error_code と、エージェントが対応に利用できる remediation を返します。人間がターミナルから実行する CLI 呼び出しはサニタイズされません。その場合、人間が信頼境界となります。
• 出力境界。 エージェントに返されるユーザー制御の識別子（カバレッジプロファイル内のファイル名、ドメイン名、パッケージパス）は、破壊的に置き換えずパーセントエンコードされるため、異なる名前が同一化されません（src/über.go が別のファイルに化けることはありません）。制御文字、バッククォート、Markdown のメタ文字は、指示として表示されません。悪意のある PR や攻撃者が命名したテストファイルによる、戻りの通信を介したプロンプトインジェクションを防ぎます。

coverctl はローカルファーストです。デフォルトのインストールでは、テレメトリー、アナリティクス、ソースデータを含め、何も送信されません。独自のパイプラインを計測したいユーザー向けに、オプトインの --mcp-telemetry フラグを指定すると、構造化されたツール呼び出しイベントが stderr に出力されます（形式は docs/design/mcp-metrics-spec.md に記載されています）。敵対的シナリオと正常系の評価（internal/eval/scenarios/ にある 85 件以上のシナリオ）により、拒否スキーマの完全性とプロンプトインジェクション耐性がすべてのリリースで審査されます。

正規の意図：docs/strategy/system-intent.md。 脅威モデルの全文と残存リスク：docs/security/mcp-threat-model.md。

CLI リファレンス

CLI は MCP サーバーの基盤であり、人間が直接使用することもできます。

コマンド	目的
init / i	対話型ウィザードで、言語とドメインを自動検出します。CI では --no-interactive を指定します。
check / c	カバレッジを測定し、ポリシーを適用します。機械可読な出力には -o json、--fail-under N、--ratchet、--from-profile を指定します。
run / r	ポリシー評価を行わず、カバレッジ成果物を生成します。
watch / w	開発中、ファイルの変更時にカバレッジを再実行します。
report	既存のプロファイルを評価します。-o html、--uncovered、--diff <ref>、--merge <profile> を指定します。
detect	ドメインを自動検出し、設定を書き込みます。プレビューには --dry-run を指定します。
badge	SVG カバレッジバッジを生成します。--style flat-square を指定します。
compare	2 つのプロファイルの差分を表示します。
debt	カバレッジ負債レポートを生成します。
trend	記録済みの履歴からカバレッジの傾向を表示します。
record	現在のカバレッジを履歴に追加します。CI では --commit、--branch を指定します。
suggest	しきい値を提案します。適用するには --write-config を指定します。
pr-comment	カバレッジを GitHub/GitLab/Bitbucket の PR に投稿します。
ignore	設定済みの除外項目と追跡対象のドメインを表示します。
mcp serve	MCP サーバーを起動します（stdio）。--mode=agent|ci|auto を指定します。
mcp doctor	初回実行時の検証を行い、各手順の PASS/FAIL と対処方法を表示します。
survey	Sean Ellis の 40% PMF プロンプトを表示し、~/.coverctl/survey.jsonl に追記します。

グローバルフラグ：-q/--quiet、--no-color、--ci（quiet と GitHub Actions の注釈を組み合わせます）。

テスト実行フラグ

check、run、record は、基盤となるテストランナーに転送されるツールチェーンフラグを受け付けます。

フラグ	例
--tags	--tags integration,e2e
--race	（Go のレース検出器）
--short	実行時間の長いテストをスキップします
-v	詳細なテスト出力
--run	--run TestFoo
--timeout	--timeout 30m
--test-arg	繰り返し指定できます：--test-arg=-count=1 --test-arg=-parallel=4
--language / -l	自動検出を上書きします：python、javascript、typescript、java、rust、go、csharp、cpp、php、ruby、swift、dart、scala、elixir、shell

ターミナルでの実行（エージェントなし）

coverctl を直接実行する場合：

coverctl init      # auto-detect language + domains, write .coverctl.yaml
coverctl check     # enforce policy; exit 1 on violation
coverctl suggest --strategy current
coverctl record

手順が失敗した場合：coverctl detect --dry-run で init の出力を事前に確認できます。coverctl check -o json で構造化された失敗の詳細を確認できます。coverctl record --commit "$(git rev-parse HEAD)" --branch "$(git rev-parse --abbrev-ref HEAD)" で、CI 内でメタデータを明示的に指定できます。

設定

.coverctl.yaml（スキーマ：schemas/coverctl.schema.json）：

ドメインは名前付きのパスグループであり、言語パッケージではありません。match は、ほとんどの言語ではパスのグロブ（src/auth/**）、Go プロジェクトでは Go のパッケージパス（./internal/auth/...）を使用します。

version: 1
policy:
  default:
    min: 75
  domains:
    - name: auth
      match: ["src/auth/**"]   # Go equivalent: ["./internal/auth/..."]
      min: 90                   # critical path — stricter
    - name: api
      match: ["src/api/**"]
      min: 80
    - name: utils
      match: ["src/utils/**"]
      # falls back to default min: 75
exclude:
  - "**/generated/**"

ドメインごとの適用が重要です。全体のカバレッジでは、重要なパスでのリグレッションが見えなくなります。coverctl は各ドメインをそれぞれの最小値と照合して評価し、いずれかのドメインが下回るとビルドを失敗させます。言語ごとのスターター設定については、ドキュメントのクイックスタートを参照してください。標準のテストランナーとの違いについては、ネイティブカバレッジとの比較を参照してください。

Go のみの補足：通常の go test ./... と数値が異なる理由

Go プロジェクトでは、coverctl は設定済みドメインにまたがる -coverpkg を渡す場合があります。これにより、あるパッケージを使用する他のパッケージのテストでも、そのパッケージにカバレッジが加算されます。通常の go test ./... では、パッケージ自身のテストのみが加算されます。どちらも正当な数値であり、coverctl の数値のほうが通常は高くなります。これは Go のテストランナーの動作であり、製品のモデルによるものではありません。履歴を比較する場合は、coverctl check のプロファイルを使用してください。--from-profile は、指定されたプロファイルで測定された値をそのまま報告します。

高度な設定

files:
  - match: ["internal/core/*.go"]
    min: 90                          # per-file overrides
diff:
  enabled: true
  base: origin/main                  # only enforce on changed files
integration:
  enabled: true                      # Go 1.20+ GOCOVERDIR integration tests
  packages: ["./internal/integration/..."]
  cover_dir: ".cover/integration"
  profile: ".cover/integration.out"
merge:
  profiles: [".cover/unit.out", ".cover/integration.out"]
annotations:
  enabled: true                      # // coverctl:ignore, // coverctl:domain=NAME

複数のパッケージからなるモノレポですか？extends: を使ってポリシーを継承してください。最初の設定には、templates/coverctl.yaml をコピーしてください。

対応言語

15 言語に対応する単一の製品です。coverctl は呼び出すテストランナーを自動検出するため、パスドメインを一度設定すれば済みます。

言語	形式	検出マーカー
Python	Cobertura、LCOV	pyproject.toml、setup.py、requirements.txt
TypeScript / JavaScript	LCOV	tsconfig.json、package.json
Java / Kotlin	JaCoCo、Cobertura	pom.xml、build.gradle
Rust	LCOV（cargo-llvm-cov）	Cargo.toml
Go	ネイティブのカバレッジプロファイル	go.mod、go.sum
C# / .NET	Cobertura（coverlet）	*.csproj、*.sln
C / C++	LCOV（gcov/lcov）	CMakeLists.txt、meson.build
PHP	Cobertura（PHPUnit）	composer.json、phpunit.xml
Ruby	LCOV（SimpleCov）	Gemfile、Rakefile
Swift	LCOV（llvm-cov）	Package.swift
Dart	LCOV（dart test）	pubspec.yaml
Scala	Cobertura（scoverage）	build.sbt
Elixir	LCOV（mix test）	mix.exs
Shell	Cobertura（kcov）	*.bats

言語ごとの設定例については、ドキュメントのクイックスタートを参照してください。

GitHub Action

jobs:
  coverage:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-go@v6
        with:
          go-version: "1.25"
      - uses: ./.github/actions/coverctl
        with:
          command: check
          config: .coverctl.yaml
          output: text

プラットフォーム／開発者体験チーム向け

多数の多言語リポジトリにわたるカバレッジポリシーを標準化していますか？ coverctl には、セキュリティ審査や調達審査で求められる成果物が揃っています。

• MCP 脅威モデル — 入力と出力の境界制御、プロンプトインジェクション対策、残存リスク。
• 拒否スキーマのリファレンス — エージェントの復旧を支援する、安定した error_code + remediation の契約。
• GTM ファネル指標の仕様 — 計測対象と、テレメトリをオプトイン方式に保つ仕組み。

coverctl の組織全体への導入を検討していますか？GitHub issue を platform-evaluation ラベル付きで作成してください。アーキテクチャと信頼境界について喜んでご説明します。

コミュニティ

• Claude Code Plugin Marketplace — /plugin install を使って coverctl を直接インストールできます。
• MCP Registry — registry.modelcontextprotocol.io に登録されています。
• GitHub Discussions — go.klarlabs.de/coverctl/discussions。
• coverctl の開発をスポンサーする — github.com/sponsors/felixgeelhaar。

coverctl を数週間使いましたか？coverctl survey を実行して PMF に関するフィードバックをお寄せください（デフォルトではローカルのみで処理され、オプトインしない限り何も送信されません）。

Felix Geelhaar が、多言語 AI コーディングコミュニティからの貢献とともに開発しました。

貢献

• TDD：動作を変更する前にテストを作成してください。
• 各ドメインの .coverctl.yaml にある min を満たしてください（未設定の場合、デフォルトは 80% です）。このリポジトリは Go で作られているため、go run ./cmd/coverctl check で実地検証してください（これはランナーに対するポリシーであり、go test の失敗内容を読む代わりにはなりません）。
• Relicta のバージョン更新ロジックのため、Conventional Commits（feat:、fix:、chore:、...）を使用してください。
• main は保護されています。CI がすべて成功（.github/workflows/go.yml + .github/workflows/eval.yml）した後、PR 経由でマージしてください。
• プッシュする前に gofmt -w と golangci-lint v2 を実行してください。

貢献者向けのアーキテクチャの詳細：ARCHITECTURE.md。

リリース

Relicta で管理されています。v* タグを手動でプッシュしないでください。

セキュリティ

開示ポリシーについては SECURITY.md を参照してください。MCP 入力のサニタイズ（internal/mcp/sanitize.go）と出力の正規化（internal/mcp/sanitize_output.go）が、プロンプトインジェクションに起因する引数やコンテンツへの攻撃に対する主な防御策です。回避方法を発見した場合は、非公開で報告してください。