対応 issue: #729 根拠となる第一原理:
design-philosophy.mdI-9(承認された宣言は実差分で再検証される — 二段 detect) 本書の位置づけ: design-philosophy.md §8 トリアージにおける #729 の配置先(「plan 前ゲートは PlanGate 側と ai-loop 側の両建て、Deviation Log は decision record と統合検討、I-9 の運用面を補完」) を具体化した機構正本。思想的根拠(なぜ)は design-philosophy.md に譲り、本書は「何を・いつ・ どう記録するか」の手順のみを定義する。
PlanGate はすでに「Plan → Review → 承認 → 実行」の統制を持つが、以下のリスクは 既存フローだけでは潰しきれない:
Unknown Discovery は、この「未知」を 発見(Plan 前)→ 明示(Plan 中)→ 記録(実装中) の
3 ゲートに分けて構造化し、design-philosophy.md I-9
(宣言と実差分は別命題であり、二段で検証する)の運用面を補完する。
AI 駆動開発で発生する典型例を併記する。
| 分類 | 定義 | AI 駆動開発での典型例 |
|---|---|---|
| Known Knowns | 分かっていて明示していること | plan.md の受入基準・Constraints に書かれている前提 |
| Known Unknowns | 分からないと自覚していること | 「この API のレート制限が不明」「既存テストが該当パスをカバーしているか未確認」等、plan.md の Questions / Unknowns 節に書ける粒度のもの |
| Unknown Knowns | 見れば分かるが、事前に言語化できていない暗黙知 | 既存コードの命名規約・エラーハンドリング方針など、コードを読めば分かるが指示文には書かれていない慣習 |
| Unknown Unknowns | 知らないことにすら気づいていないリスク・制約 | 「この変更が別サービスの契約を暗黙に壊す」「HO パスに波及する副作用がある」など、事前に問いすら立っていない領域 |
Unknown Discovery の目的は、Unknown Unknowns をできる限り Known Unknowns に変換し、 残った Unknown Unknowns の存在を「分からないものが残っている」という形で明示することである (ゼロにする、ではなく「不可視を可視化する」)。
小規模タスクへの過剰適用を避けるため、以下の基準で適用要否を判定する。
mode-classification.md の high-risk / critical 相当)mode-classification.md の ultra-light / light 相当判定不能・境界事例は、design-philosophy I-4(安全側デフォルト)に従い適用する側に倒す。
実装計画を作る前に、AI に blindspot pass を実行させる。
確認観点(5 つ):
成果物: plan.md 内 ## Unknowns / Blindspots 節(既存 plan.md の
「Questions / Unknowns」節を拡張する形。新規ファイル unknowns.md は本書では採用しない
— plan.md と別ファイルに分裂させると参照漏れが起きやすく、C-3 レビュー時に一体で読める
ほうが実効性が高いため。ただし高リスク・複数論点で plan.md が肥大化する場合は、担当者判断で
別ファイル化してよい)。
単なる作業順序ではなく、人間が調整・判断しそうな論点を先に出す。
優先して明示する 6 領域:
これらは plan.md の Work Breakdown / Risks & Mitigations 節に、「この論点は人間の 判断待ちである」ことが分かる形で明記する。C-3 ゲート(人間レビュー)が、この明示を前提に 判断できることが目的であり、C-3 の判定基準自体は変更しない。
実装中に計画と現実の差分が出た場合、勝手に大きく設計変更せず、理由を記録する。
記録する 5 項目:
成果物: plan.md 内 ## Deviations 節、または docs/working/TASK-XXXX/status.md
の「計画からの変更点」節(working-context.md
既存節を流用。新規 implementation-notes.md は本書では採用しない — status.md が既に
「計画からの変更点」を持つため、成果物を増やすより既存節に統合するほうが Progressive
Disclosure(L1 で読める)と整合する)。
「勝手に大きく設計変更しない」の運用境界:
design-philosophy.md I-1 の枠内で、
承認境界の拡大解釈を自己判断しない)Deviation Log(4.3)と、ai-loop の decision record
(execution-runbook.md §2-(4) 「decision record を保存」)は、
別の記録ではなく同一の記録機構への異なる入力として扱う方針とする。
| 項目 | Deviation Log(本書) | decision record(execution-runbook §2-(4)) |
|---|---|---|
| 記録主体 | PlanGate 標準フロー(人間 C-3/C-4 前提) | ai-loop(Arbiter 裁定後) |
| 記録タイミング | 実装中、計画との差分発生時 | 1 サイクル完了後 |
| 記録先 | plan.md ## Deviations / status.md |
decision record(ai-loop 側の永続化先) |
| 統合方針 | PlanGate 標準フローの Deviation Log は decision record の前身データとして扱い、ai-loop 適用領域では同一項目(発見事実・計画差分・対応・要判断論点・学び)を decision record のフィールドに写像する。二重記録・二重正本は作らない | — |
具体的なフィールド対応(decision record 側スキーマの拡張)は、ai-loop 側の実装 PBI で
decision-table.md §5 provenance スキーマとの整合を確認した上で
確定する。本書は「統合する」という方針表明までとし、スキーマ確定は本書の scope 外。
issue #729 の検討事項に含まれる「Review 前の Understanding / Quiz Gate」は、
本書の 3 ゲート(Discovery / Tweakable Decision / Deviation Log)とは性質が異なり
(実装前後ではなく PR レビュー直前が対象)、PlanGate の C-4(PR レビュー)運用に接続する
別ゲートとして扱う。本書では 導入するかどうかの検討事項として記録するに留め、
確定した観点定義は別途 PR レビュー関連の正本(review-principles.md
等)側で扱う。
想定される確認観点(参考):
design-philosophy.md I-9 は「承認された宣言
(plan)と実差分は別命題であり、二段で検証する」という検証構造の原理である。
本書の 3 ゲートは、その運用面を以下のように補完する:
本書は I-9 の検証構造そのものを変更しない。あくまで、その前後に人間・AI が参照する 記録の質を上げるための運用手順である。
design-philosophy.md §2 I-9 / §8 トリアージ(#729 行)execution-runbook.md §2-(4)(decision record 保存)decision-table.md §5(provenance スキーマ)working-context.md(status.md「計画からの変更点」節)mode-classification.md(適用対象の mode 判定)