anian0/plan-execution

计划执行

按实施计划逐个执行模块，通过 subagent 连续实现模块内子步骤，模块边界审核确保质量。 默认范围只做模块级单元/集成测试，不做端到端测试。

<HARD-GATE> - 实施计划必须存在；无计划则先调用 implementation-planning - 计划文件路径：`workplace/1.X/plan/`（X 为当前活跃版本数字），计划为**目录结构**，含 `index.md` 和各模块文件 `M{N}-xxx.md` - **所有新增测试文件必须落到 `workplace/1.X/test/` 下对应子目录**（backend/unit、backend/integration、frontend/unit、frontend/component、review、fixtures），不得放在源码旁 - 执行过程中**不提交 git** </HARD-GATE>

版本号约定

1.X 为占位符，详见 requirements-workshop/SKILL.md。真实路径必须替换为具体数字（如 workplace/1/plan/）。

测试目录规范（强制）

workplace/1.X/test/
├── backend/
│   ├── unit/<module>/         # 后端单元测试（核心）
│   └── integration/<module>/  # 后端集成测试（仅关键路径）
├── frontend/
│   ├── unit/<page-or-store>/  # 前端单元测试
│   └── component/<component>/ # 前端组件测试
├── review/                    # 前端审查清单（subagent 逐项检查）
├── fixtures/                  # 共享测试数据
└── README.md                  # 运行命令矩阵 + 覆盖率目标

约束：

• 委派 implementer subagent 时，必须把"测试文件应落入的具体子目录"写进 prompt
• 模块审核 subagent 必须检查测试文件位置合规
• 如果 workplace/1.X/test/ 不存在，第一个被执行的模块负责创建该骨架（含 README.md）
• 本套 skill 不做端到端测试，因此测试目录中不应出现 e2e/

为什么用 Subagent

每个模块委托给有隔离上下文的专用 agent，确保聚焦并成功完成。他们不继承你的会话上下文——你构建他们确切需要的内容，同时保护你的上下文用于协调。

模块状态管理

模块状态以 index.md 中的状态列为准，不依赖内存（会话中断即丢失）。

| 时机 | 操作 | |------|------| | 开始执行某模块前 | 在 index.md 执行索引表中状态改为 执行中，保存 | | 模块通过审核后 | 状态改为 完成，保存 index.md | | 用户决定不做某模块 | 改为 跳过，在 index.md 该模块行末加跳过原因；若下游依赖被跳过模块的输出，先与用户确认替代方案再继续 | | 会话中断后恢复 | 读 index.md，找第一个 待执行 或 执行中 模块继续；遇 跳过 直接越过，但需检查下游依赖是否仍可执行 |

初始化：读取交接信息 + 计划理解确认

从交接清单获取计划目录路径、需求文档路径、技术方案路径。

只读 index.md（不读任何模块文件），获取执行索引后，向用户确认理解：

我已读取任务清单，理解如下：

计划文件：workplace/1.X/plan/YYYY-MM-DD-xxx/（目录） 模块数量：N个（列出编号和名称） 功能点总数：K个（列出FP编号） 后端脚本测试点：X个（列出TC编号） 前端审查测试点：Y个（列出TC编号） 特别关注点：[从计划文件提取]

执行顺序：[模块执行顺序摘要]

请确认是否开始执行？

等待用户确认后才进入执行循环。若用户提出调整，处理后再重新确认。

按需加载原则

计划文档是目录结构（index.md + 各模块文件），利用文件边界天然隔离上下文：

• 初始化：只读 index.md，获取模块数量、顺序、状态
• 执行每个模块前：只读对应的 M{N}-xxx.md 文件（index.md 的"模块文件"列有文件名），该文件完全自含
• 禁止：在执行某模块时读取其他模块文件（除非审核需要相邻模块接口摘要，且该摘要已在当前模块文件中内含）
• 1.X 替换（强制）：传递模块文件内容给任何 subagent 之前，必须将所有 1.X 占位符替换为当前活跃版本号。计划文档由 implementation-planning 编写时会保留 1.X，但 implementer 遇到字面 1.X 会停止并询问——由你在传入前完成替换，包括验收脚本内容中的路径

执行流程（精简）

读取交接信息 → 确认计划理解
       ↓
读取 index.md → 选下一个待执行模块
       ↓
更新状态=执行中 → 读取当前模块文件 → 委派实现 subagent (implementer-prompt.md)
       ↓
