/harness

harness は何をしますか？

Harness Engineering 最小実践。 3つの制約ロール（Inspector、Worker、Reviewer）でAIの創造性を正しい軌道に乗せ、TODO.md共有ボードで継続的改善を推進します。発想はHarness Engineeringメソッドに基づいています。軽量でありながら確定的なプロセスフレームワークにより、AIエージェントを「自由な発揮」から「予測可能な高品質成果物のデリバリー」へと導きます。

トリガー条件

即時実行

• ユーザー入力 /harness — 完全サイクル（Inspector + Worker + Reviewerループ）
• ユーザー入力 /harness inspect — Inspectorのみ実行
• ユーザー入力 /harness work — Worker + Reviewerを1回実行
• ユーザー入力 /harness loop — タスクがなくなるまでWorker + Reviewerを継続実行

ユーザーはコマンドの後に自然言語の指示を付与でき、追加のコンテキストとして渡せます。例：

• /harness 今回はサイレントデータ損失に注目して
• /harness work まずP0の環境変数検出を修正して
• /harness inspect 現在のスケルトン目標だけを校正し、Workerは実行しない

定期スケジュール（cron）

Claude CodeのCronCreate/CronDelete/CronListツールを利用します。セッションは原則として分離されており、異なるセッションのcronは互いに影響しません。

コマンド	説明
/harness cron "*/30 * * * *"	30分ごとにフルサイクルを実行
/harness cron "*/30 * * * *" inspect	30分ごとにInspectorのみ実行
/harness cron "0 */2 * * *" work	2時間ごとにWorker+Reviewerを実行
/harness cron "*/15 * * * *" loop	15分ごとにタスクを消化し続ける
/harness cron list	現在のセッションの全harness cronを表示
/harness cron stop <job_id>	指定したcronを削除
/harness cron stop	現在のセッションの全harness cronを削除（対話確認後、1つずつ削除）

制限事項：

• Cronジョブは現在のClaude Codeセッションが有効な間のみ機能し、端末を閉じると無効になります。
• 定期ジョブは7日後に自動的に期限切れになります。
• REPLがアイドル状態のときにのみトリガーされ、進行中の会話を中断しません。

3ロールプロトコル

コア原則：成果物の検証

各ロールは自身の成果物を検証しなければなりません。「やり終えた」だけで引き渡してはいけません。

• Inspector：タスクを作成したら、タスクの説明が十分に明確か、ヒントが実行可能か確認します。
• Worker：コードを修正したら、プロジェクトのドキュメント（AGENTS.md / CLAUDE.md / TODO.md / README など）で定義された検証コマンドを実行します。プロジェクトがエンドツーエンドまたは実際のフロー検証を定義している場合、それを実行し結果を記録しなければなりません。
• Reviewer：レビュー時に、Workerが今回の変更に関連する検証コマンドを実行したことを確認します。プロジェクトがE2Eまたは実際のフロー検証を定義しており、変更がそのパスに影響を与える場合、Workerが検証していなければ拒否するか、追加で検証を行います。

エンドツーエンド（E2E）検証はオプションではありません。プロジェクトに特定のE2E/実際のフロー検証がない場合、または外部依存関係が利用不可で実行できない場合は、その理由を明示的に記録しなければなりません。

Inspector (プランナー)          — 方向性を決定し、タスクを発見する
  ↓ TODO.mdへ書き込み
TODO.md (共有ボード)
  ↓
Worker (修正者)                — タスクを受け取り、コードを修正する
  [待機中] → [進行中] → [レビュー待ち]
  ↓
Reviewer (レビュアー)          — コードをレビューし、プロジェクトルールに従ってコミットするか却下するかを決定する
  承認 → Done Log + （許可されている場合のみ）git commit
  却下 → [却下済み] + 修正の指示
  ↓
Worker が [却下済み] を再取得...

タスクステートマシン

ラベル	意味	変更可能なロール
[待機中]	未取得	Inspectorが新規追加/変更可、Workerが取得可
[進行中]	Workerが作業中	Workerが取得時に設定、他者は変更不可
[レビュー待ち]	Workerが完了	Workerが完了時に設定、Reviewerがレビュー
[却下済み]	Reviewerが却下	Reviewerが却下時に設定、Workerが再取得可

実行手順

Step 1 — ユーザー指示の解析

ユーザー入力から以下を抽出します。

1. cronモードかどうか: 入力に cron キーワードが含まれているか
2. モード: cron / inspect / work / loop / full（デフォルト）
3. 追加コンテキスト: コマンド後の自然言語テキスト（あれば）

cronモードの場合は Step 5 にジャンプします。そうでなければ Step 2 に進みます。

追加コンテキストを一時ファイルに保存します。

echo "ユーザー追加指示: <ユーザーが入力した自然言語>" > /tmp/harness-context.txt
#   ライフサイクル：フルモードの次のサイクル = inspector + worker-reviewer の両方が読み取ります；
#   worker-reviewer が実際に claude に引き渡した後の後片付け時に削除されます（実行可能なタスクがなく早期終了した場合は保持）

追加コンテキストがない場合、空のファイルを作成します（子プロセスは空ファイルを検出すると注入しません）。

Step 2 — プロジェクト環境の確認

# プロジェクトルートにいることを確認
test -f TODO.md || echo "NOT_HARNESS_PROJECT"
# skillスクリプトが存在することを確認（skillディレクトリからの相対パス）
test -f ../harness/inspector.sh && test -f ../harness/worker-reviewer.sh || echo "SCRIPTS_MISSING"

