実装判断の規律

このスキルが防ぐ失敗は 4 つある。

1. 要求が答えていない設計判断を推測で埋め、誤った解釈のまま実装へ進む
2. API・型・境界・責務を、合意なく不用意に変える
3. 実装が計画からずれたことに気づかず、動くだけの実装で終わる
4. 完了を印象で判断し、検証可能な基準に照らさない

重い工程はこの 4 つを防ぐための手段であって、コードに触れること自体の税ではない。防ぐ失敗がないタスクに工程だけを課さないよう、最初に階層を判定し、階層に応じた重さで進める。

本文中の references/ は、このスキルと同じディレクトリの直下にある。references を読むことは該当フェーズの入る条件の一部であり、読まないままそのフェーズの subagent を起動しない。スキル本文が会話に注入されていても references は注入されていないので、本文を読んだことを references を読んだことと混同しない。会話が要約(compaction)された後は、本文も references も文脈から失われている前提で、次のフェーズに入る前に読み直す。

階層の判定

タスクを受け取ったら、設計も実装もする前に、次の 3 つの問いに答える。ここでは合意メモを作らず、subagent も起動しない。答えに必要な範囲で要求と該当コードを読むだけでよい。GitHub issue を起点とするタスクでは、先に issue-agreement スキルで合意メモを作り、それを入力にして判定する。

1. 未確定の判断があるか: 実装が答えを必要とするのに、要求テキストにも既存コードの前例にも答えがない決定を挙げる。特に外形(API の形、設定の与え方、データモデル、外部へ送る内容と送信先、公開範囲、画面や操作の見え方)に触れるものを見る。
2. 誤りは検出されるか: この変更を間違えたとき、テスト・型検査・ビルド・静的検査・検証コマンドの結果に現れるか。それとも、動いてしまって黙って通るか。
3. 高影響領域に触れるか: 認可・認証、公開範囲、データの消失や不可逆な移行、外部への送信、秘密情報、課金のどれかに触れるか。

判定は差分の大きさでは行わない。大量の機械的 rename は直接実装でよく、数行の認可条件の変更は高影響領域として扱う。「小さいから安全」「大きいから危険」のどちらも根拠にならない。

直接実装

次のどちらかに当てはまるなら、このスキルの対象外とする。Phase 0 にも計画にも入らず、通常の作業として実装し、プロジェクトの検証コマンド（CI 定義や AGENTS.md にあるもの）を実行して報告する。subagent の起動も独立レビューも要らない。

• 成果物の種類で対象外: CI/CD 定義だけ、ドキュメントだけ、設定値や依存バージョンだけの変更
• アプリケーションコードに触れるが、次をすべて満たす変更
  • 原因または変更箇所が特定済みで、期待する結果が明確
  • 3 つの問いがすべて「いいえ」: 未確定の判断がなく、誤りが検証コマンドで検出され、高影響領域に触れない
  • 新しい概念・型・API・責務・層境界を導入しない
  • 既存の実装パターンをそのまま適用できる
  • 変更範囲が局所的だと事前に分かり、何を実行すれば正しさを確認できるか分かっている

このスキルが明示的に呼ばれた場合も、この条件を満たすなら「直接実装として進める」と一言述べて通常の作業へ戻ってよい。

直接実装の途中で条件が崩れたら(未確定の判断が現れた、既存パターンが当てはまらない、変更範囲が予定より広がった、高影響領域に触れた)、そこで止まり、階層を判定し直す。外形に触れる決定が現れた場合は、Phase 0 と同じ形でユーザーに確認してから進める。

軽量

直接実装の条件を満たさないが、次をすべて満たす変更。

• 未確定の判断があっても、内部実装の選び方に限られ、外形に触れない
• 新しい型・概念・責務・層境界を導入しない。既存 API の内部実装の置き換えはここに含まれる
• 変更範囲を事前に局所化できる
• 高影響領域に触れるとしても、要求がその決定(誰に許可するか、何を公開するか、何を消すか)を明記しており、未確定の判断が残らない

進め方は「軽量の進め方」に従う。メインが実装と検証を行い、独立レビューは条件付きで依頼する。

標準

次のどれかに当てはまる変更。

• 外形に触れる未確定の判断が残る
• API や設定方法を決める、データモデルを変える、新しい型・概念を導入する、責務や層境界を変える
• 複数の実現方法があり、設計判断が要る
• 変更範囲を事前に局所化できない
• 高影響領域に触れ、かつ未確定の判断が残る、または誤りが検証コマンドで検出されない

進め方は「標準の進め方」の Phase 0〜6 に従う。

判定例