subagent 提问？→ 是：回答上下文 → 重新委派
              → 否：subagent 连续实现+自检+模块测试
       ↓
委派模块审核 subagent (module-reviewer-prompt.md)
       ↓
审核通过？→ 否：让实现 subagent 修复 → 重新审核
        → 是：更新状态=完成
       ↓
还有模块？→ 是：循环
        → 否：委派最终审核 subagent (final-reviewer-prompt.md) 做集成核对
              （仅做跨模块集成与验收标准核对，不做端到端测试）
       ↓
最终审核通过？→ 否：按"最终审核失败处理"修复 → 重新审核
            → 是：完成收尾

模型选择

用足够完成模块的最弱模型以节省成本和时间。

| 模块类型 | 推荐模型 | |----------|----------| | 机械实现（重复性 CRUD） | 最快最便宜 | | 集成判断（多文件协调） | 标准 | | 模块审核 | 最强（需判断力） | | 最终集成核对 | 标准 |

禁止事项

绝不：

• 并行委派多个实现 subagent（会冲突）
• 让 subagent 自己读取计划目录中的其他文件（由你只传当前模块文件内容）
• 在执行某模块时读取其他模块文件（除非审核需要相邻接口摘要，且该摘要已在当前模块文件中内含）
• 忽略 subagent 提问（回答后再继续）
• 让 subagent 自检替代实际审核
• 接受"差不多符合"（审核未通过即未通过）
• 在没有为前端模块准备前端测试（单元/组件至少一类）的情况下声明前端模块完成
• 接受含有降级逻辑的实现：若模块审核发现降级逻辑（静默fallback、功能缩水、mock侵入生产路径、错误掩盖），必须要求实现 subagent 修复，不得以"功能大体可用"为由放行

模块审核维度

模块审核器一次审核六件事：

1. 功能点覆盖（是否做了该做的）

• 对照模块的"对应功能点"列表，逐项验证是否实现
• 子步骤完成度（是/否/部分）
• 缺失的要求（声称工作但未实现）
• 额外/不需要的工作（YAGNI）

2. 验收执行（验收是否实际通过）

• 后端模块：实际运行验收 py 脚本，检查是否 ALL PASS
• 前端模块：按审查清单逐项验证，检查是否全部勾选
• 不相信实现者的报告，独立验证

3. 代码质量（是否做得好）

• 文件单一职责
• 关键接口命名清晰
• 遵循代码库现有模式
• 不逐行审查、不纠结格式（交给 linter）

4. 模块边界（接口是否正确）

• 输入：是否正确消费前置模块的接口/数据
• 输出：是否符合契约
• 数据格式、字段名、类型一致

5. 测试目录合规

• 所有新增测试文件位于 workplace/1.X/test/ 下
• 源码目录无残留 .test. / .spec. / test_*.py
• 后端单元在 backend/unit/<module>、集成在 backend/integration/<module>；前端单元在 frontend/unit/<page-or-store>、组件在 frontend/component/<component>；前端审查清单在 review/
• 未出现 e2e/ 目录或端到端测试文件（出现即不通过，提醒移除）
• 前端模块至少包含单元/组件测试中的一类
• 测试命令可执行

6. 特别关注点合规

• 计划文档"特别关注点"中与该模块相关的关注项是否已落实
• 每个相关关注点是否有对应的实现或测试验证

审核传入：模块文件全部内容（已自含目标、功能点、测试点、子步骤、接口契约、相邻模块接口摘要、特别关注点、验收标准）+ 实现者报告 + 本目录规范。

测试失败修复流程

模块测试失败时：

1. 主控 agent 不修改代码，把失败摘要（命令、失败用例、错误日志）反馈给同一实现 subagent
2. 委派该 subagent 仅修复测试失败相关的代码与测试
3. 修复完成后再次运行模块测试命令
4. 三次仍未通过 → 停止并向用户报告：当前情况、已尝试的修复、推测根因 → 由用户决定继续修、跳过还是回设计阶段
5. 测试通过后无需重新做模块审核（除非修复涉及接口/架构变更，由主控判断）

最终审核（不做端到端测试）

所有模块完成后，委派最终审核 subagent（references/final-reviewer-prompt.md）做集成核对：

获取传入信息：

