harness-engineering

ハーネスエンジニアリング

ハーネスエンジニアリングは、コーディングエージェントが繰り返すミスを、リポジトリに定着する成果物へと変えます。

Harness = Instructions + Constraints + Feedback + Memory + Evaluation + Governance

次の依頼を受けた場合は、このスキルを使用してください。

• GitHub Copilot などのコーディングエージェントがより確実に作業できるよう、リポジトリを改善する
• 永続的なエージェント向け指示、リポジトリのルール、またはガードレールを追加する
• AI コーディングエージェントが繰り返すミスを防ぐ
• 既知の失敗パターンと、再発を防ぐチェックを記録する
• プロジェクトのルールに対する軽量なドリフトチェックを追加する
• 既存のエージェントハーネスをレビュー、更新、または整備する

ユーザーがリポジトリのエージェント実行環境の改善を求めていない限り、通常の機能実装にはこのスキルを使用しないでください。

基本原則

• 対象リポジトリを信頼できる情報源として扱います。
• 編集の前に調査します。既存の技術スタック、パッケージマネージャー、CI、ドキュメント、命名規則、アーキテクチャを維持します。
• 有用な最小限のハーネスを追加します。重複するガイダンスを追加するより、既存ファイルの更新を優先します。
• 重要なルールは、可能な限りテスト、リンター、型チェック、CI、pre-commit フック、またはドリフトスクリプトで強制できるようにします。
• 自動化が不安定になったり、誤解を招いたりする場合に限り、手動レビューのチェックポイントを設けます。
• 再発させてはならない重大なリスクの高い失敗を記録し、再発を検出するチェックまたはレビューポイントを明記します。
• 汎用テンプレートをそのままコピーしないでください。各成果物を、対象リポジトリの実際の根拠に合わせて調整します。

調査

ハーネスの変更を提案または実施する前に、既存のルールと根拠をリポジトリ内で調査してください。

次のファイルやフォルダーがある場合は、読み込んでください。

• README.md
• AGENTS.md
• .github/copilot-instructions.md
• .github/instructions/
• .github/workflows/
• CONTRIBUTING.md
• package.json、pyproject.toml、go.mod、Cargo.toml、pom.xml、build.gradle などのパッケージマニフェスト
• docs/ 以下の既存ドキュメント
• scripts/ 以下の既存スクリプト
• 既存のテストと CI チェック

そのうえで、次の内容を要約してください。

• 技術スタック、パッケージマネージャー、エントリーポイント
• 既存の開発コマンドと検証コマンド
• 現在のエージェント向け指示やリポジトリの規約
• 既知の障害、インシデント、不安定な処理経路、繰り返し寄せられるレビューコメント
• プロジェクトのルールが強制されていない箇所

導入ワークフロー

次の順序で進めてください。

1. 対象リポジトリに適したハーネスの導入箇所を選びます。
2. 対象に合わせたエージェント向け指示を作成します。
3. 重要度の高いルールを強制するチェックを追加します。
4. リスクが高い、または繰り返し発生する失敗を記録します。
5. 古くなっても気づかれにくいガイダンスにはドリフトチェックを追加します。
6. 根拠、前提、今後の対応を示して、導入内容を報告します。

1. ハーネスの導入箇所を選ぶ

対象リポジトリに適した箇所だけを選んでください。

