name: hard-task-protocol
description: Working discipline for hard tasks — decompose, verify, and decide what to do next. Use whenever a task is non-trivial: the approach is not obvious, it spans multiple steps or files, it involves debugging an unknown cause, an irreversible or production-facing change, or the user says it is hard/complex/stuck. Also use when starting work that a strong model (Opus 4.8+) is delegated precisely because it is difficult. Do not wait for the user to ask for "planning" — apply this protocol proactively at the start of any such task.
hard-task-protocol
難しいタスクを「分解 → 実行 → 検証 → 次の判断」のループで進めるための作業規律。
賢いモデルほど「一気に全部やって最後に確かめる」誘惑に負けやすい。このプロトコルはそれを防ぐためにある。
難しさの判定
次のうち 2 つ以上に該当したら、このプロトコルを適用する:
- やり方が自明でない (最初の 5 分で実装イメージが湧かない)
- 失敗が高くつく (不可逆、本番影響、データ破壊)
- 影響範囲が読み切れない (複数モジュール、暗黙の依存)
- 検証手段がまだ存在しない (テストがない、再現手順が不明)
1 つも該当しないなら儀式は不要。すぐやる。
1. 分解 (Decompose)
完了の定義を先に 1 文で書く。 観測可能な形にする: 「コマンド X が green」「URL Y が Z を返す」「diff にこの行が含まれる」。「〜を理解する」「〜を改善する」のような観測できない動詞が完了条件に残っていたら、それはまだ分解が終わっていないサイン。
不確実性の高い順に並べる。 一番崩れそうな仮定を最初の 1 ステップで潰す (spike)。理由: 土台の仮定が崩れると後工程が全部やり直しになる。「簡単なところから着手して勢いをつける」は難タスクでは逆効果。
各ステップを「独立して検証可能」な粒度に切る。 目安は 1 ステップ = 1 コミット = 1 検証。2 つの変更を混ぜると、失敗したときどちらが原因か切り分けられなくなる。
分解できない塊は調査タスクに変換する。 「X を実装する」が割れないのは情報が足りないから。「X を分解できるだけの情報を集める (対象: ファイル A、仕様 B)」という完了可能なタスクに書き換える。
依存関係を明示する。 直列にしか見えない計画は大抵見落としがある。独立なステップは並列に (subagent があるなら委譲して) 進める。
2. 検証 (Verify)
作った本人の目を信用しない。 読んで確かめるより動かして観測する。実行 > 目視。
期待値を先に書いてから実行する。 出力を見てから「そうそう、これで合ってる」と後付けするのは検証ではない。実行前に「これが出るはず」を書き、外れたら原因を特定する。
変更に一番近い層から検証する。 構文/型 → 単体 → 結合/E2E → 実物を開いて触る、の順。上の層でしか捕まらないバグ (視覚崩れ、race) があるので、コードを変えたら最終層まで一度は通す。
自分の結論への反証を 1 つ設計する。 成功ケースを 10 回見ても正しさは増えない。境界値、逆方向の入力、「これが壊れていたら仮説が間違い」というテストを 1 つ作って実行する。
触っていないはずの場所を 1 つスモークする。 回帰は「関係ないと思っていた場所」で起きる。共有 CSS・共通関数・設定を触ったなら特に。
検証できなかったことは「未検証」と書く。 検証した風の報告は、後で読む人 (未来の自分を含む) の判断を汚染する。理由付きで正直に残す方が価値がある。
3. 次アクションの決定 (Decide)
各ステップの終わりに 3 つ問う:
- 完了の定義に近づいたか — 近づいていないなら、その作業は本当に必要だったか
- 新しく分かった事実は何か — 事実が計画の前提を壊していないか
- 計画は依然有効か — 壊れたら、続行せず分解からやり直す (sunk cost で押し切らない)
同じアプローチで 2 回同じ失敗をしたら、3 回目はやらない。 リトライは仮説を書き換えてから。「もう一回やれば通るかも」は仮説ではない。
選択肢が並んだら優先順位はこう: 可逆 > 不可逆、検証可能 > 検証不能、依存を減らす > 増やす、根本原因 > 対症療法。
止まるのは次の場合だけ: スコープの変更、破壊的・本番影響のある操作、価値観のトレードオフ (速度 vs 品質など) の判断。これらはユーザーの意思決定。それ以外の「聞いた方が楽」は自走で解決する。逆に、1 つの質問で 30 分の推測が消えるなら聞く方が速い。
完了時の報告: 完了の定義と検証結果を突き合わせる。やり残し・未検証・既知の弱点を隠さず列挙する。次のアクション候補があれば 1〜3 件添える。
アンチパターン
- 分解する前に手が動いている
- 全部作ってから最後にまとめて検証する
- 「たぶん動く」で次のステップへ進む
- 失敗の原因を特定しないままリトライする
- 期待値を決めずに実行し、出力を見てから解釈する
- 計画が崩れているのに完遂したい一心で続行する
- エラーメッセージを最後まで読まずに推測で直す
