Skip to content
Deep Work Plan 今天登陆 Product Hunt 去支持
← 全部规范文档

符合性

版本 1.3。状态：稳定。 本文档界定了一个代码仓库符合 Deep Work Plan——也就是 AI-first、可被代理驾驭——意味着什么。关键词 MUST、MUST NOT、SHOULD、SHOULD NOT 与 MAY 应按 RFC 2119 中所述加以解释。

符合性之所以存在，是为了让“AI-first”成为一项客观、可核查的属性，而非一种印象。一个仓库要么满足下述标准，要么不满足。verify 子技能（/dwp-verify）会以机械方式核查它们。

一个符合规范的代码仓库

一个符合 DWP 的代码仓库 MUST 满足以下全部要点。每一件产物都 MUST 为该仓库经过推理——适配于它真实的语言、框架与命令。一份泛用的占位骨架、一个占位符，或从另一个仓库复制来的内容，都不满足任何一项标准。

  1. 根目录的 AGENTS.md。 仓库 MUST 包含一个根级 AGENTS.md，其中含有（a）文档索引、（b）该仓库的强制规则，以及（c）一个 Quick Commands 块，其命令在本仓库中真实且可运行。占位命令（例如在一个不使用 npm 的仓库中出现 npm test）MUST NOT 出现。该索引 MUST NOT 链接一个不存在的 docs/ 文件，且该文件 SHOULD 保持在 150–500 行的预算之内，通过将细节移入 docs/ 并加以链接，而非无限制地增长。
  2. CLAUDE.md 解析到 AGENTS.md。 MUST 存在一个 CLAUDE.md 并解析到 AGENTS.md（一个符号链接，或保证单一事实来源的等价方式）。两者 MUST NOT 相互背离。
  3. 一套 docs/ 层级结构。 仓库 MUST 包含一个 docs/ 目录，涵盖标准的各类别（架构、规范、测试、开发命令、安全与代理接入），并具备真实、仓库专属的内容。复杂模块 SHOULD 携带各自的 README.md。测试指南 MUST 定义一套真实的测试、lint 与类型检查工具链——或者，对于一个完全没有这类工具链的仓库，定义一套在接入期间从其技术栈提议而来的具体方案。一份空白的测试指南或“无测试”都不满足这项标准：在没有一种已定义的方式来验证行为的情况下，一份计划就没有客观的验证关卡。
  4. 一个 .agents/ 目录。 仓库 MUST 包含一个 .agents/ 目录，含 agents/、commands/ 与 skills/，外加 .agents/docs/ 之下一份与磁盘上一致的目录。dwp-* 命令 MUST 是委派给已安装技能的轻量委派器。一个 .claude 路径 MUST 解析到 .agents。
  5. 一个被 gitignore 的 .dwp/ 工作区。 仓库 MUST 包含一个含 plans/ 的 .dwp/ 目录，且 .dwp/ MUST 被 gitignore。一个 tmp/ 草稿空间 SHOULD 存在，并 SHOULD 被 gitignore。
  6. 方法论技能可被解析。 Deep Work Plan 技能 MUST 被安装或被引用，使得仓库中的代理能够调用其各子技能。

一个仓库在零可选附加组件下即完全符合规范。可选附加组件（devcontainer、Dailybot、dependency-upgrade、design-system）MUST NOT 作为符合性的必要条件。自标准 2.3.0 起，AI Diff Reviewer 本地审查（vendored skill + 扩展文件）属于基线的一部分：对声明 2.3.0 或更新版本的仓库，它的缺失是一项失败；对旧版仓库则是一项 harness 版本发现。其 CI 层面保持可选。

一份结构良好的计划

.dwp/plans/ 中的一份 Deep Work Plan 在满足以下条件时即为结构良好：

  1. 每项任务 MUST 声明一个明确的范围、验收标准，以及至少一个验证关卡（一个客观地非通过即失败的命令或核查）。
  2. 每项新增核心功能或改变产品行为的任务 MUST 在其验收标准中包含针对该行为的自动化测试覆盖，并 MUST 在其验证关卡中将代码仓库的测试与其 lint 及类型检查一并运行——而不仅仅是构建。现有测试 MUST 保持通过；行为变更 MUST 更新它所破坏的测试，而非删除或跳过它。纯文档、配置或研究类任务无需创建测试，但仍要运行代码仓库的关卡。
  3. 每项涉及身份验证、输入处理、机密或配置、网络暴露面或依赖项的任务 MUST 在其验收标准中承载该变更的安全期望，且每次提交 MUST 不含任何机密材料。
  4. 计划 MUST 持久化进展，使工作能在中断中存续，并能被另一个代理恢复。一项任务 MUST NOT 在其任何验证关卡记录仍显示失败且未解决的运行时被记录为 completed，且一项任务自身的完成日志 MUST NOT 与其记录的状态相矛盾（例如，一项 completed 任务若其日志仍写着「Status: pending」，即为一项缺陷，而非一次通过）。
  5. 计划 MUST 以其记录在案的最终审查收尾。在本版本下编写的计划 MUST 恰好以唯一的强制 Final Review 作结——安全审查、最终状态验证与技能决策核对。在更早版本下编写的计划以三项强制收尾任务（Security Review、Skills & Agents Discovery、Executive Report）作结，且仍然符合规范。一项严重的安全发现会阻止完成，直至被修复或被明确接受。完成本身是一次经验证、可恢复的事务，而非一次简单的状态翻转：终结任务通过一个受保护的发布步骤关闭，该步骤会在写入状态之前验证已完成计划的产物，并留下一份机器可核验的 FINALIZATION.json 收据；一次被中断的发布会依据证据被恢复，绝不会被静默地重新宣告为已完成。一条关卡记录所引用的任何证据指针 MUST 能够在计划自身的文件夹内解析——一个悬空或逃逸的指针是一项发现，而非通过证据。
  6. 任务 SHOULD 在执行之前重新锚定到计划的目标，以防止在长周期中发生漂移。

验证符合性

符合性 SHOULD 以机械方式验证，而非靠人工检查。运行 /dwp-verify 会针对上述标准生成一份通过/未通过报告：AGENTS.md 的存在与真实内容、CLAUDE.md 的解析、docs/ 的各类别、.agents/ 目录与磁盘的一致性、.dwp/ 与 tmp/ 的 gitignore 状态，以及——对一份计划而言——每项任务都带有验收标准与验证关卡，对改变行为的任务带有测试覆盖，且记录在案的最终审查已就位。对于一份计划，它还会核查计划的 Markdown 与其机器可读状态是否一致（README 与 state.json 去同步是一项发现，绝非静默通过），已完成的任务是否携带无矛盾的关卡与日志证据，以及——当一份已完成的计划推进到那一步时——是否有一份发布收据支撑它所声明的完成。检查器是版本感知的：它 MUST 接受一份旧版计划（三项强制收尾任务、无触及面）为符合规范，并 MUST 拒绝一份声明本版本、却在本版本下客观无效的计划。它还会将缺失或过期的 DWP standard: 溯源行报告为一项指明目标 harness 升级的发现。 机械层对其局限保持诚实：在没有可用的解释器（Python 3.9+）时，它会以非零退出码和明确的 UNVERIFIED 结论结束，而不是跳过检查——检查器绝不报告它未曾验证的结果。

一个仓库 SHOULD 在接入之后、以及每份计划完成之后重新验证，使符合性得以持续维护，而非只声称一次。