Harness Plan

Harness Plan

Harness の統合プランニングスキル。 以下の3つの旧スキルを統合:

• planning (plan-with-agent) — アイデア → Plans.md への落とし込み
• plans-management — タスク状態管理・マーカー更新
• sync-status — Plans.md と実装の同期確認

Quick Reference

スコープ既定: 今進められる全作業（operator 裁定 2026-07-24）

計画依頼（create / 引数なし起動 / 「計画して」）の既定解釈は 「現時点で着手可能なすべての作業」。

• ユーザーが範囲を明示しない限り、依頼文脈に入る open item（残 phase、未処理 follow-up、既知の改善点、依頼文で言及された問題すべて）を洗い出して計画に含める。勝手に最小サブセットへ絞らない
• 件数が多い場合も絞り込みではなく、全量を Required / Recommended / Optional / Reject に分類して提示する。除外は Reject として理由を明示する（黙って落とさない）
• 「一部だけ先に」が妥当と判断する場合は、絞った計画ではなく、全量計画の中の実行順序（Phase 分割 / Depends）として表現する

この既定は計画候補の洗い出し範囲であり、実装や保護操作の承認ではない。評価・比較だけの依頼は評価を返し、採用済みの変更と提案を区別する。 task には目的と理由、担当範囲、検証可能な DoD、利用する証拠、原依頼や適用される承認の参照を残す。実装手順は契約上必要な制約以外を固定しない。

Literal companion commands（CC 2.1.108+）

• /recap: 久しぶりに戻った時に要約を取り直してから sync へ入る
• /undo: /rewind の別名。直前の plan 更新を即座に戻したい時にそのまま使う

サブコマンド詳細

標準の計画品質契約

See references/planning-quality.md

harness-plan は、spec.md product contract and Plans.md task contract の co-required planning output を作る planning surface である。 precedence は spec.md > sub-spec > Plans.md のまま維持する。 Plans.md は task ledger、root spec.md は product contract であり、上下関係は崩さない。 渡された情報をそのまま Plans.md に落とさない。 計画作成や大きな task 追加では、最新情報・既存仕様・記憶・TeamAgent / サブエージェントによる複数視点の議論を確認し、 このプロダクトに取り入れるべき要素だけを task contract に変換する。 /harness-plan create は Spec delta または Spec skip reason と Plans.md task 生成をセットで返す。 出力には必ず Spec delta または Spec skip reason を含める。 Spec delta / Spec skip reason は Harness が生成し、consumer は承認・修正だけ行う。

Non-trivial planning gate:

単発・軽微タスクでない planning は、TeamAgent またはサブエージェント前提で扱う。 ここでの non-trivial は、複数 task / 複数 file / 複数 session / product behavior / API / data model / 権限 / 課金 / 外部連携 / 配布面 / セキュリティに影響する依頼を指す。 Task tool が使える場合は Product / Architecture / Security / QA / Skeptic の独立視点を走らせる。 使えない場合は サブエージェント未使用 と明示し、同じ観点を単独で分けて評価する。 各担当には独立して答えられる問い、読む範囲、必要な根拠を渡す。利用可能な同時実行上限を守り、親も仕様照合や統合を進める。関連する追加調査は同じ担当に返す。

non-trivial planning の出力には、次の検証を必ず含める。

• team_validation_mode: not_required_lightweight / native / subagent / manual-pass / unavailable
• spec.md / sub-spec / Plans.md の整合性
• harness-mem / harness-recall / repo memory による車輪の再発明防止確認
• プロダクト目的から外れていないか
• セキュリティ、権限、秘密情報、サプライチェーンに問題がないか
• lint / formatter baseline があるか。source code changes を含む plan で未設定なら、実装 task の前に setup task を置く
• ちゃんと動く計画か。つまり test / smoke / CI / review / release gate が task DoD に落ちているか

