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，参见 Plan state）；（2）比例严格度层级（micro / standard / deep，参见 比例严格度）；（3）任务结构中可选的 Delta 段落，用于存量代码的行为变更；（4）DWP 恢复协议升格为具名、可引用的六步仪式。现有 v1.1 计划仍然符合规范。

定义

一份 Deep Work Plan 是一件结构化、仅基于 Markdown 的产物，它描述了一项被分解为一系列连续、可审阅工作单元的复杂工程任务，旨在由自主工作的 AI 编码代理来创建、执行与维护。

DWP 是规范驱动的：计划即规范，代理 MUST 依据其明确的验收标准与验证关卡来执行，而非即兴发挥。规范——而非聊天记录——才是持久的事实来源，因此工作可验证，并可跨会话、跨代理恢复。它同时也是被打磨为可移植形态的 harness 工程：让代理变得可靠的上下文、控制循环、防护栏与可恢复状态，都以纯 Markdown 的形式被安装进代码仓库本身，于是任意符合规范的代理 MAY 在没有工具专属框架的情况下驾驭该仓库。

计划结构

一份计划 MUST 是 .dwp/plans/ 下一个名为 PLAN_<slug>/ 的目录。该目录 MUST 包含：

  • README.md —— 计划概览、目标、任务表与状态。
  • 每项任务一个文件，命名为 <n>.task_<slug>.md。
  • PROGRESS.md —— 一份持续的执行日志。

计划 MAY 额外携带机器可读状态层：manifest.json（静态标识，在物化时写入一次）与 state.json（实时逐任务执行状态）。状态层对新计划 RECOMMENDED，对无人值守执行与无 git 的代理工作区 REQUIRED。参见 Plan state。

任务结构

每个任务文件 MUST 按顺序包含这九个段落：

  1. Goal（目标） —— 用一段文字陈述该任务达成了什么。
  2. Context（上下文） —— 背景、链接，以及这项任务为何存在。
  3. Steps（步骤） —— 有序、具体、要执行的动作。
  4. Acceptance criteria（验收标准） —— 一份界定“完成”的条件清单。
  5. Validation（验证） —— 为核实而要运行的命令或测试。
  6. Files（文件） —— 预计将被创建或修改的路径。
  7. Dependencies（依赖） —— 其他任务或外部前置条件。
  8. Risks（风险） —— 可能出错之处，以及缓解措施。
  9. Completion & Log（完成与日志） —— 一个状态标记外加按时间顺序排列的记录。

任务 MAY 额外包含 Delta 段落（对于存量代码的行为变更 RECOMMENDED——见下文）以及 Rollback 段落（对于迁移、基础设施变更或部署 RECOMMENDED）。

Delta 段落（存量代码的行为变更）

现实中的大多数工作是修改现有行为，而非创造新行为。修改现有系统行为的任务 SHOULD 携带一个 Delta 段落，以三个列表标题将变更描述为明确的前后契约：

  • ADDED —— 任务完成后存在、之前不存在的行为。
  • MODIFIED —— 前后均存在的行为，以 was: … → now: … 的形式表述。
  • REMOVED —— 之前存在、任务完成后被有意移除的行为。

每条记录 MUST 是可观测的行为——接口的响应、CLI 标志、UI 状态、默认值——而非实现细节。Delta 段落是审阅者在行为层面的差异对比：验收标准验证 ADDED/MODIFIED 条目，而 REMOVED 条目则是删除的明确许可。未列为 REMOVED 的内容 MUST 保持正常工作，任务的验证关卡（现有测试保持通过）正是强制执行这一点的机制。

验证关卡与测试

验证就是把“已完成”的声明变为完成证据的那道关卡：在某项任务的“验证”段落中的每条命令都已运行并通过之前，该任务 MUST NOT 被标记为完成。测试是这道关卡的头等组成部分，而非可选的附加项——正是它们让计划交付的代码变得可靠且可验证。

