Harness Score導入判断: AIコーディング基盤をCIで数値化すべきか

Cursor や Claude Code、GitHub Copilot などのAIコーディングエージェントを日常的に使うチームが増えています。ただし同じモデル・同じプロンプトを使っても、リポジトリごとに出力の質が大きく変わる場面に心当たりがあるなら、この記事が判断の参考になれば幸いです。

差を生んでいるのはモデルの性能ではなく「ハーネス」と呼ばれる土台です。ハーネスとは、エージェントに与えるガイド文書・ルール設定・スキル定義・フック（特定のイベントで自動実行される処理）・テスト・CIのフィードバックなど、エージェントを取り巻く仕組み全体を指します。この土台は多くの場合、少しずつ手作業で積み上げられ、誰も体系的に測っていません。あるプルリクエストが hooks.json を静かに削除したり、CIのゲート（品質基準を満たさないと先に進めない関門）を落としたりしても、エージェントが高コストな誤動作を起こすまで気づかれないことがあります。

この状況に対して、GitHub Actions（GitHubのCI/CD実行基盤）上でハーネスの成熟度をスコア化する harness-score というActionが公開されています。テストやLintと同じように、ハーネスにも「後戻りさせない仕組み（ラチェット）」を導入する発想です。導入するかどうかを決めるための判断軸を整理します。

判断が必要になる場面

複数のAIコーディングツールを併用しているリポジトリで、レビュー時に「なぜこのPRだけエージェントの出力が雑なのか」と感じたことがあるなら、ハーネスの劣化を疑う価値があります。

また新メンバーがAIエージェントを使い始めたときに、既存メンバーと同じ品質が出ないケースも同様です。原因がプロンプトの書き方ではなく、リポジトリ側のガイド・ルール・フックの欠落である可能性を検討する場面です。

判断軸1: 現状のハーネス成熟度をどこまで把握できているか

harness-score は Cursor、Claude Code、Windsurf、Cline、Continue、Codex、Copilot といった主要ツールの設定ファイルをスキャンし、証拠（ファイルシステム上の実体）に基づいてスコアを算出します。

重要な設計原則として、スキャン中にLLM（大規模言語モデル）へのAPI呼び出しは発生しません。ネットワーク通信もありません。同じコミットに対しては常に同じスコアが返ります。この決定性（deterministic）があるからこそ、CIのゲート条件として安全に使えます。

レベルはL0からL4まで6段階ではなく5段階で定義されています。

レベル	名称	状態の目安
L0	Unharnessed	エージェントが毎回プロジェクトを一から探る
L1	Documented	実質的なコンテキストファイルが存在
L2	Guided	スコープ付きルール・スキルと基本衛生がある
L3	Sensing	テスト・Lint・型検査・CIフィードバックが揃う
L4	Self-correcting	ゲートとフィードバックフックが循環を閉じる

まずローカルで試すだけなら、以下のコマンドで即座に確認できます。

npx [email protected]

自分のリポジトリが現在どのレベルにあるかを知らないまま導入是非を議論するのは非効率です。最初の一歩として、この単発実行で現状把握するのが妥当です。

判断軸2: CIにゲートを置くタイミングとして適切か

ローカルスキャンは有用ですが、CIに組み込んで初めて「契約」として機能します。GitHub Actionsのワークフローに追加すると、PRのジョブサマリーに6つの評価軸ごとの内訳が表示され、ベースブランチとのスコア差分をPRコメントとして自動更新できます。

ただし、いきなり min-level （最低要求レベル）を高く設定するのは避けるべきです。推奨される導入手順は段階的です。

name: Harness maturity
on:
  pull_request:
  push:
    branches: [main]
jobs:
  harness:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: paladini/harness-score@v1
        with:
          min-level: '0'  # まずは観測のみ
          badge: 'harness-badge.svg'
          report: 'harness-report.md'

1週目は min-level: '0' で観測に徹し、実際のスコアを確認します。2週目にその時点のレベルを min-level に設定してリグレッション（後退）を防ぎます。そこから1レベルずつ引き上げていくのが実務的な進め方です。

判断軸3: PRレビューのワークフローに乗せられるか