1. 从 index.md 顶部读取"需求文档"和"技术方案"路径
2. 读取需求文档，提取功能清单和测试关注标记
3. 读取技术方案文档，提取功能点清单（FP-N）和测试点清单（TC-N）
4. 从 index.md 复制执行索引表
5. 从 index.md 复制特别关注点章节

传入信息：

• 需求文档功能点清单（功能列表 + [后端]/[前端] 测试关注标记）
• 技术方案的功能点清单（FP-N）和测试点清单（TC-N）
• index.md 的执行索引表（含模块→功能点→测试点映射）和功能点-模块映射表
• index.md 中的特别关注点（用户强调的约束、风险、偏好）

核对内容：

• 验收标准覆盖核查（需求文档每条验收 → 是否有模块覆盖）
• 模块间接口/数据格式一致性
• 横切关注点（错误处理、边界、用户反馈）是否完整
• 前端页面清单是否全部已实现
• 测试套件完整性（backend/unit、backend/integration、frontend/unit、frontend/component、review、fixtures、README）
• 特别关注点合规（计划文档中的用户强调项是否在实现中落实）

不做：实际跑端到端用例、模拟完整用户路径——这些不在本套默认范围内。

最终审核失败处理

最终审核发现问题时的处理流程：

1. 分类问题：将最终审核发现的问题按影响范围分为——
   • 单模块问题：仅影响某个模块的验收或功能点（如遗漏的验收项）
   • 跨模块问题：涉及模块间接口不一致或全局性遗漏（如前端字段与后端不匹配）
2. 单模块问题：让对应模块的实现 subagent 修复，修复后重新运行该模块验收脚本，无需重新做模块审核
3. 跨模块问题：与用户讨论修复方案，确定影响范围后再派发修复；若修复涉及接口变更，需重新审核受影响的模块
4. 重新审核：修复完成后重新委派最终审核 subagent
5. 三次仍未通过：停止并向用户报告当前情况、已尝试的修复、推测根因，由用户决定下一步

完成收尾

最终审核通过后，产出执行总结并更新计划文件：

所有模块已完成并通过审核。执行总结：

• 计划文件：workplace/1.X/plan/YYYY-MM-DD-xxx/（目录）
• 模块完成：N/M（跳过K个，列出编号及原因）
• 功能点覆盖：已执行模块的 FP 全部验收通过（跳过模块的 FP 列入遗留事项）
• 测试结果：后端脚本 X 个 ALL PASS，前端审查 Y 个全部通过
• 遗留事项：[如有跳过模块或待办，列出]

后续：如需部署、上线验证或处理跳过模块，由用户决定下一步行动。

提示词模板

委派 subagent 前，读取对应模板文件，替换占位符后作为 prompt 传入。

• references/implementer-prompt.md - 委派模块实现 subagent（按模板中的 {...} 占位符说明，传入当前模块文件的完整内容）
• references/module-reviewer-prompt.md - 委派模块审核 subagent（按模板中的 {...} 占位符说明，传入模块文件完整内容 + 实现者报告）
• references/final-reviewer-prompt.md - 委派最终审核 subagent（按模板中的 {...} 占位符说明，传入 index.md 内容 + 需求/技术方案信息）

示例工作流

你：执行计划。

[读取 index.md，确认 6 个模块及顺序]

模块 M1：数据库迁移与模型
[读取 M1-数据库迁移与模型.md，index.md 状态改"执行中"]
[委派 implementer，传入 M1 模块文件内容]

实现者："开始前 - 数据库连接配置在哪里？"
你："见技术方案 §1.2"
实现者：[实现] → 报告 DONE

[委派 module-reviewer，传入 M1 模块文件内容 + 实现者报告]
审核：✅ 通过

[执行 M1 测试命令]
测试通过 → index.md 中 M1 状态改"完成"

模块 M2：业务服务层
[只读取 M2-xxx.md，不读 M1 或 M3 文件]
... (同上)

[所有模块完成]
[委派 final-reviewer 做集成核对（传入 index.md 内容 + 需求/技术方案，不跑 E2E）]
最终审核：✅ 验收标准全部覆盖，集成无问题

完成！

关联 skill

| Skill | 关系 | |-------|------| | implementation-planning | 创建本 skill 执行的模块计划 | | tech-design | 模块引用的技术方案来源 | | requirements-workshop | 技术方案引用的需求来源 | | issue-troubleshooting | 大修修复计划经 implementation-planning 生成后，由本 skill 按模块执行 |