• typo や明らかな 1 行のバグ修正: 直接実装
• 原因が特定済みで、既存パターンに沿った数ファイルの修正: 直接実装。修正方法に内部の選択が残るなら軽量
• 既存 API の内部実装だけを置き換え、外形は変わらない: 軽量。テストが置き換え対象の経路を通らないなら、独立レビューを付ける
• 新しい API endpoint を追加するが、要求に request/response/権限まで明記されている: 残る判断で決める。既存 endpoint のパターンに沿い、層配置も決まっているなら軽量。層配置や新しい型が要るなら標準。自動的に標準にしない
• 「通知機能を追加して」のように、保存方法・送信先・失敗時挙動が未確定: 標準。Phase 0 でユーザーに確認する
• domain model に新しい型や責務を導入する: 標準
• 大量の機械的 rename: 直接実装
• 数行の変更だが認可・公開範囲・データ消失に関わる: 要求が決定を明記していれば軽量(独立レビュー必須)。明記していなければ標準として Phase 0 で確認する

軽量の進め方

メインセッションが自分で実装する。subagent は、条件を満たしたときの完了前レビューだけに使う。

1. 解釈の確認: 階層の判定で挙げた未確定の判断それぞれに、出典(要求テキストの引用、既存コードの前例のパス、ユーザーの回答)を付ける。出典を付けられないものは仮定として記録する。仮定が外形に触れると分かった時点で、標準へ上げて Phase 0 の確認を行う。
2. 簡易計画: 受け入れ基準(観察できる条件のリスト)、変更してよい範囲、検証コマンド一覧、記録した仮定の 4 項目を、ユーザーから見える場所(plan 管理 tool か本文の短いメモ)に書く。
3. 実装と検証: メインが実装し、検証コマンドを自分で実行する。抽象化と削除の判断は references/delegation.md の基準に従う。
4. 検収: git diff --stat(相当する手段)で実差分を取り、簡易計画の範囲と受け入れ基準に照らす。記憶ではなく実差分で照合する。
5. 独立レビュー(条件付き): 次のどれかに当てはまる場合だけ、references/review-request.md を読み、その形式で subagent 1 体に文脈の複製なしでレビューを依頼する。当てはまらなければ省き、検収をもって完了する。

• 高影響領域に触れる
• 検証コマンドが変更の中心を通らない。該当経路にテストがなく追加もしない、正しさを目視でしか確認できない、など
• 置き換えや削除を含み、参照の網羅が要る
• 実装中に差分が簡易計画の範囲を超えた

6. 完了: レビューを依頼した場合、MUST FIX を修正して再検収する。反復は 1 巡まで。完了報告は、受け入れ基準の充足状況、最終差分の要約、実行した検証コマンドと結果、残した指摘とその理由の 4 項目で書く。

独立レビューを省く基準は「コードに触れたか」ではなく、見落としが後段で検出されるかである。検証コマンドが差分の中心を実際に通り、誤りがそこに現れるなら、レビューを付けても得られる情報は少ない。

subagent の使いどころ(全階層共通)

subagent を使うかどうかは、references/subagent-grades.md のグレード選択と同じ基準で決める。出力を後段の仕組みが実物と照合できる仕事は、省いてもメインが行ってもよい。見落としが黙って通る判断は、独立した視点を残す。

• 残す: 設計の反証(Phase 1 の再検討)と完了前レビュー(標準では常に、軽量では条件付き)。検討した本人や実装した本人は自分の結論を楽観的に見るので、別の subagent に任せることに意味がある。
• 文脈で決める: 調査と実装の分担。作業を独立した範囲として切り出せ、探索や中間出力をメインの文脈から隔離するか、並行して進める意味がある場合に分担する。出力は Phase 4 でメインが実物と照合する。探索が広い、独立した担当範囲を並行して進められる、メインの文脈が既に重い、のどれかが目安になる。変更が数ファイルに閉じ、計画が固定されている場合や、変更箇所が密に結びついていて分割に引き継ぎコストがかかる場合は、メインが実装してよい。
• テスト設計: 実装担当やレビュー担当と兼ねてよい。ただし「テストを追加しない」判断が中心になる場合は、メインの自己判断で済ませず subagent に反証させる。追加しない判断の誤りは後段の照合に現れない。

起動の共通ルール

