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 流程——信任模式在保留分析与质量检查的同时直接物化；（5）Lite 优先的计划物化——引导式 create 直接产出一份可直接执行的 Lite 计划，而非不可执行的草案，并可在任意时刻晋升为 Full 计划（参见 Lite 计划）；以及（6）明确的兼容性矩阵：来自更早版本的计划与仓库仍然符合规范。

标准 4.0.0。 此次版本号跳变将标准的编号与产品线对齐——2.x 为历史版本，不存在 3.x 标准——并且不改变 2.4.0 的任何要求。早期版本的仓库与计划仍然符合标准。

定义

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

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

create 流程——单步、模式感知

create 流程一次性收集目标、上下文、约束与任务大纲，执行其需求分析（范围、任务间的依赖排序、从触及面出发的验证选择、比例严格度层级），然后按开发者所选择的模式物化：

• 引导模式（默认）。 该流程直接物化一份Lite 计划——一份紧凑、已经可执行的方案，任务记录以内联 {#task-N} 的形式呈现，可在一轮之内审阅完毕——并请开发者选择将其保留为 Lite、晋升为 Full 计划、请求修改，或停止。不再产生中间的不可执行草案。
• 信任模式（trust / auto）。 该流程直接物化所选定的形态（Lite，或 Lite 之后立即晋升为 Full），不设审阅步骤——开发者已放弃该步骤。需求分析、依赖排序与一次计划质量检查仍然运行：信任放弃的是审阅，而非分析。信任模式的计划被记录为已预批准用于无人值守执行。

两种模式都在同一次需求分析中决定计划的格式（Lite 或 Full），绝不是事后才决定。完整的形态、创建与选择、晋升生命周期参见 Lite 计划。

计划结构

一份计划 MUST 是 .dwp/plans/ 下一个名为 PLAN_<slug>/ 的目录，采用以下两种形态之一：

• Full。 该目录 MUST 包含 README.md（计划概览、目标、任务表与状态）、每项任务一个、命名为 <n>.task_<slug>.md 的文件，以及 PROGRESS.md（一份持续的执行日志）。
• Lite。 紧凑、完全可执行的任务记录以内联形式存在于 README.md 中，位于稳定的 {#task-N} 锚点之后，而非单独的任务文件——每条记录仍然携带目标、触及面、验收标准、验证与完成日志。PROGRESS.md 仍然 REQUIRED。一份 Lite 计划 MAY 在任意时刻被晋升为 Full。完整生命周期参见 Lite 计划，此处不再重复。

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

任务结构

任务文件

1. 01 Title
2. 02 Context
3. 03 Read Before Starting
4. 04 Goal
5. 05 Touched Surface
6. 06 Instructions
7. 07 Acceptance Criteria
8. 08 Outputs
9. 09 Validation
10. 10 Execution Checklist + Completion & Log

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

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

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

触及面

触及面是任务改动之物与必须验证之物之间的契约。它的存在是为了让验证按效果选择而非按习惯，并让后来的读者能看到关卡为何如此选择。一项改变行为的任务 MUST 记录：

• 计划面 —— 该任务打算更改的路径、模块、包或配置，在编辑之前写就。
• 实际面 —— 编辑后与计划核对过的清单，取自真实的 diff。代理 MUST 在选择关卡之前核对计划面与实际面。
• 受影响的消费方 —— 依赖实际面的模块、包或服务，以代码仓库已文档化的映射所能确立的范围为准。在无法确立之处，条目 MUST 说明这一点。
• 风险级别 —— 以下之一：isolated（隔离，局限于单一模块及其测试）；seam（接缝，更改协作方之间的契约、持久化、路由、序列化、认证或框架接线）；shared/core（共享核心，被广泛导入，或是依赖、迁移、构建/测试配置、schema 或工具链变更）；unknown（未知，映射缺失、过期或未经验证）。
• 所用的测试映射 —— 哪份已文档化的映射或哪个工具产出了该选择。
• 所选关卡及理由 —— 确切的命令，以及它们为何覆盖实际面。

配置文件、schema、依赖清单、模板、测试夹具、迁移与代理指令文件能够改变行为，MUST 按其效果分类，绝不按文件扩展名。一项只更改散文、注释或研究产物的任务 MAY 声明触及面不适用，但仍要运行代码仓库的非运行时检查。

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

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

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

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

验证关卡——按风险级别选择

验证就是把“已完成”的声明变为完成证据的那道关卡：在某项任务的“验证”段落中的每条命令都已运行并通过之前，该任务 MUST NOT 被标记为完成。一项改变行为的任务，其关卡从经核对的触及面按风险级别选择：

一项行为变更 MUST 产出非空且相关的测试选择——无效的选择器或一个选中零个测试的运行器都不算覆盖。在代码仓库的测试映射过期之处，推导出正确的调用并记录映射更新；一条缺失的小命令绝不要求一次完整的接入运行。在不存在限定范围调用之处，适用完整适用的套件——这是旧行为，绝不是错误。

当一项任务新增核心功能或实质性改变现有行为时，其验收标准 MUST 包含针对新增或变更行为的自动化测试覆盖，其验证将代码仓库的测试与 lint、类型检查及格式检查一并运行——而不仅仅是构建。现有测试 MUST 保持通过。

最终状态验证

逐任务的关卡验证每项任务触及的内容；它们并不取代对整份计划的验证。在一份计划完成之前，代码仓库完整适用的验证 MUST 在最后相关状态上——即最后一次实质性变更之后——于 Final Review 中运行并通过。更早的宽范围运行发生在集成边界或 shared/core 变更之后，而非按任务计数的时间表。一个通过的结果 MAY 仅在存在证据表明相关输入等价时被复用；否则重新运行。每次关卡运行留下一条简明记录：命令、范围、修订版本、结果，以及证据路径。

安全纪律

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

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

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/ 被 git 忽略 · 可丢弃
• plans/
• PLAN_<name>/
• README.md
• PROGRESS.md
• <n>.task_<slug>.md
• analysis_results/ 报告
• SECURITY_REVIEW.md 安全审查
• EXECUTIVE_REPORT.md 执行摘要报告

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

机器可读计划状态

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

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

比例严格度

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

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

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

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

兼容性

来自更早版本的计划与仓库仍然符合规范，符合性检查器 MUST 区分一件已知的旧版产物（接受）与一件声明本版本、却在本版本下客观无效的产物（拒绝）：

版本控制

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