claude-harness

claude-harness

Claude Code のハーネスエンジニアリングをフレームワーク化したプラグイン。 宣言的な設定ファイル .claude/harness.yaml 1枚で、プロジェクトごとに異なる CI・チケット管理・レビュー体制を吸収しながら、共通のワークフローエンジンを配布する。

解決する問題

複数プロジェクトでハーネス（CLAUDE.md / skills / hooks / settings）をコピペ運用すると、 プロジェクト間で世代ドリフトが起きる。改良が他プロジェクトに還流せず、 どのプロジェクトが第何世代かも分からなくなる。

このリポジトリはハーネスのエンジン部分を1箇所に集約し、プラグインとして バージョン付きで配布する。プロジェクト側に残るのは設定（harness.yaml）と ドメイン知識（CLAUDE.md / rules / 固有スキル）だけ。

5層モデル

層	内容	置き場所
Context	CLAUDE.md・docs・rules（ドメイン知識）	各プロジェクト
Knowledge	スキル（判断基準・手順書）	プラグイン（汎用）+ プロジェクト（固有）
Enforcement	フックによる構造的強制（ゲート・ガード）	プラグイン（本リポジトリ）
Automation	サブエージェント（ペルソナレビュー等）	プラグイン（汎用）+ プロジェクト（固有）
Audit	config-audit・ビジュアライザ	プラグイン

中核コンセプト

• 複数ワークフロー: implement / investigate / pr-review を名前つきで宣言し、 セッションごとに /flow <name> で有効化。フローごとに編集権限とゲート列が変わる
• ゲートシーケンサー: Stop フック1本が harness.yaml のゲート列を順に要求。 通過記録はセッション単位のノンス（ワンタイムトークン）でのみ有効 — 改ざん防止と複数セッション並走時の競合防止を同じ仕組みで実現。 同一ゲートが規定回数（デフォルト5回・HARNESS_MAX_GATE_BLOCKS）連続でブロックされ 進捗がない場合はサーキットブレーカーが解放し、無限ループを構造的に防ぐ
• 検証可能なアウトプットの強制（gates[].verify）: トークンによる完了申告は デフォルトでは自己申告（「やった」と言えば通る）に過ぎない。verify: に シェルコマンドを書くと、エンジンがそれを実行して exit 0 を確認できて初めて 通過を受理する（非0なら同じトークンで再ブロック。サーキットブレーカーの 連続ブロック回数カウンタも継続し、無限リトライを許さない）
• ペルソナレビュー / 任意ゲートの独立コンテキスト実行: レビュー観点 （QA / PO / アーキテクト / セキュリティ）を独立コンテキストのサブエージェントとして 並列起動する review-board（personas:）に加え、任意のゲートを1エージェントで 独立実行できる gates[].agent（personas: マップの単一参照）も v0.5.0 で追加。 refactor・tdd 等も yaml 1行で「実装者の会話から隔離して実行」に切り替えられる （/gate-run 経由。未設定ならメインコンテキストで直接実行する後方互換動作）。 /gate-run は diff ベース（レビュー系）だけでなくチケットベース（計画系）の ゲートにも使える汎用機構
• Planner（デフォルト有効）: Anthropic の harness 設計記事の Planner/Generator/Evaluator 構成に倣い、implement ワークフローの entry ゲートに plan（独立コンテキストの planner ペルソナ）をデフォルトで 組み込んだ（v0.6.0）。entry ゲートなので計画が通るまで実装ファイルの編集自体が ブロックされる。計画は「スコープ / スコープ外 / 影響ファイル / リスク」の 構成で書かせ、verify-plan.sh が空・プレースホルダのまま記録することだけを防ぐ （内容の妥当性そのものは自然文のため機械検証できない）
• セッション/ゲートスコープのアーティファクト: verify:/output: に書ける {session_id} プレースホルダをエンジンが実セッションIDに置換してから評価する。 固定パスのまま書くと複数セッション同時実行でレビュー結果等が衝突するため、 gate_artifact_path() が .claude-harness/<session_id>/<gate名>/... の形で セッション+ゲート名スコープのパスを一元発行する
• 永続進捗ログ（.claude-harness/progress.log, JSONL・追記専用）: Anthropic の claude-progress.txt 相当。セッション状態（/tmp 配下）は SessionEnd で消えるが、workflow 宣言・ゲート通過/スキップ/検証失敗/ ブレーカー解放は全てこのログに残り、長時間・複数セッションにわたるループの 進捗を /harness-map の「最近の進捗」セクションで追跡できる
• アダプタ: チケット置き場（GitHub Issues / Projects / なし）と CI コマンド・カバレッジ閾値を設定で吸収
• Just-in-time 注入: スキーマの読者は Claude ではなくエンジン。 Claude へはフック出力経由で「次の一手」だけが注入される

設計ドキュメント

1. docs/schema-v0.md — harness.yaml スキーマ草案（注釈つきフル例・検証表・未決事項）
2. docs/runtime-v0.md — ランタイム設計（データフロー・ウォークスルー・導入フロー・v0 実装スコープ）

リポジトリ構成（プラグインレイアウト）

claude-harness/
├── .claude-plugin/
│   ├── plugin.json          # プラグインマニフェスト
│   └── marketplace.json     # このリポジトリ自身をマーケットプレイスにする
├── hooks/                   # エンジン: ディスパッチャフック（5本）
├── scripts/                 # mark-gate-passed 等の補助スクリプト
├── skills/                  # /flow, /review-board, /gate-run, /harness-map, /harness-init, /config-audit, /report
├── agents/                  # 汎用ペルソナ（planner / qa / po / architect / security）
├── schemas/                 # harness.schema.json（エディタ補完・検証用）
└── docs/                    # 設計ドキュメント

導入（予定）

# マーケットプレイス追加 → プラグインインストール
/plugin marketplace add m-kuwata/claude-harness
/plugin install claude-harness@m-kuwata

# プロジェクト初期化（対話ウィザードが harness.yaml を生成）
/harness-init

ステータス

エンジン + 全スキル実装済み（v0.9.0）。E2E スモークテスト 108 件通過（bash tests/run.sh）。pokotto-box / classly / ehon-note でパイロット導入済み。classly では claude plugin marketplace add / claude plugin install（実インストール、user scope）で通しの動作検証済み（詳細は下記 v0.9.0）。