• 起動 tool に親会話を複製するオプション(Codex の fork_turns など)がある場合、調査・実装担当への複製は最小(可能なら複製なし)にする。再検討担当と完了前レビュー担当への複製は、量にかかわらず禁止する。反証とレビューは実装の経緯を知らないことが独立性を作るからで、複製された会話はメインの推論で子の結論を誘導し、毎ターン再送され続けるコストも払う。渡すべき文脈は依頼文に書き切り、子が親の会話を参照しないと動けないなら、依頼文の不備として依頼文を直す。この規律はセッション後半、文脈が重くなったときほど破られやすい。依頼文を書き切る余力がないと感じたときこそ、複製へ逃げずに依頼文を直す。複製オプションがない環境では、このルールは何もしなくて満たされる。
• 進捗を待つ tool は、その tool で指定できる最大の timeout でまとめて待つ。待機 1 回ごとにメインの全文脈の再送が発生するので、待機の合間に進捗確認や思いつきの追加指示を送らない。subagent への送信は、起動時の依頼文と、報告を検収した後の差し戻しに限る。伝えたいことが途中で増えたら、次の差し戻しへ 1 通にまとめる。完了が自動通知される環境では、このルールは何もしなくて満たされる。
• モデルや reasoning effort を指定できる環境では、references/subagent-grades.md を読んでグレードを選ぶ。モデルは役割で、effort は作業の形で、別々に決める。起動 tool がグレードの指定を複製なしに限る環境(Codex など)では、グレードを指定する起動はすべて複製なしにする。

標準の進め方

成果物が要求とずれる原因は 2 つある。計画が要求からずれる(要求が答えていない決定を推測で埋める)か、実装が計画からずれる(完了の基準を固定せず、検収を印象で行う)かである。Phase 0 の解釈ゲートが前者を塞ぎ、Phase 1 以降のフェーズ制が後者を塞ぐ。Phase 1 以降はすべて計画との照合で動くため、計画自体が誤っていると後段のどのフェーズも誤りを検出できない。だから解釈の確認は、実装より先の安い段階で済ませる。

基本方針:

• メインセッションは要求、計画、最終結果に責任を持つ。解釈、計画の固定、スコープ判断、検収、最終判断を担い、必要なら自分で実装する。調査・実装・テスト設計の分担は「subagent の使いどころ」に従って決め、再検討とレビューは subagent に任せる。
• 実装した者と完了前レビュー担当を分ける。メインが実装した場合も、レビューは別の subagent に依頼する。同じ subagent に自分の実装をレビューさせない。
• 完了判定と完了報告は、その場の印象ではなく Phase 1 で固定した計画との照合で行う。

レビュー担当を分離できないのは、起動用 tool を探し、一覧を確認しても見つからないか起動に失敗して代替もなく、その経緯と続行する理由を実装前にユーザーへ報告した場合に限る。確認せずに「使えない」と判断しない。その場合もフェーズの順序と出る条件は変えない。Phase 5 が自己レビューになる分、Phase 4 の検収を厚くし、完了報告に「レビュー担当を分離できなかった」と明記する。

Phase 0 解釈ゲート

入る条件: 階層が標準と判定された。まだ設計も実装もしていない。メインのモデルが fast/affordable 級(references/subagent-grades.md の格で判断する)で動いている場合は、解釈に入る前に、上位モデルへの切り替えを提案して turn を終える。解釈・階層判定・提案の採否はこの skill で最も見落としが黙って通る判断で、effort を上げてもモデルの能力は補えない。ユーザーが切り替えずに進めると答えた場合は、そのまま進める。

やること: 要求を「出典付きの決定」と「質問」に分解する。要求の言い換えは、どれだけ丁寧でも成果物として認めない。このフェーズの成果物は合意メモ(意図、検証済みの現状、仮定、確定した決定の 4 項目)である。issue-agreement など入口のスキルで合意メモが既に作られている場合、このフェーズは「4 項目が埋まっているか」「外形に触れる保留が残っていないか」の検収だけで通過してよい。

1. 階層の判定で挙げた未確定の判断を起点に、実装が答えを必要とするのに要求テキストが答えていない決定を列挙する。少なくとも次の観点を見る。

• 入力・設定の与え方: 環境変数か、アプリケーション内の設定か、引数か
• 対象の範囲: どの操作・イベント・データが対象で、何が対象外か
• 外部との接点: API の形、送信先、送る内容、公開範囲
• データの置き場所と寿命: どこに保存し、いつ消えるか
• 失敗時の挙動: 無視するか、リトライするか、エラーを返すか

2. 各決定に出典を付ける。出典として認めるのは次の 3 種類だけ。もっともらしい推測は出典にならない。

• 要求テキストからの引用
• 既存コードの前例(パス付き)
• ユーザーの回答 出典を付けられない決定は、すべて保留として扱う。

