Skip to content
← すべての仕様ドキュメント

DWP 仕様

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

v1.2 での追加。 四つの追加機能、破壊的変更なし。（1）機械可読な計画状態レイヤー（manifest.json + state.json、計画の状態 を参照）、（2）比例したリゴーのティア（micro / standard / deep、比例したリゴー を参照）、（3）ブラウンフィールドの挙動変更のためのタスク構造内のオプションの Delta セクション、（4）DWP 再開プロトコルが命名された引用可能な六ステップの儀式として昇格。既存の v1.1 計画は適合したままです。

定義

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

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

計画の構造

計画は .dwp/plans/ 配下の PLAN_<slug>/ という名前のディレクトリでなければなりません（MUST）。そのディレクトリは次のものを含まなければなりません（MUST）。

  • README.md — 計画の概観、目標、タスク表、状態。
  • タスクごとに一つのファイル。<n>.task_<slug>.md という名前。
  • PROGRESS.md — 実行の進行ログ。

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

タスク構造

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

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

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

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

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

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

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

検証ゲートとテスト

検証は、完了の主張を完了の証拠へと変えるゲートです。タスクは、その Validation 節にあるすべてのコマンドが実行されて合格するまで、完了とマークしてはなりません（MUST NOT）。テストはこのゲートの第一級の構成要素であり、任意の付け足しではありません。テストこそが、計画の出荷するコードを信頼でき検証可能なものにします。

タスクが新しい中核機能を追加したり、既存の挙動を実質的に変更したりする場合。

  • その受け入れ基準は、新しいまたは変更された挙動に対する自動テストの網羅（ハッピーパスに加えて、意味のあるエッジケースとエラーケース）を、リポジトリのテスト規約とカバレッジの期待に従って含まなければなりません（MUST）。
  • その検証は、ビルドだけでなく、リポジトリのテストをそのリント、型チェック、フォーマットチェックとともに——リポジトリが定義する完全なコード品質チェックを——実行しなければなりません（MUST）。「ビルドが通る」は、挙動変更にとって十分なゲートではありません。
  • 既存のテストはグリーンを保たなければなりません（MUST）。影響を受けるコードを網羅するテストを壊す変更は、そのテストを意図された新しい挙動へと更新しなければなりません（MUST）。ゲートを無理に通すためだけに、テストを削除、スキップ、または弱めてはなりません（MUST NOT）。

純粋なドキュメント、設定、または調査のタスクは、テストの作成を免除されますが、それでもリポジトリが定義するいかなる検証ゲートも実行しなければなりません（MUST）。テストの深さは、変更の大きさとリポジトリの成熟度に比例します。リポジトリにテストやリントのツールチェーンがまったくない場合、エージェントはこの規律を黙って省いてはなりません（MUST NOT）。それはオンボーディング中に提案されるツールチェーンに依存します（適合性を参照）。

セキュリティの規律

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

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

このタスクごとの規律は、Security Review の最終タスクを置き換えるものではありません。タスクごとのチェックは問題が生まれたコミットでそれを捕らえ、最終ゲートは計画全体——テストとドキュメントのタスク自体を含む——を監査します。したがってすべての計画は、三つの必須の最終タスク——Security Review、次に Skills & Agents Discovery、次に 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 実行しなければなりません。

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

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

実行ループ

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

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

出力作業領域

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

機械可読な計画状態

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

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

比例したリゴー

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

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

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

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

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

バージョニング

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