必要なもの	推奨する成果物
エージェントに常時適用する動作	AGENTS.md または .github/copilot-instructions.md
ファイル単位のガイダンス	.github/instructions/*.instructions.md
定期的に実施するプロジェクトチェック	scripts/check_*.py、シェルスクリプト、またはパッケージスクリプト
CI による強制	既存のワークフローファイル、または小規模な新規ワークフロー
既知の失敗	docs/failures/*.md
アーキテクチャやプロセスに関する決定	docs/decisions/*.md
導入の根拠	docs/harness/adoption-report.md など

リポジトリに同等の導入箇所がすでにある場合は、別の仕組みを作成せず、既存のものを更新してください。

2. エージェント向け指示を作成する

エージェント向け指示は、具体的で実務に役立つ内容にしてください。次の事項を含めます。

• プロジェクトの目的と主要な担当範囲
• セットアップ、テスト、リンター、ビルド、検証の各コマンド
• パッケージマネージャーと依存関係のルール
• 安全な編集ルール、生成ファイルのルール、編集禁止のパス
• 変更したコードに対するテストの要件
• リポジトリに存在する場合は、PR とコミットの規約
• 新たな失敗や決定の記録方法

漠然とした性格に関する指針、一般的なベストプラクティス、チェックやレビューができないルールは避けてください。

3. 強制可能なチェックを追加する

価値の高いルールをチェックに変換します。優れたハーネスチェックは次の条件を満たします。

• 誤検知を避けられるよう、対象が十分に絞り込まれている
• ローカルとCIの両方で十分速く実行できる
• エージェントが作業完了前に実行できるよう、明確な名前が付いている
• 守っているルールとともに文書化されている

例:

Rule: Do not edit generated API clients.
Check: script scans diffs for generated paths and fails with a clear message.

Rule: Every failure memory note names a regression check.
Check: script validates docs/failures/*.md for a "Detection" section.

Rule: Profile docs and templates must stay aligned.
Check: test compares profile README files to expected template files.

4. 失敗の記録を残す

ユーザーに見える失敗、リスクの高い失敗、または再発しやすい失敗は記録します。 同じ根本原因を既存のメモがすでに扱っている場合を除き、docs/failures/ 配下に新しいファイルを作成してください。

推奨される構成:

# Short Failure Title

## Summary

What failed, who saw it, and why it matters.

## Root Cause

The technical or process cause. Avoid blame.

## Prevention

Instruction, test, drift check, CI gate, fixture, or manual review point that
prevents or detects recurrence.

## Evidence

Links to issue, PR, test, log, command output, or file paths.

自動化されたチェックが現実的でない場合は、手動レビューのポイントと、自動化が安全でない、または誤解を招く理由を記録してください。

5. ドリフトチェックを追加する

静かに古くなりうるガイダンスには、ドリフトチェックを使用します。よくある例は次のとおりです。

• ドキュメントが、もう存在しないコマンドに言及している
• プロファイルのスニペットと生成された例が食い違っている
• 失敗メモに回帰テストのチェックが欠けている
• 構造的な変更に対する決定記録が欠けている
• CI が古いスクリプトやパッケージコマンドを参照している

リポジトリで既に使われている言語で書かれた小さなスクリプトを優先してください。リポジトリにスクリプトの慣習がない場合は、標準ライブラリのみを使う Python が移植性の高い既定の選択肢です。

6. 導入レポートを作成する

大規模なハーネス作業は、次の内容を含む導入レポートで締めくくってください。

• 変更したファイル
• 追加または更新したルール
• 追加または再利用したチェック
• 実行したコマンドと結果
• 前提条件と手動でのフォローアップ事項
• 作成した、または意図的にスキップした失敗メモ
• 有効性をどのように測定するか

レビューのワークフロー

ハーネスの変更をレビューするよう求められたら、反対の立場から検討してください。次の点を探します。

• 対象リポジトリに根拠なく、一般論としてコピーされたルール
• 重複または競合する指示ファイル
• 有効な変更でも失敗しそうな広範なチェック
• 強制されていないリスクの高いルール
• 繰り返し発生するミスや実行時の失敗に対する失敗メモの欠落
• ソースの変更後に更新されていない生成済みドキュメント
• 関連するチェックを実行しない CI ゲート
• ハーネスの既定値によって上書きされた、対象リポジトリの慣習

指摘事項は、重大度順にまず報告してください。利用可能な場合は、ファイルと行の参照を付けてください。ユーザーが明示的に修正を求めない限り、レビュー中にファイルを変更しないでください。

出力の契約

ハーネス導入作業を終える前に、次を確認してください。

• 編集の前に、対象リポジトリを調査していること
• 新しいガイダンスが対象リポジトリに固有のものであること
• 変更したチェックをローカルで実行できること、または手動での代替手順が文書化されていること
• 必要な場合は失敗メモを記録していること、または記録しなかった理由を最終レスポンスで説明していること
• 生成されたドキュメントや索引が更新されていること
• 最終レポートで、実行したすべてのコマンドとその結果を明記していること

任意の参考資料

https://github.com/baskduf/harness-starter-kit のプロンプト優先ワークフローは、これらの考え方の参照実装です。ユーザーが求めた場合、またはリポジトリにすでに含まれている場合にのみ、参考資料として使用してください。対象リポジトリが引き続き唯一の情報源です。