軽量 task は team_validation_mode: not_required_lightweight でよい。 non-trivial planning は native / subagent / manual-pass のいずれかを使う。 unavailable のまま Required にしてはいけない。 Product / Architecture / Security / QA / Skeptic は検証 perspective であり、agent_type 名ではない。 利用可能な TeamAgent / Task サブエージェントに perspective として依頼し、任意 agent spawn を要求しない。 Security gate は秘密情報の実読取を要求しない。 .env や secret の read が必要になる場合は Risk Gate として止め、許可された既存 guard / evidence で確認する。

適用する場面:

• create で新しい計画を作る
• add で product behavior / API / 権限 / 課金 / 外部連携 / 配布面に影響する task を足す
• ユーザーが外部プロダクト、競合、仕様案、改善案、比較材料を渡した
• 既存仕様や過去判断との衝突リスクがある

軽く扱ってよい場面:

• marker 更新だけの update
• status 照合だけの sync
• typo、format、README/CHANGELOG のみ
• 既存 spec とテストで正解が固定されている狭い変更

品質フロー:

1. 入力情報を分解し、評価対象・採点軸・不確かな事実を明示する
2. 最新情報を取得する。外部事実は WebSearch / 公式ドキュメント / 一次情報を優先し、重要点は複数ソースでクロスチェックする
3. 既存仕様・root spec.md・Plans.md・README・docs・CLAUDE.md・関連 skill を確認する
4. harness-mem / harness-recall / .claude/agent-memory/ / .claude/state/ など、利用可能な記憶面を project-scoped で確認する
5. non-trivial planning では TeamAgent / Task サブエージェントを使い、Product / Architecture / Security / QA / Skeptic など異なる視点で独立レビューする
6. source code changes を含む plan では lint / formatter baseline を確認し、未設定なら setup task を先行させる
7. 中立的な採点レビューを出し、Required / Recommended / Optional / Reject に分類する
8. $easy 形式で、提案内容・理由・どうなるのかを報告する
9. 採用する案だけを root spec.md / Plans.md / test task へ落とし込む

Lane Taxonomy + Stage Gate

Fast / Gate / Release は 新 skill ではなく Plans metadata として扱う。Plans.md の 5 column テンプレート（Task / 内容 / DoD / Depends / Status）は変更せず、 lane（[lane:fast] / [lane:gate] / [lane:release]）・stage（検証→計画→TDD実装→レビュー→PR closeout の 5 段階）・unknown data contract（not_observed != absent、確認できない事実は unknown と明示）を 内容（Content）または DoD の先頭に埋め込む。タグ一覧・worked example・stage 別 DoD 例は references/create.md を参照。

create — 計画作成

See references/create.md

アイデア・要件をヒアリングし、実行可能な Plans.md を生成する。

フロー:

1. 会話コンテキスト確認（直前の議論から抽出 or 新規ヒアリング）
2. 既存の依頼・仕様・読み取り調査で不足を補い、結論を変える未決事項だけ聞く（max 3問）。軽微な仮定は明示して計画を進める
3. 計画品質チェック（最新情報、既存仕様、記憶、TeamAgent / サブエージェント複数視点レビュー、採点）
4. 技術調査（WebSearch）
5. 機能リスト抽出
6. spec.md / Plans.md 二正本チェック（Spec delta または Spec skip reason + Plans.md task）
7. 優先度マトリクス（Required / Recommended / Optional / Reject）
8. TDD 採用判断（テスト設計）
9. Plans.md 生成（cc:TODO マーカー付き）
10. 事前確認セクション生成（plan-time pre-approval）
11. 次のアクション案内

create — 事前確認セクション（plan-time pre-approval）

create で計画を確定する時は、Plans.md task を出したあと、承認前に 事前確認セクションを必ず生成する。 目的は、常設 allowlist で何でも許可するのではなく、作業スコープごとに「発生しそうな stop / ask」を plan 承認時に 1 回だけ前倒しで確認すること。