3. 類例を調査する。同種の機能や設定がすでにリポジトリにあるなら、その実現方法(設定の持ち方、置かれている層、使われているパターン)を出典として使い、原則それに従う。逸脱するなら、逸脱する理由に別の出典が要る。この調査は subagent に任せてよい。
4. 警戒の目安: 要求が数行以下なのに新しい機能を求めている場合、保留が多いはずだと考えて臨む。列挙した決定がすべて出典付きになったなら、出典を都合よく解釈していないか見直す。

確認の判断: 保留のうち、次のどれかに触れるものが 1 つでもあれば、実装に入らず、ユーザーに確認して turn を終える。

• API の形、設定の与え方、データモデル、外部へ送る内容と送信先、画面や操作の見え方

確認は短い設計メモで行う。長い報告は要らない。

• 採用しようとしている解釈(出典付き)
• 外形の案
• 質問の一覧。各質問に推奨案と代替案を 1 行ずつ付ける

質問は、答えがないと進められないものだけに絞る。内部実装の選び方はここで聞かず、Phase 1 の計画で決めて記録する。

ここで止まるコストは数分で、誤った解釈のまま完成させるコストより常に安い。確認を進行の妨げとして避けない。

出る条件: 合意メモが揃い、外形に触れる保留がなくなった。ユーザーが回答したか、保留が外形に触れないか、ユーザーが推測で進めてよいと明示した場合に満たされる。回答以外の理由で進む場合は、保留と採用した仮定を Phase 1 の計画に記録する。解釈が確定した結果、標準の条件を満たさなくなったなら、軽量へ下げてよい。その場合は「軽量の進め方」の簡易計画から続ける。

Phase 1 計画の固定

入る条件: 解釈ゲートを出た。Phase 0 の調査を除き、まだ subagent を起動していない。

やること: 設計判断を確定してから、作業計画を確定する。

設計判断(新しい概念の導入、型・境界・責務の変更)を含むタスクでは、再検討 subagent を起動して設計と解釈の反証を探させる。起動する前に references/redesign-check.md を読み、その形式で依頼する。

再検討 subagent の指摘や代替案に、Phase 0 で合意していない新しい概念・型・層配置・API が含まれる場合、それを決定として採用しない。subagent の提案は出典にならない。外形か層境界に触れるなら Phase 0 の解釈ゲートへ差し戻し、ユーザーに確認してから計画へ入れる。

計画に含める 6 項目:

• 合意メモの内容: 意図、出典付きの決定、記録の上で進める仮定
• 受け入れ基準: 何が確認できたら完了かを、観察できる条件のリストで書く
• 変更してよい範囲と、触らない範囲。置き換えを含む場合は、不要になる旧コードの削除も範囲と受け入れ基準に含める
• 検証コマンド一覧: プロジェクトの AGENTS.md、CI 定義、既存のビルド・テスト設定から特定する
• 局所対応か根本対応かの選択と、その理由
• 実装をメインが行うか subagent に分担するかと、その理由(「subagent の使いどころ」の基準で決める)

スコープは、差分の小ささではなく要求への過不足のなさで選ぶ。同じ不具合が複数箇所に散る、呼び出し側ごとに同じ判断を繰り返す、データ構造・型・API 境界を直すほうが今後の変更を単純にできる、といった場合は根本対応を選ぶ。広げる場合も現在の要求と因果関係がある範囲に限り、関係の薄い改善は別作業に切り出す。既存の設計意図は尊重し、違う書き方を入れるなら理由を持つ。

出る条件: 6 項目が埋まり、計画をユーザーから見える場所に書き出した。plan 管理 tool(update_plan など)があればそれを使い、なければ本文に短い計画メモとして書く。subagent への依頼文の中だけに計画を置かない。依頼文は暗号化や要約で参照できなくなることがあり、Phase 4 以降の照合先が消える。以降で計画を変える場合は、変更点を明示して更新する。暗黙にゴールをずらさない。

Phase 2 調査・実装

入る条件: Phase 1 の計画が確定し、references/delegation.md をこの会話で読んだ。読んでいなければ着手の前に読む。Phase 0〜1 を飛ばして、要求理解や参照先の探索を subagent に丸投げしない。

やること: Phase 1 で決めたとおりに実装する。

• subagent に分担する場合: 依頼テンプレート、渡す判断基準(抽象化・削除)、報告フォーマットは references/delegation.md の形式に従い、その形式で依頼して返させる。
• メインが実装する場合: references/delegation.md の抽象化・削除の判断基準に自分も従う。実装中に計画の範囲を超えそうになったら、黙って広げず計画を更新してから進める。

