ハーネス整備の効果を見極める3つの判断基準
この記事で学べること
- ハーネス整備後に観察した変化と、未測定のROIを分けて扱う方法
- 再現性・具体性・検証性の3条件で問題をルール化する判断基準
- ROIを測定する指標と、ハーネスへ移さない条件の決め方
繰り返す問題だけをハーネスへ移す
ハーネス（AIに渡すルール、作業手順、検証方法をまとめた仕組み）へ問題を移すかは、再発性、具体性、検証可能性で判断できます。このサイトでは、前提を共有ルールへ移し、レビュー観点を固定する変化を観察しました。一方、時間やエラー件数を測っていないため、ROIは観察した変化と未測定の効果を分けて扱います。
この記事では、「どの繰り返し問題をハーネス化し、その効果をどう測るべきか」という問いに焦点を当て、結論を分ける判断軸、適用条件、最初に確認する事項を扱います。
最後まで読むと、「どの繰り返し問題をハーネス化し、その効果をどう測るべきか」という問いを、自分の状況に照らして判断するための材料を持ち帰れます。
再発性・具体性・検証性でハーネス化を判断する
このサイトでは、ハーネス整備前後の作業時間、修正回数、レビュー指摘数を同じ条件で計測していません。そのため、「何%削減した」「投資を回収した」といった定量的な成果は示しません。
確認できるのは、英語の一人称、既存UIの維持、slug（公開URLで記事を識別する文字列）の形式など、繰り返し説明していた前提をリポジトリ内のルールへ移したことです。これは作業方法の変更であり、効果測定とは分けて扱います。
整備前は問題の条件が会話に閉じていた
同じ前提を依頼ごとに説明していた
日本語と英語の記事を同時に更新するときは、「英語の著者一人称はIを使う」「日本語を正本にする」といった前提を依頼ごとに書いていました。コード変更では、AstroとStarlightを使っていること、既存ナビゲーションを変えないこと、対象外のファイルを編集しないことを個別に伝えていました。
問題の背景が次の作業へ残らなかった
会話中に修正理由を説明しても、その理由がリポジトリに残らなければ、別のセッションや別の担当者は同じ判断条件を確認できません。単に「この表現は禁止」と伝えるだけでは、どの場面に適用するのか、何を検査すべきかが曖昧でした。
レビュー範囲を毎回決め直していた
変更対象と保護対象が依頼文だけにあると、レビュー時に「どこまで変更してよかったか」を会話へ戻って確認する必要があります。これはAI固有の問題というより、作業契約が成果物と別の場所にあることによる確認コストです。
整備後は前提と検査をリポジトリへ置いた
繰り返す前提を共有ルールに移した
英語の一人称、UI保護、slug形式などをルールファイルへ置き、ルートの指示ファイルから参照する構成にしました。これにより、依頼文へすべての前提を書かなくても、AIと人が同じ正本を確認できるようになりました。
Markdownのルールは行動を案内しますが、それだけで遵守を強制するものではありません。重要な条件は、検証スクリプト、権限設定、フック（特定のタイミングで処理を自動実行する仕組み）、CI（変更時に自動でテストや検査を行う仕組み）などの実行層でも確認します。
レビュー観点を固定した
「対象外ファイルを変更していないか」「日英のslugが一致しているか」のように、合否を判定できる項目へ変換しました。レビュー時間の短縮は計測していませんが、何を確認するかはリポジトリから追跡できます。
再発性・影響・検証可能性でハーネス化を判断する
| 判断条件 | 確認する問い | ハーネスへ移す目安 |
|---|---|---|
| 再現性 | 同じ種類の作業で再び起きるか | 一度きりではなく、条件を再現できる |
| 具体性 | 適用対象と期待動作を一文で示せるか | 「品質を上げる」ではなく、対象と禁止・許可を示せる |
| 検証性 | 守られたかを人またはスクリプトで確認できるか | ファイル、値、コマンド結果、レビュー項目で判定できる |
3条件が揃う問題は、会話上の注意から共有ルールや検証へ移す候補です。再現性が低い問題は作業メモ、具体性が不足する問題は仕様確認、検証できない問題は人のレビュー観点として残します。
ROIを判断するなら先に測定方法を決める
ハーネス整備の費用対効果を示す必要がある場合は、導入前後で比較できる指標を先に決めます。
- 同じ問題による再修正件数
- 依頼時に繰り返した前提説明の件数または時間
- 対象外ファイルの変更件数
- 公開前レビューで見つかったCritical件数
- 自動検査が検出した問題と、人が見つけた問題の内訳
期間、対象タスク、使用モデル、担当者、レビュー基準が変わると比較条件も変わります。測定していない場合は、「減った」ではなく「ルールへ移した」「検査できるようにした」と、確認できる変更だけを記述します。
ハーネスへ移さない条件も決める
一度しか起きない問題、適用条件を説明できない好み、成果物から確認できない抽象方針は、恒久ルールにしない方が保守しやすい場合があります。ルールが増えるほど読み込みと更新の負担も増えるため、次のいずれかに該当したら削除または別の文書へ移します。
- 対象となる機能や運用がなくなった
- 別の検証スクリプトが同じ条件をより確実に確認している
- 例外が多く、一文のルールでは誤判断を増やす
- 一度きりの判断記録で、繰り返し適用する必要がない
まとめ：再発性・具体性・検証可能性が揃う問題をハーネスへ移す
ハーネスへ移す候補は、繰り返し発生し、具体的に記述でき、結果を検証できる問題です。効果を定量化していない場合は、時間短縮や手戻り削減を断定せず、前提を共有ルールへ移したこと、レビュー観点を固定したこと、機械検査を追加したことを分けて記録します。まず1つの繰り返す問題を選び、適用条件と合否判定を書けるか確認するところから始められます。