当一项任务新增核心功能，或实质性改变现有行为时：

  • 其验收标准 MUST 包含针对新增或变更行为的自动化测试覆盖（正常路径，外加有意义的边界与错误情形），并遵循代码仓库的测试约定与覆盖率预期。
  • 其验证 MUST 将代码仓库的测试与其 lint、类型检查及格式检查一并运行——即代码仓库所定义的完整代码质量检查——而不仅仅是构建。对于行为变更而言，“它能构建”不是一道充分的关卡。
  • 现有测试 MUST 保持通过。若某项变更破坏了一项覆盖受影响代码的测试，则 MUST 将该测试更新为预期的新行为；它 MUST NOT 仅仅为了强行通过关卡而删除、跳过或弱化测试。

纯文档、配置或研究类任务无需创建测试，但仍 MUST 运行代码仓库所定义的任何验证关卡。测试的深度与变更的规模以及代码仓库的成熟度成正比。当某个代码仓库完全没有测试或 lint 工具链时，代理 MUST NOT 默默跳过这一纪律——它依赖于在接入期间提议的工具链（参见 Conformance）。

安全纪律

安全与测试一样是头等事项，并且遵循同样的双层模型：在工作进行期间贯穿每项任务的纪律，外加在最后对整个变更集执行的一道强制 Security Review 关卡。每当一项任务触及认证或授权、输入处理、机密或配置、网络、文件或 shell 接触面，或依赖时：

  • 其验收标准 MUST 陈述该变更的安全预期——输入经过校验与转义、代码或测试夹具中不含机密材料、认证检查得到保留或加强——并与 docs/SECURITY.md 保持一致。
  • 每次提交在落地之前 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、关卡记录、outcome 记录、提交哈希。

这六个步骤构成一个逻辑事务。在协议执行中途被中断的代理 MUST NOT 启动下一项任务——它必须先完成或撤销部分完成的状态。

DWP 恢复协议

续行 MUST 仅凭计划的文件加上 git 日志即可实现，无需外部状态。在没有 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. 原子性地继续。 恰好执行下一项任务；不得批量预先执行。

代理 MUST 信任已完成（[x]）的标记，MUST NOT 重新验证已完成的任务，除非用户明确要求，或冒烟测试以涉及已完成任务的方式失败。

执行循环

DWP 定义了五项操作：

  • create —— 从一个目标生成一份新计划。
  • execute —— 逐任务执行计划。
  • refine —— 修改一份现有计划。
  • resume —— 恢复一份被中断的计划。
  • status —— 报告计划状态而不执行。

输出工作区

所有 DWP 产物 MUST 存放于代码仓库根目录下一个被 gitignore 的 .dwp/ 目录中。

机器可读计划状态

计划 MAY 携带机器可读状态层——manifest.json（静态标识）与 state.json（实时逐任务状态、验证关卡记录、outcome 记录、检查点、阻塞状态）。Markdown 计划仍是事实来源；JSON 层是一份派生投影，在协议节点处重新生成，并在续行时协调。

状态层对新计划 RECOMMENDED，对无人值守执行 REQUIRED，对无 git 的代理工作区 REQUIRED。完整的规范性定义参见 Plan state。

比例严格度

严格度 MUST 与工作相称。对琐碎变更加诸仪式是方法论的失败，而非额外的安全保障。每项工作恰好落在以下某一层级：

层级 何时适用 形式
micro 单一原子变更：一个关注点，大约一次完成，无需协调。Bug 修复、文案变更、配置调整。 无计划文件夹。代理在对话中内联陈述目标、验收标准与验证关卡，然后执行、验证、提交。
standard 具有实际范围的多步骤工作：一项功能、一次重构、单一代码仓库内的迁移。默认层级。 完整计划：计划文件夹、九段式任务、强制收尾任务。
deep 跨越并行组、子代码仓库或多次无人值守会话的长周期工作。 标准计划加上编排器和/或团队代理能力，以及状态层。

当代理被要求为 micro 层级的工作创建计划时，MUST 说明计划是不成比例的，并改为提供内联形式。计划文件夹 MUST NOT 因琐碎的单文件变更而被创建。

micro 层级工作仍然保持不可妥协的要求：明确的目标、运行并通过的验证关卡，以及行为变更的测试纪律。层级改变的是包装形式，而非关卡。

当范围在执行中途增长时——micro 任务揭示了真实的范围，标准计划生出了子代码仓库——代理 MUST 停下并将工作提升至下一层级，而非拉伸当前层级。

版本控制

本规范遵循语义化版本控制。