出る条件: 分担した場合は報告フォーマットを満たした報告が返ってきた。メインが実装した場合は計画の範囲内で差分ができ、検証コマンドを実行した。

Phase 3 テスト設計

入る条件: 実装方針が見えた、またはテストを追加しそうになった。このフェーズだけは Phase 2 と並行して進めてよい。実装が全部終わってから起動し、既に書いたテストの追認だけをさせてはならない。

やること: テスト設計担当(subagent、または「subagent の使いどころ」の条件でメイン)に次を渡す。

• 守るべき仕様、不安な仕様、壊れやすい境界
• 既存テストで既に守られていること
• テストの追加・修正・不要判断のどれを検討しているか
• test-design-discipline を必ず使うこと。追加するならどの誤変更を防ぐのか、追加しないなら型・既存テスト・ビルド・静的検査で何を担保するのかを答えさせる

出る条件: 変更の中心に対する検証方針が決まり、テストの追加・修正・不要判断の根拠を説明できる。遅くとも Phase 5 に入る前に満たす。

Phase 4 メインの検収

入る条件: 実装の差分ができた(subagent の報告を受け取った、またはメインが実装を終えた)。Phase 6 の反復で修正差分ができたときも、ここへ戻って同じように検収する。

やること: 自己申告や記憶を根拠に次へ進まない。メインセッション自身が実物と照合する。

• git status と git diff --stat(成果物の置き場所に応じた同等の手段)で実際の差分を取得し、報告内容または計画の範囲と突き合わせる。
• 完了判定に使う検証コマンド(Phase 1 の一覧)を、メインが自分で(再)実行する。
• 実差分が報告や修正意図と食い違う場合は、修正元へ差し戻す。

出る条件: 直近の変更内容と実差分が一致し、検証コマンドがメイン自身の実行で通った。

Phase 5 完了前レビュー subagent

入る条件: Phase 4 の検収を通過し、references/review-request.md をこの会話で読んだ。読んでいなければ起動の前に読む。完了報告やコミットの前。

やること: 実装した者とは別の subagent に、文脈の複製なしでレビューを依頼する。依頼に含める項目と順序は references/review-request.md に従う。レビュー担当はファイルを編集せず、指摘を MUST FIX / SHOULD FIX / 確認済み に分類して返す。

出る条件: 分類済みの指摘が返ってきた。

Phase 6 反復と完了

入る条件: レビュー指摘を受け取った。

やること: MUST FIX を修正し、Phase 4 の検収と Phase 5 の再レビューへ戻る。再レビューは修正箇所と影響範囲を重点にする。

• MUST FIX は原則として修正する。修正しない場合は、誤分類・今回の要求外・要求外だが重要なので別作業化・ユーザー確認が必要、のどれに当たるかを明示する。
• SHOULD FIX は、今回の要求と因果関係があり、差分を不必要に広げないものだけ修正する。残す場合は理由を完了報告に書く。
• 実装を分担していた場合、修正は原則として実装担当への差し戻しで行う。差し戻し先は文脈の重さで選ぶ。元のスレッドの文脈がまだ軽いなら会話の継続でよい。長く生きて文脈が重くなったスレッドへの追加依頼は、毎ターンその文脈を支払う。その場合は、元の依頼内容に現在の差分と指摘一覧を添えた新規起動(文脈の複製なし)を選ぶ。会話を継続する仕組みがない環境では、常に新規起動でよい。メインが直接直してよいのは数行程度の軽微な修正に限る。メインが実装していた場合は、メインが修正する。

反復の上限: 既定で 1 巡(修正 → 再検収 → 再レビュー)。2 巡目に入ってよいのは、再レビューで新しい MUST FIX が出た場合だけ。2 巡を終えても新しい MUST FIX が出続ける場合は、局所修正を続けず、残件と選択肢(方針変更・スコープ縮小・ユーザー確認)をまとめてユーザーに報告する。同種の MUST FIX の再発は、対応がパッチ的で問題を先送りしている兆候として扱い、実装担当のグレードを下げていた場合は references/subagent-grades.md の戻しルールに従う。

意味のある単位が完了したら、ユーザーの指示を待たずにコミットの区切りを検討する。コミットする場合の手順・ブランチ確認・メッセージ・署名は git-commit スキルに従う。ここでは重複定義しない。

出る条件: 未対応の MUST FIX がなくなったか、反復の上限に達して残件をユーザーへ報告した。完了時は次の完了報告を埋める。「一応動く」「軽く確認した」では完了扱いにしない。

完了報告テンプレート:

• 受け入れ基準それぞれの充足状況
• 最終差分の要約
• 実行した検証コマンドと結果
• 残した指摘とその理由