DWP 仕様

バージョン 4.0.0。状態: 安定。 この文書は Deep Work Plan（DWP）方法論の規範的な仕様です。キーワード MUST、MUST NOT、SHOULD、SHOULD NOT、MAY は、RFC 2119 に記述されたとおりに解釈されます。

2.4.0 での追加、破壊的変更なし。 （1）変更対象面（Touched Surface） セクション — タスクが変更するものと検証されなければならないものとの契約であり、リスククラス（isolated / seam / shared-core / unknown）によるゲート選択を伴う。（2）完全な検証は計画唯一の必須 Final Review で実行される最終状態要件となり、明示的な証拠再利用ルールが伴う。（3）タスク内スキル決定は所有タスクへ移り、Executive Report はオプションで要求に応じたものになる。（4）モード対応の create フロー — trust モードは分析と品質チェックを保ちながら直接マテリアライズする。（5）Lite ファーストの計画マテリアライゼーション — ガイド付き create は、非実行可能なドラフトの代わりに直接実行可能な Lite 計画 を生成し、いつでも Full 計画へ昇格できる（Lite 計画を参照）。（6）明示的な互換性マトリクス：より前のバージョンの計画とリポジトリは適合したまま。

標準 4.0.0。 このバージョンの跳びは、標準の番号を製品ラインと揃えるためのものです — 2.x は歴史的バージョンで、3.x 標準は存在しません — そして 2.4.0 から要件は一切変わっていません。以前のバージョンの計画とリポジトリは引き続き適合します。

定義

Deep Work Plan は、複雑なエンジニアリング作業を逐次的でレビュー可能な作業単位へと分解して記述する、構造化された Markdown のみの成果物であり、自律的に働く AI コーディングエージェントによって作成、実行、維持されるよう設計されています。

DWP は仕様駆動です。計画が仕様であり、エージェントは即興するのではなく、その明示的な受け入れ基準と検証ゲートに照らして実行しなければなりません（MUST）。仕様こそが、チャットの履歴ではなく、永続的な信頼できる情報源であるため、作業は検証可能で、セッションとエージェントをまたいで再開可能です。これは同時に、ハーネスエンジニアリングを持ち運び可能にしたものでもあります。エージェントを信頼できるものにするコンテキスト、制御ループ、ガードレール、再開可能な状態が、プレーンな Markdown としてリポジトリそのものにインストールされるため、適合するあらゆるエージェントは、ツール固有のフレームワークなしにリポジトリを操縦できます（MAY）。

create フロー — 単一ステップ、モード対応

create フローは目的、コンテキスト、制約、タスクアウトラインを一度に収集し、要件分析（スコープ、タスク間の依存順序付け、変更対象面からの検証選択、比例リゴーのティア）を実行し、開発者が選んだモードに従ってマテリアライズします。