スコアをCheckタブの赤バツだけで終わらせず、レビュー中に見える形にしたいなら、スティッキーコメント機能を使います。pull_request イベントに対して comment: 'true' を設定すると、PRのヘッド（変更後）とベースブランチを比較し、単一のコメントを継続更新します。

on:
  pull_request:
permissions:
  contents: read
  pull-requests: write
jobs:
  harness:
    runs-on: ubuntu-latest
    concurrency:
      group: harness-score-${{ github.event.pull_request.number }}
      cancel-in-progress: false
    steps:
      - uses: actions/checkout@v4
      - uses: paladini/harness-score@v1
        with:
          min-level: '3'
          comment: 'true'
          badge: 'harness-badge.svg'

ここで注意すべきは権限設定です。pull-requests: write をワークフロー側で明示しないと、Actionはコメント投稿の権限を得られません。GitHub Actionsの権限モデル（permissions キーで細かく制御する仕組み）に馴染みがない場合は、既存のCIワークフローの permissions ブロックを確認してから追加してください。

判断軸4: サプライチェーンのリスク許容度

外部のGitHub Actionを組み込む以上、サプライチェーン攻撃（依存先が改ざんされることで被害が波及するリスク）への配慮が必要です。@v1 のようなタグ参照は、タグの向き先が変わるリスクを伴います。

セキュリティ要件が高いリポジトリでは、コミットSHA（変更不可能なハッシュ値）にピン留めする運用が無難です。社内のActions利用ポリシーで外部Action使用時のピン留めルールが決まっているか、事前に確認しておくと安心です。

選択肢の比較

AIハーネスの品質を担保する方法は harness-score 導入だけではありません。

アプローチ	コスト	可視性	決定性
harness-score導入	低（Action追加のみ）	PRコメント・バッジで高い	スキャンベースで確保
手動レビューのみ	レビュー時間分	属人的でばらつきあり	担当者依存
独自スクリプトで自作	高（設計・保守が必要）	設計次第	設計次第

手動レビューだけに頼る場合、hooks.json の削除やCIゲートの欠落といった「静かな劣化」を見逃すリスクは残ります。独自スクリプトを自作する選択肢もありますが、対応ツールの追跡・保守コストを考えると、既存のActionを使う方が投資対効果は高いと考えられます。

ケース別の推奨

複数人がCursorやClaude Codeを併用し、リポジトリごとに出力品質のばらつきを感じているなら、まずローカルで npx [email protected] を実行して現状を数値化するところから始めるのが妥当です。

すでにテストカバレッジやLintルールをCIゲートとして運用しているチームなら、同じ発想で min-level: '0' から観測を始め、2〜3週間かけて min-level を引き上げていく流れが自然にフィットします。

AIエージェントのコスト（トークン消費や誤動作による手戻り）が可視化された組織であれば、L3・Sensing以上をゲート条件にする価値は高いと考えられます。

あえて見送るべき条件

単一の開発者だけがAIエージェントを試験的に使っている段階では、CIゲート化は過剰です。PRレビューの仕組みが機能してから検討しても遅くありません。

また社内のGitHub Actions利用ポリシーが未整備で、外部Actionのピン留め運用ルールすら決まっていない場合は、先にそちらを整えるのが優先です。セキュリティレビューを通さずに write 権限を伴うActionを追加するのは避けるべきです。

CIの実行時間やジョブ数にすでに制約があるリポジトリでは、追加ジョブによるパイプライン全体の遅延も考慮する必要があります。

導入前に確認すること

判断に迷ったら、以下の順で確認するのが実践的です。

ローカルで npx [email protected] を実行し、現在のレベルを把握する
CIの permissions ブロックで pull-requests: write を追加できるか確認する
外部Actionのピン留めポリシーを社内で確認し、SHA固定が必要か判断する
min-level: '0' から始め、観測期間を経てから段階的にゲートを引き上げる

AIコーディングエージェントの出力品質は、モデル選定よりもリポジトリ側の土台に左右される場面が少なくありません。テストやLintに投資してきたのと同じ発想で、ハーネスの状態を数値として追跡する仕組みを検討してみてください。