環境が正しくない場合、停止してユーザーに通知します。

実行例：

cd <project> && bash ~/.codex/skills/harness/inspector.sh
cd <project> && bash ~/.codex/skills/harness/worker-reviewer.sh --loop
HARNESS_PROJECT_DIR=/abs/path/to/project bash ~/.codex/skills/harness/inspector.sh

TODO.md が存在しない場合、最小限のテンプレートを作成します。

# Project Improvement Board

## Current Phase: 初期化

## Goals
- [ ] Inspectorによる初回巡回後に記入

## Done Log

Step 3 — モードに応じた実行

モード: inspect

cd <プロジェクトディレクトリ> && bash <skillディレクトリ>/inspector.sh

モード: work

cd <プロジェクトディレクトリ> && bash <skillディレクトリ>/worker-reviewer.sh

モード: loop

cd <プロジェクトディレクトリ> && bash <skillディレクトリ>/worker-reviewer.sh --loop

モード: full（デフォルト）

# Phase 1: Inspector 巡回
cd <プロジェクトディレクトリ> && bash <skillディレクトリ>/inspector.sh

# Phase 2: Worker+Reviewer ループ
cd <プロジェクトディレクトリ> && bash <skillディレクトリ>/worker-reviewer.sh --loop

Step 4 — 結果の出力

完了後、ユーザーに報告します。

Harness サイクル完了

Inspector:
  - 現在の目標: ...
  - アーキテクチャ判断: ...
  - 新規/調整タスク: N 個

Worker+Reviewer:
  - 完了タスク: N 個
  - 却下タスク: N 個
  - 残り待機中: N 個

次のサイクル: /harness を入力して継続

Step 5 — cronモード（CronCreate/CronDelete/CronListツールの使用）

5.1 定期タスクの作成: /harness cron "<cron式>" [mode]

1. cron式とオプションのmode（inspect / work / loop / full）を解析します。
2. modeに応じてプロンプト内容を構築します。
   • full: "Harnessフルサイクルを実行します。順に実行： 1. cd <プロジェクトパス> && bash <skillパス>/inspector.sh 2. bash <skillパス>/worker-reviewer.sh --loop 完了後に結果を報告してください。"
   • inspect: "Harness inspectを実行します。cd <プロジェクトパス> && bash <skillパス>/inspector.shを実行してください。完了後に結果を報告してください。"
   • work: "Harness workを実行します。cd <プロジェクトパス> && bash <skillパス>/worker-reviewer.shを実行してください。完了後に結果を報告してください。"
   • loop: "Harness loopを実行します。cd <プロジェクトパス> && bash <skillパス>/worker-reviewer.sh --loopを実行してください。完了後に結果を報告してください。"
3. CronCreateを呼び出します。パラメータ：
   • cron: ユーザーが指定したcron式
   • prompt: 上記で構築したプロンプト
   • recurring: true
4. 作成成功をユーザーに確認し、job_idを返します。

5.2 定期タスクの確認: /harness cron list

1. CronListを呼び出し、現在のセッションの全cronジョブを取得します。
2. プロンプトに "harness" キーワードが含まれるジョブをフィルタリングします。
3. 表形式で表示します：job_id | cron式 | mode | 作成時間（あれば）
4. harness cronがない場合、「現在のセッションにharness定期タスクはありません」と通知します。

5.3 定期タスクの削除: /harness cron stop [job_id]

• job_idがある場合: CronDeleteを呼び出して指定ジョブを削除し、削除成功を確認します。
• job_idがない場合:
  1. CronListを呼び出し、harness関連ジョブをフィルタリングします。
  2. 削除予定のすべてのジョブをユーザーに表示します。
  3. ユーザーの確認後、1つずつCronDeleteを呼び出して削除します。
  4. 削除結果を報告します。

子プロセス入力メカニズム

各子プロセス（Inspector / Worker / Reviewer）は claude -p で起動され、入力は以下の3つの部分で構成されます。

1. ロールプロンプト — <skillディレクトリ>/prompts/inspector.md など
2. プロジェクトドキュメント — スクリプトが自動的に AGENTS.md、CLAUDE.md、README、TODO.md などのファイル内容を連結します。
3. ユーザー追加コンテキスト — /tmp/harness-context.txt から読み取り、プロンプトの末尾に注入します。

3つの部分を連結して claude -p に渡すことで、子プロセスがプロジェクト全体の状況とユーザーの今回の具体的な意図の両方を把握できるようにします。

デフォルトでは、スクリプトは呼び出し時のカレントワーキングディレクトリ（pwd -P）をプロジェクトディレクトリとみなします。別の場所から呼び出す場合は、HARNESS_PROJECT_DIR=/abs/path/to/project で明示的に上書きできます。skillのインストールディレクトリはスクリプトとプロンプトの配置場所としてのみ使用され、プロジェクトディレクトリとしては扱われません。

ファイル一覧

ファイル	責務
prompts/inspector.md	Inspectorロールプロンプト
prompts/worker.md	Workerロールプロンプト
prompts/reviewer.md	Reviewerロールプロンプト
inspector.sh	Inspector実行スクリプト
worker-reviewer.sh	Worker+Reviewer実行スクリプト
TODO.md	共有タスクボード（プロジェクトルート）