ガイド付きモード（デフォルト）。 フローは Lite 計画 を直接マテリアライズします — インラインの {#task-N} タスクレコードを持つ、コンパクトで既に実行可能な提案であり、一回のパスでレビューできます — そして開発者に、それを Lite のまま維持するか、Full 計画へ昇格させるか、変更を要求するか、あるいは停止するかを尋ねます。中間的な非実行可能ドラフトは生成されません。
trust モード（trust / auto）。 フローは選択された表現形式（Lite、または Lite の直後に Full へ昇格したもの）をレビューステップなしで直接マテリアライズします — 開発者がそれを放棄したのです。要件分析、依存順序付け、そして計画品質チェックは引き続き実行されます。trust が放棄するのはレビューであって分析ではありません。trust モードの計画は無人実行に向けて事前承認済みとして記録されます。

どちらのモードも、計画の形式（Lite か Full か）を同じ要件分析の一部として決定し、後付けで決めることは決してありません。表現形式、作成と選択、昇格のライフサイクル全体については Lite 計画を参照してください。

計画の構造

計画は .dwp/plans/ 配下の PLAN_<slug>/ という名前のディレクトリで、次の二つの表現形式のいずれかでなければなりません（MUST）。

Full。 ディレクトリは README.md（計画の概観、目標、タスク表、状態）、タスクごとに一つの <n>.task_<slug>.md という名前のファイル、そして PROGRESS.md（実行の進行ログ）を含まなければなりません（MUST）。
Lite。 コンパクトで完全に実行可能なタスクレコードが、別個のタスクファイルの代わりに、安定した {#task-N} アンカーの背後で README.md にインラインで存在します — 各レコードは、目標、変更対象面、受け入れ基準、検証、完了ログを引き続き持ちます。PROGRESS.md は引き続き REQUIRED です。Lite 計画はいつでも Full へ昇格しても(MAY)構いません。完全なライフサイクルはここで繰り返さず、Lite 計画を参照してください。

計画は追加で機械可読な状態レイヤーを MAY 携えることができます。manifest.json（マテリアライゼーション時に一度書き込まれる静的な識別情報）と state.json（タスクごとのライブ実行状態）です。状態レイヤーは新しい計画に対して RECOMMENDED であり、無人実行および git のないエージェントワークスペースに対しては REQUIRED です。計画の状態を参照してください。

タスク構造

タスクファイル

01 Title
02 Context
03 Read Before Starting
04 Goal
05 Touched Surface
06 Instructions
07 Acceptance Criteria
08 Outputs
09 Validation
10 Execution Checklist + Completion & Log

Every task file follows the same ten ordered sections defined by the installed skill, so each unit of work is self-contained and reviewable.

各タスクファイルは、これら十の節をこの順序で含まなければなりません（MUST）。

Goal（目標） — タスクが何を達成するかを述べる一段落。
Context（コンテキスト） — 背景、リンク、そしてこのタスクが存在する理由。
Touched Surface（変更対象面） — タスクが変更するものと、検証されなければならないものとの契約。
Steps（手順） — 実行すべき、順序づけられた具体的な行動。
Acceptance criteria（受け入れ基準） — 完了を定義する条件のチェックリスト。
Validation（検証） — 検証のために実行するコマンドやテスト。変更対象面から選択される。
Files（ファイル） — 作成または変更されると見込まれるパス。
Dependencies（依存関係） — 他のタスクや外部の前提条件。
Risks（リスク） — 何がうまくいかない可能性があるか、そしてその緩和策。
Completion & Log（完了とログ） — 状態マーカーと時系列の記録。

タスクは追加で Delta セクション（ブラウンフィールドの挙動変更に対して RECOMMENDED — 下記参照）と Rollback セクション（マイグレーション、インフラ変更、またはデプロイメントに対して RECOMMENDED）を MAY 含むことができます。

変更対象面

変更対象面は、タスクが変更するものと検証されなければならないものとの契約です。それは、検証が習慣ではなく効果によって選択されるため、また後の読者がゲートがなぜ選ばれたのかを見られるために存在します。挙動を変更するタスクは次を記録しなければなりません（MUST）。

計画面 — タスクが変更しようとするパス、モジュール、パッケージ、設定。編集の前に書かれる。
実際の面 — 編集後に照合されたリスト。実際の差分から取られる。エージェントはゲートを選択する前に計画面と実際の面を照合しなければなりません（MUST）。
影響を受けるコンシューマー — 実際の面に依存するモジュール、パッケージ、サービス。リポジトリの文書化されたマッピングが確立できる範囲まで。確立できない場合、そのエントリーはそう述べなければなりません（MUST）。
リスククラス — 次のいずれか。isolated（隔離。一つのモジュールとそのテストに限定）、seam（継ぎ目。協調者間の契約、永続化、ルーティング、シリアライゼーション、認証、フレームワーク配線を変更する）、shared/core（共有／コア。広くインポートされる、または依存関係、マイグレーション、ビルド／テスト設定、スキーマ、ツールチェーンの変更）、unknown（不明。マッピングが欠落、古い、または未検証）。
使用したテストマッピング — どの文書化されたマッピングまたはツールがその選択を生成したか。
選択されたゲートと理由 — 正確なコマンドと、それらが実際の面をなぜカバーするのか。

設定ファイル、スキーマ、依存関係マニフェスト、テンプレート、フィクスチャ、マイグレーション、エージェント指示ファイルは挙動を変更し得るものであり、ファイル拡張子ではなく効果によって分類されなければなりません（MUST）。散文、コメント、調査成果物のみを変更するタスクは、変更対象面を適用外と宣言する MAY を持ち、それでもリポジトリの非ランタイムチェックを実行します。

Delta セクション（ブラウンフィールドの変更）

実際の作業のほとんどは、新しい挙動を作るのではなく、既存の挙動を変更するものです。既存システムの挙動を変更するタスクは、変更を明示的なビフォー・アフターの契約として記述する Delta セクション を持つべきです（SHOULD）。三つのリスト見出しを使用します。

ADDED — タスクの後に存在し、以前は存在しなかった挙動。
MODIFIED — 両方に存在し、was: … → now: … の形式で記述された挙動。
REMOVED — 以前は存在し、タスクの後に意図的に消滅する挙動。

各エントリーは観察可能な挙動でなければなりません（MUST）。エンドポイントのレスポンス、CLI フラグ、UI の状態、デフォルト値 — 実装の詳細ではありません。Delta セクションは挙動レベルでのレビュアーの差分です。受け入れ基準は ADDED/MODIFIED エントリーを検証し、REMOVED エントリーは削除の明示的なライセンスです。REMOVED としてリストされていないものは MUST 引き続き動作しなければなりません。

検証ゲート — リスククラスによる選択

検証は、完了の主張を完了の証拠へと変えるゲートです。タスクは、その Validation 節にあるすべてのコマンドが実行されて合格するまで、完了とマークしてはなりません（MUST NOT）。挙動を変更するタスクのゲートは、照合済みの変更対象面からリスククラスに基づいて選択されます。

リスククラス	必須の検証
isolated（隔離）	変更された挙動とその影響を受けるコンシューマーのテストに加え、実際の面をカバーする静的チェック。
seam（継ぎ目）	上記に加え、その継ぎ目のインテグレーションまたは契約テスト — 存在しない場合はこのタスクで追加する。継ぎ目でのインテグレーションチェックは計画の末尾に先送りされない。
shared/core（共有／コア）	影響を受けるパッケージとその推移的コンシューマーへ拡大する。影響を確実に限定できない場合、完全な検証を実行する。
unknown（不明）	調査して選択を修正する。それでも確立できない場合、より広いまたは完全なコマンドを実行する。
適用外（散文／調査）	リポジトリの非ランタイムチェック。理由は変更対象面に記録される。

挙動変更は、空でない関連するテスト選択を生成しなければなりません（MUST） — 無効なセレクターやゼロのテストを選択したランナーは網羅ではありません。リポジトリのテストマッピングが古い場合、正しい呼び出しを導出し、マッピング更新を記録します。小さなコマンドの欠落のために完全なオンボーディング実行が要求されることは決してありません。スコープされた呼び出しが存在しない場合、完全な適用可能スイートが適用されます — レガシーの挙動であって、決してエラーではありません。

タスクが新しい中核機能を追加したり、既存の挙動を実質的に変更したりする場合、その受け入れ基準は新しいまたは変更された挙動に対する自動テストの網羅を含まなければならず（MUST）、その検証はリポジトリのテストをリント、型チェック、フォーマットチェックとともに — ビルドだけでなく — 実行します。既存のテストはグリーンを保たなければなりません（MUST）。

最終状態検証

タスクごとのゲートは各タスクが触れたものを検証しますが、計画全体の検証の代わりにはなりません。計画が完了する前に、リポジトリの完全に適用可能な検証が、最後の実質的な変更の後の最終的な関連状態において — Final Review の中で — 実行されて合格しなければなりません（MUST）。より早い段階での広い実行は、統合境界または shared/core 変更の後に行われ、タスク数のスケジュールでは行われません。合格した結果は、関連する入力が等価であるという証拠がある場合にのみ再利用できます（MAY）。それ以外の場合は再実行されます。各ゲート実行は簡潔な記録を残します。コマンド、スコープ、リビジョン、結果、そして証拠のパスです。

セキュリティの規律

セキュリティはテストと同じように第一級であり、同じ二層モデルに従います。作業が行われている間のタスクごとの規律に加えて、最後に Final Review のセキュリティパスが変更セット全体を監査します。タスクが認証または認可、入力処理、シークレットや設定、ネットワーク・ファイル・シェルの接触面、または依存関係に触れるときは必ず、次が当てはまります。

その受け入れ基準は、その変更のセキュリティ上の期待——入力が検証されエスケープされていること、コードやフィクスチャにシークレット情報がないこと、認証チェックが維持または強化されていること——を docs/SECURITY.md と整合する形で述べなければなりません（MUST）。
すべてのコミットは、それが入る前に、テストのフィクスチャとドキュメントの例を含めて、シークレットや認証情報を含まないことを確認しなければなりません（MUST）。プッシュされたコミットの中のシークレットは、単に削除されるのではなく、漏洩したものとして扱われローテーションされなければなりません（MUST）。
セキュリティに敏感な作業が相当な場合、専用のハードニングタスクを実装タスクの直後、包括的テストのタスクの前に置くべきです（SHOULD）。そうすれば、テストが挙動を固定する前に発見事項が修正され、各発見事項が手戻りではなく回帰ケースになります。

このタスクごとの規律は、Final Review のセキュリティパスを置き換えるものではありません。タスクごとのチェックは問題が生まれたコミットでそれを捕らえ、最終ゲートは計画全体——テストとドキュメントのタスク自体を含む——を監査します。

計画ライフサイクル — Final Review

このバージョンのもとで書かれたすべての適合計画は、ちょうど一つの必須タスクで終わります。すなわち Final Review（タスク N）です。より前のバージョンが別々の最終タスクに置いていた二つの責務は再配置されます。スキルの決定はそのパターンを生んだタスクへ移り、Executive Report はオプションの要求に応じた成果物になります。セキュリティパスで緩められるものは何もありません。

Final Review は次の順序で行わなければなりません（MUST）。

（a）セキュリティパス — 計画の累積した変更一式を、ハードコードされたシークレット、インジェクションのリスク、新たな攻撃面、弱められた認証、ログやドキュメント内の機密データについてレビューする。導入された依存関係を監査する。docs/SECURITY.md がなお現実を反映していることを確認する。クリーンな場合でもセキュリティレビューレポートを書く。重大な発見事項は、計画が完了する前に修正される — またはユーザーによって明示的に受け入れられる。

（b）最終状態検証 — リポジトリの完全に適用可能な検証が、最終的な関連状態において実行されて合格する。

（c）スキルの突き合わせ — すべてのタスクがスキル処分を運び、記録されたすべての候補に処分がある。二つ目の探索レポートはない。

（d）完了 — 成果物、検証の証拠、制限とともに完了を報告する。Executive Report を一度だけ提案する。提案が回答されるかどうかにかかわらず、計画は完了しています。

Final Review は他のすべてのタスクの後に逐次的に実行され、並列グループに置かれることは決してありません。

タスク内スキル決定

「この作業は、スキルやエージェントに値する再利用可能なパターンを生んだか？」という問いは、そのパターンを生んだタスクの内部で、証拠がまだコンテキストにあるうちに答えられます。すべてのタスクの Completion & Log はスキル処分を運びます。なし、既存スキルの更新、名前付き成果物の作成、または理由を伴う見送りのいずれかです。正当な作成は、そのタスクの内部で、その検証ゲートとコミットの前に、既存カタログとの重複チェックの後に行われます。

Executive レポート — オプションで要求に応じて

Executive Report はもはや必須のタスクではありません。完了時にエージェントが一度だけ提案し、明示的な要求があった場合にのみ、計画を再生せずに永続的な証拠から生成されます。回答がない場合や無人実行の場合でも、計画はレポートを生成せずに完了したままです。

タスク完了プロトコル

バリデーションを通過した後、次のタスクへ進む前に、エージェントはこの順序で次を MUST 実行しなければなりません。（1）計画の README でタスクを [x] とマークする。（2）計画のステータスカウントをインクリメントする。（3）タスクの Completion & Log をプレースホルダーなしで記入する。（4）PROGRESS.md に 3〜5 箇条書きのエントリーを追加する。（5）計画がコミットする場合、{type}({scope}): {description} — Task {N} of PLAN_{name} の形式でコミットする。（6）計画が状態レイヤーを持つ場合、state.json をアトミックに上書きする — タスクを completed、ゲートレコード、アウトカムレコード、コミットハッシュを含む。

六つのステップが一つの論理的なトランザクションを形成します。プロトコルの途中で中断されたエージェントは、次のタスクを開始してはなりません（MUST NOT）。部分的な完了を終了するか、巻き戻さなければなりません。

DWP 再開プロトコル

再開は、外部状態なしに、計画のファイルと git ログのみから MUST 可能でなければなりません。git のないワークスペースでは（アーキタイプ §3 を参照）、計画の state.json が REQUIRED であり、git ログの代わりを担います。

再開するエージェント — 新しいセッション、別のエージェント、スケジュールされたデーモンターン、または起動するクラウドセッション — はこの儀式をこの順序で MUST 実行しなければなりません。

再アンカー。 計画の README を読む。目標、グローバルガイドライン、タスクリスト。
チェックポイントを特定する。 README の最初の未チェックタスクを見つける。git ログと git status を読む（git がない場合は state.json の checkpoint）。
状態を照合する。 state.json が存在する場合、README のチェックボックスと照合する。デシンクがある場合、続行前に Markdown から再生成する。
継ぎ目を確認する。 再開ポイントのタスクの Completion & Log と最後の PROGRESS.md エントリーを読む — 前のセッションの最後に検証された地点。
スモークテスト。 リポジトリの最も安価な常設バリデーションを実行し、構築する前に世界がまだ機能していることを確認する。失敗したスモークテストは、その上に構築するのではなく、まず調査する。
アトミックに継続する。 まさに次のタスクを実行する。先に進めない。

エージェントは完了済みの（[x]）マークを MUST 信頼しなければならず、ユーザーが明示的に要求した場合、またはスモークテストが完了済みタスクに関連する形で失敗した場合を除き、完了済みタスクを再バリデーションしてはなりません（MUST NOT）。

実行ループ

DWP のコアループ。五つの操作が計画を目標から完了した作業へと進め、検証が適合性のゲートとなります。

DWP は五つの操作を定義します。

create — 目標から新しい計画を生成する。
execute — 計画をタスクごとに実行する。
refine — 既存の計画を修正する。
resume — 中断された計画を再開する。
status — 実行せずに計画の状態を報告する。

出力作業領域

出力ワークスペース

.dwp/ git 無視・破棄可
plans/
PLAN_<name>/
README.md
PROGRESS.md
<n>.task_<slug>.md
analysis_results/ レポート
SECURITY_REVIEW.md セキュリティレビュー
EXECUTIVE_REPORT.md エグゼクティブレポート

プランのすべての出力は、git で無視される `.dwp/` ワークスペースに置かれ、追跡対象のソースとは別に管理されます。

すべての DWP 成果物は、リポジトリのルートにある gitignore された .dwp/ ディレクトリの配下に存在しなければなりません（MUST）。

機械可読な計画状態

計画は機械可読な状態レイヤーを MAY 携えることができます。manifest.json（静的な識別情報）と state.json（タスクごとのライブ状態、バリデーションゲートレコード、アウトカムレコード、チェックポイント、ブロック状態）です。Markdown の計画が信頼できる情報源であり続け、JSON レイヤーはプロトコルポイントで再生成され再開時に照合される導出された投影です。

状態レイヤーは新しい計画に対して RECOMMENDED であり、無人実行に REQUIRED であり、git のないエージェントワークスペースに REQUIRED です。完全な規範的な定義は計画の状態を参照してください。

比例したリゴー

リゴーは作業に比例しなければなりません（MUST）。些細な変更に対するセレモニーは方法論の失敗であり、余分な安全性ではありません。すべての作業はちょうど一つのティアに属します。

ティア	適用場面	形式
micro	単一のアトミックな変更。一つの関心事、おおよそ一回の作業、調整なし。バグ修正、コピー変更、設定の調整。	計画フォルダーなし。エージェントは目標、受け入れ基準、バリデーションゲートを会話の中でインラインで述べ、実行し、バリデーションし、コミットする。
standard	実際のスコープを持つ複数ステップの作業。機能、リファクタリング、一つのリポジトリ内のマイグレーション。デフォルトのティア。	完全な計画。計画フォルダー、十の節からなるタスク、Final Review。
deep	並列グループ、子リポジトリ、または複数の無人セッションにまたがる長期的な作業。	標準計画に加えて、オーケストレーターおよび／またはチームエージェント機能と状態レイヤー。

micro ティアの作業に対して計画を作成するよう求められたエージェントは、計画が不釣り合いであることを MUST 述べ、代わりにインライン形式を提案しなければなりません。些細な単一ファイルの変更に対して計画フォルダーを作成してはなりません（MUST NOT）。

micro ティアの作業でも、交渉不可の事項は維持されます。明示的な目標、実行されて合格するバリデーションゲート、そして挙動変更のためのテストの規律。ティアはパッケージングを変えるのであり、ゲートを変えるのではありません。

スコープが途中で成長した場合 — micro タスクが実際のスコープを明らかにする、標準計画にサブリポジトリが生える — エージェントは MUST 止まって、現在のものを引き延ばすのではなく、作業を次のティアに昇格させなければなりません。

互換性

より前のバージョンの計画とリポジトリは適合したままです。適合チェッカーは、既知のレガシー成果物（受け入れる）と、このバージョンを宣言しながらその下で客観的に無効な成果物（拒否する）を区別しなければなりません（MUST）。

ケース	ルール
より前のバージョンのもとで書かれた計画（三つの必須最終タスク。変更対象面のないタスク）をこのバージョンが実行する	サポートされる。自身の記録されたかたちのもとで実行される — 最終タスクは追加、削除、並べ替えされず、変更対象面が途中で追加されることもなく、検証は完全な適用可能スイートにフォールバックする。`refine` セッションが意図的に移行する MAY を持つ。
より前のバージョンのもとでオンボーディングされたリポジトリを、このバージョンがオンボーディングまたは計画化する	サポートされる。計画はフルスイートのゲートにフォールバックする。スコープされた呼び出しの文書の欠落は、対象のハーネスアップグレードを名指す発見事項であり、決して失敗ではない。
このバージョンのもとで書かれた計画、このバージョンに従うエージェント	サポートされる — これが目標のかたち。
このバージョンのもとで書かれた計画、より前のバージョンに従うエージェント	サポートされない。文書化されている。より古いスキルを固定しているリポジトリは、新しい計画を採用する前にスキルをアップグレードすべきです（SHOULD）。

バージョニング

この仕様はセマンティックバージョニングに従います。