plan-it 是做什么的？
将模糊的需求 → 交付一个可构建的交付包。 这是规划
指挥者：生命周期的纪律性前半部分，精确止于 /build-it
开始之处。它完成 发现（研究真实情况）、规范
（编写设计文档）和 敏捷拆分（PRD、史诗、测试、共享
合约）——然后移交。
/plan-it ─────────────► docs/ + delivery/ ─────────────► /build-it
(发现 → 规范 → 计划) (可构建的交付包) (构建它)
可由人类直接使用，也可由任何接收新需求并将其转化为交付包后再调度工作线程的编排型 指挥者 代理使用。
五条不可协商的规则（强制执行这些规则——而不仅仅是建议）
这些是从每次成功运行中逆向工程得出的承重规则。 如果违反其中一条，下游构建会偏移或静默失败。
-
在任何并行规划之前冻结一个共享的 CONTRACT。 CONTRACT 是 法则：规范实体、模式、API/接口、枚举、仓库/分支映射，以及 “已发布”的定义。团队根据它编写；任何跨领域的发现都 会折叠回它，作为带日期的修订版本（v1.0 → v1.1 …）。没有冻结的合约 → 没有 并行团队。
-
将每个仅由人类做出的决策批处理到一个门控中。 不要预先决定任何事情 不可逆的事（仓库拓扑、托管、产品名称、架构模式、自建 vs. 购买）。 将它们一起呈现，每个都附上建议， 让人类按编号回答。这个门控是人类注入愿景的地方，而不仅仅是挑选 选项——留出空间让他们添加你未提出的概念。用 所有者 + 日期锁定每个答案。
-
验证每个代理在磁盘上的输出——“空闲 ≠ 已交付。” 团队进入空闲状态 并不意味着它写入了文件。在任意扇出之后，在实际继续之前检查路径是否存在且非空。 如果一个团队将其输出作为消息保存，则指示它
Write到明确 的绝对路径。永远不要相信“完成”。 -
在冻结之前，根据线上系统而非仓库来验证计划。 对于任何涉及正在运行的系统的计划， 仓库是一个假设；已部署的现实才是真理，并且两者会偏离。 在冻结 CONTRACT 之前，根据实际系统进行验证，并将观察结果写入 （而非仓库派生的猜测）。 经过实战检验：在一个项目中，每一次中途修正都追溯到某个仓库推断出的 被现实矛盾的假设——错误的规范标识符（清单已偏离已部署的目录）， 一个存在但指向死主机的配置值，“待构建”但已部署的组件， 以及一个被发现是错误的凭据。 请参阅阶段 3 的在线验证门控以了解具体检查项。
-
运行机器，而不是文字。 管道的控制流存在于
machine.json（明确的状态图）中，而不是本文档中——这段文字 解释机器。调用时，读取或初始化.plan-it/state.json（在目标项目中）并从其state恢复；在每次 转换时写入它。在每次有守卫的转换时，运行守卫映射的子命令 （node scripts/gate-check.mjs <check> …），并且在非零退出时绝不推进 ——修复、重新运行，然后转换。如果 Node 不可用，手动执行同样的检查 并将它们记录在状态文件中（降级，永不中断）。完整 协议：references/machine.md。
确定性核心 (v2) — 为什么需要机器
以文字形式编写的控制流（“执行步骤 1，绝不跳过门控”）在确定性 文献中被称为散文式控制流：它依赖于模型在长且容易丢失摘要的上下文中的纪律， 有时模型不会遵循它。v2 在适当的高度反转了这一点——边界处非确定性， 核心处确定性：
machine.json— 管道的 XState v5 兼容状态图：15 个状态， 三个人类门控（meta.gate+meta.human），有守卫的转换，以及一个parallelPlanning上的AMENDMENT自循环。粘贴到 stately.ai/viz 即可查看。.plan-it/state.json— 持久化的运行：当前状态、门控批准 （所有者 + 日期）、合约版本、已验证的工件注册表、历史记录。这就是使 运行能够从崩溃或新会话中恢复的关键。scripts/gate-check.mjs— 作为退出码的守卫：verify（规则 3， 空闲 ≠ 已交付），freeze（规则 1，无合约 → 无团队），handoff（ 剧本 §F 中可机械化的部分），state（规则 2，已记录门控），adversary（规则 6 / D4 — 故障模式深度：建模的机器必须覆盖或豁免 五类级联；线性工作流不适用）。LINT_CLEAN和ADVERSARY_CLEAN转换（verify → adversaryGate → handoff）以后两个为依据。
模糊阶段——发现、综合、规范编写、判断——
保持在 LLM-at-the-node（在机器中标记为 llmAtTheNode）。不要将它们形式化；
建模只有在能消除混淆时才不是仪式。详细信息、状态文件模式
和恢复协议：references/machine.md。
硬性执行 (v2.1，仅适用于 Claude Code 的插件安装)： 一个 PreToolUse
钩子（scripts/hooks/planit-guard.mjs）在运行合约未冻结时，拒绝对 PRD/史诗
交付物执行 Write/Edit 调用——规则 1 不再是一个指令，而是变成了工具链拒绝的东西。
故障开放：它从不触及非 plan-it 的工作。纯技能安装则依赖规则 5 的约束。
测试合约 — 质量区分器（使其不可协商）
唯一最能提高交付代码质量的措施：每个 PRD/史诗都以生成其自身的测试合约结束——
多达约 20 个具体的用例/场景来对实现进行压力测试——并且该功能在 100% 通过之前
不算是“完成”。 构建代理不能只交付功能；它必须满足合约，并通过
/iterate 直到通过。
这是一个有名称的、经过验证的规程：实例化规范 (Gojko Adzic) + ATDD/BDD 用于代码（具体示例成为可执行的验收测试和活文档），以及 Eval-Driven Development 用于技能/LLM 功能（注册具有预期输出的黄金标准，迭代直到通过）。 在规划阶段编写这些用例是全部意义所在——它们成为了有约束力的合约， 而不是事后的想法。
测试合约的规则：
- 在规划阶段编写 — 编写每个史诗/PRD 的最后一步就是编写其测试合约。 预期输出现在注册（“先设计；注册预期输出”），而不是在构建过程中发现。
- 每个功能最多约 20 个高质量的用例 — 足以覆盖真实行为 + 边缘情况；不是成千上万个浅层用例（质量 > 数量——自动批量生成 = “垃圾”， 根据评估文献）。用例来源于真实/可能的故障模式。 每种形态的计数规则： 大型形态-1 多团队项目保持每个史诗至少 10 个用例的下限（每个史诗是一个大型功能）；小型形态（单 技能/功能，S/M）整个包总计编写约 20 个用例（每个史诗少量）。 切勿同时应用两者——根据形态选择，以免审查者将一个正确的 小型包标记为测试不足。
- 具有约束力 — 完成定义 = 合约 100% 通过；在此之前，执行
/iterate。无 部分交付；无基于模拟的验证（一个[REAL]用例其目标不可达 → 已实现未验证， 永远不是虚假的绿色）。 - 根据实现选择测试类型（以下之一或多项：单元 / 端到端 / 用例 / 压力）：
| 实现 | 测试类型 | 方式 |
|---|---|---|
| CRUD / REST API | 用例（快乐路径+边缘）+ 端到端 | 通过 API 及 通过 UI 使用 Chrome CDP（chrome-cdp-control）运行每个场景；对逻辑进行单元测试 |
| 技能 / 提示 / LLM 函数 | 带有预期输出的用例 | 运行它，比较真实输出与期望输出 — 封闭输出精确匹配，开放输出使用评分标准 / LLM-as-judge（make-eval，promptfoo，DeepEval G-Eval） |
| 代理 / 有状态 / 多步骤 | 压力场景 + 用例 | 六个维度：异步、扇出、升级、人工门控、递归、循环保护（Setup/Expected/Pass） |
| 纯逻辑 / 库 | 单元 + 基于属性 | 枚举用例 + 不变量 |
| 数据管道 / 迁移 | 黄金值 + 端到端 | 手工计算的期望值；幂等性/回滚 |
| 任何有负载/滥用面的东西 | 压力 / 对抗性 | 并发、速率、畸形输入、红队 |
- 执行路径：
/full-qa运行合约，/iterate循环到 100%，chrome-cdp-control驱动 UI 场景。合约是从 plan-it 到 build-it 的桥梁：/build-it的完成定义 = 此合约。
语法和合约头格式：references/formats.md（测试合约块 + §4–5）。
自主性姿态（在自主爆发中引导）
以高努力度自动运行研究和编写，但在三个门控处停止：
| 门控 | 何时 | 你问什么 |
|---|---|---|
| G1 — 范围 | 接收后（阶段 2） | 在投入精力之前确认规模（功能 vs 项目）+ 编号的完成定义 |
| G2 — 决策 | 规范起草后（阶段 7） | 批量“只有你能做出的决策”，每个都附有建议 |
| G3 — 交付 | 在敏捷拆分之前（阶段 8） | “规范看起来一致——继续进行 PRD/史诗？” |
门控之间的所有内容无人值守运行。建议在一开始使用 /effort xhigh
（你不能自己设置——告诉用户如果尚未设置则运行 /effort xhigh）。
阶段 0 — 接收
机器优先（规则 5）： 如果 .plan-it/state.json 存在于目标项目中，
运行 node scripts/gate-check.mjs state .plan-it/state.json 并从打印的
状态恢复——不要重新启动已在 history 中的阶段。如果它不存在，
现在在状态 intake 下创建它（模式在 references/machine.md 中），并在随后的每次转换中保持更新。
以其到达的任何形式接受需求：脑暴、粘贴的
转录稿、需求列表或一句话。期望指针，而不是内容——
会话名称（/read-chat "<name>"）、仓库路径、文档文件夹。你的工作是去
获取真相，而不是被递交到手上。
预先捕获：
- 原始愿景：使用用户自己的话（你将在
02 §1中引用它）。 - 指针：指向先前的会话/仓库/文档以进行研究。
- 用例（自动检测——这决定了 G1 门控处的打包形态）：
- 新的单应用，绿地 · 大型现有仓库上的功能 · 从零开始的多个子系统程序 · 多应用平台（多个 PRD）· 重构/迁移/技术债 · 研究性探索（尚未构建）· PM/看板 自动化 · 记录/审计已构建的系统。
- 研究方法：默认使用并行 Claude 团队，xhigh 努力等级。
如果需求确实是一个模糊的段落，没有指针且存在现有仓库， 那也没问题——预验证（阶段 3）将找到目标。
阶段 1 — 完成定义锁定
将模糊的散文式表述重组为一个编号的、可单独验证的完成定义
- 一个简短的已声明假设列表。这是你与用户就规划工作本身签订的合约。示例如下：
本次规划运行的完成定义：
1. 真相发现文档（每个声明 → 路径:行号或表格）
2. 解决每个发现/矛盾的愿景 + 架构文档
3. 数据/接口合约
4. …（自动确定大小——见阶段 2）
N. 移交：合约已冻结，PRD+史诗每个至少 10 个测试，启动提示
假设：<列表>
阶段 2 — 范围与形态调节器 ⏸ 门控 G1
在投入精力之前，选择大小（做多少）和 形态（什么形式）。 与用户确认两者。
大小缩放工件数量：
| 信号 | 大小 |
|---|---|
| 单一功能，1 个子系统 | S |
| 多功能 / 新子系统，1–2 个仓库 | M |
| 从零开始的程序 / 许多子系统 | L |
形态根据用例选择（完整定义 + references/templates.md PART D 中的用例→形态表）：
- 多文档 +
delivery/（基线）——从零开始的程序，并行团队。 - 单文件 PRD 即一切——绿地单应用；CONTRACT 内联为 G 规则。
- 研究 → 锁定架构 → 主 PRD + 阶段 PRD——大型现有仓库上的功能。
implementation/<name>/带编号的 PRD-NN——多应用平台，多个 PRD。- 重构/技术债工作流目录——原地进行遗留改造。 （+ 研究性探索、可执行看板和逆向文档模式——见 PART D。）
阶段相同——只有工件数量和形式改变。不要为一个功能配备 4 团队的组织；不要为一个遗留改造项目编写绿地愿景文档。
在继续之前，呈现所选的规模 + 形态 + 编号的完成定义并获得确认。
确认后，在 .plan-it/state.json 中记录 G1 = {已批准, 所有者, 日期} 以及所选的规模/形态——
G1_APPROVED 转换受 gateRecorded 守卫。
阶段 3 — 预验证
在任何扇出之前，定位精确目标，以便代理获得精确路径，而不是模糊的指令：
- 使用会话读取技能解析指针会话（如果已安装，使用
/read-chat或类似方法）； 否则请求相关的转录稿或摘要。 - 对命名仓库执行
ls/grep；找到docs/、模式文件、入口点。 - 如果仓库已连接 wiki（根据其
CLAUDE.md），读取 wiki 热缓存/索引。
输出：一个 {子系统 → 要读取的精确路径} 列表，用于孵化研究团队。
在线验证门控（规则 4）——当计划涉及正在运行的系统时
仓库告诉你应该是什么；线上系统告诉你实际是什么。在阶段 8 冻结之前执行此操作， 并将发现作为观察到的事实写入 CONTRACT：
- 配置可达性，而不仅仅是存在性。 对于计划依赖的每个环境/配置杠杆 （基础 URL、API 主机、功能标志），实际访问它——不要只确认它已设置。一个值 可以被设置为一个死主机，通过“是否存在”检查，同时静默破坏生产环境。
- 线上注册表 / 规范标识符。 构建
…
[为翻译进行了截断]
<|The original content was truncated, but I have translated what was provided.|>