抽出対象:

• 各 task の対象ファイル、関連 path、想定変更範囲
• DoD に書いた検証コマンド、PR closeout コマンド、外部 API / CLI 呼び出し
• secret-read path（.env*, secrets/**, *.pem, *.key, .ssh/**, .aws/**, credentials など）
• 外部送信（git push, gh pr create, gh api, curl / API call, release / publish / deploy）
• 破壊的操作（rm -rf, migration destructive step, force push, production apply）

固定 format:

## 事前確認
- 事項: <secret-read / external-send / destructive の具体操作>
  理由: <DoD または task 実行上必要な理由を 1 行>
  scope: Phase <phase> / Task <task>

出力ルール:

• 1 行の 理由 は secret 値を含めない。path / コマンド名 / 対象サービスまでに留める。
• plan 承認時に、事前確認セクションの全事項を一括提示し、ユーザーから承認 / 否認を得る。
• 承認結果は .claude/state/plan-preapprovals.json に plan-preapproval.v2 として記録する。schema は templates/schemas/plan-preapproval.v2.json。v1 は既存記録の読み取り互換に限る。
• 記録は 事項 + 理由 1 行 + scope (phase/task) を維持する。operations には secret-read / external-send / destructive を列挙する。paths / commands / targets には対象を列挙する。decision、approved_at、RFC3339 の expires_at を入れる。
• max_uses は必要な再試行回数を含む上限を設定する。省略時は 10 回。uses は新規承認時に 0 とする。
• 確認は plan 承認時の 1 回のみ。harness-work / breezing 実行中、宣言済み事項だけを理由に AskUserQuestion を出してはいけない。
• 記録に無い未計画の secret-read / 外部送信 / 破壊的操作は、従来どおり runtime floor / ask で停止する。安全網を狭めない。
• secret-read の承認は secret 値の表示許可ではない。必要最小の path を宣言し、work 開始時に project config の runtimefloor.secretAllow へ per-run 反映するための入力として扱う。

spec.md / Plans.md 二正本チェック（デフォルト）

Plans.md は「やるべきこと」の task contract、root spec.md は「何が正しいか」の product contract として扱う。 co-required planning output は両方の出力を必須にするという意味であり、precedence は spec.md > sub-spec > Plans.md のまま維持する。 実装がぶれる可能性がある時は、Plans.md 生成前に root spec.md を更新する。 create と product-impacting add は毎回 root spec.md を読む。

優先する保存先:

1. root spec.md
2. consumer repo に root spec.md がない時だけ、既存の project spec / architecture / product compass
3. consumer repo に root spec.md がない時だけ、docs/spec/00-project-spec.md
4. 既存規約がある repo では、その規約に沿った spec path

作成/更新が必要な条件:

• ユーザーに見える振る舞い、API、データモデル、権限、課金、外部連携を決める task
• 複数の実装方針があり、選び方で product behavior が変わる task
• 過去または今回の会話で「仕様が曖昧で実装がぶれた」兆候がある task
• Plans.md には作業内容があるが、project としての正解条件が安定文書にない task

不要な条件:

• typo、format、dependency bump、README/CHANGELOG のみ
• 動作変更なしの狭い refactor
• 既存 spec とテストで正解が十分に固定されている修正

出力契約:

• Spec delta: product contract を更新する時に、対象 spec path と変更点を書く
• Spec skip reason: product contract を更新しない時に、理由を書く
• Spec delta / Spec skip reason は Harness が生成し、consumer は承認・修正だけ行う
• docs-only / mechanical task でも Spec skip reason を task context / sprint contract に残す
• missing search result、unavailable memory、未読ファイルを absent と断定しない。not_observed != absent
• ユーザーに spec を一から書かせない。agent が既存 spec と入力から最小 delta を作り、曖昧な時だけ判断分岐を出す

参照:

• docs/plans/spec-ssot.md