implementation-plan-review

Name: implementation-plan-review
Author: validkeys

github.com/validkeys测试与质量193 次安装19 周前更新

代码仓库

关于 implementation-plan-review

implementation-plan-review 是用于检查生成的实施计划的技能，面向需要评估计划质量和开发就绪度的团队。它验证计划文件结构，并检查任务拆分、依赖、质量门槛及需求覆盖情况，生成 YAML 审查报告。

主要功能

01验证 YAML 结构与引用完整性
02按受众检查任务说明细节
03评估任务规模与拆分质量
04检查依赖关系和关键路径
05检查需求覆盖与常见缺口
06生成综合审查 YAML 报告

适用场景

01开发前检查里程碑和任务文件
02发现计划中的依赖或覆盖缺口
03评估任务是否适合分配与执行

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/validkeys/sherpy --skill implementation-plan-review

安装后在 Claude Code 中输入/implementation-plan-review确认已加载。

附带文件references/example.yamlreferences/output-spec.md

详细介绍

实施计划审查

此技能会依据既定最佳实践审查生成的实施计划，确保计划具备质量、完整性并已做好开发准备。

前置条件

已生成的 milestones.yaml 文件
相关的 milestone-m*.tasks.yaml 文件
可选：用于对齐检查的源 business-requirements.yaml 和 technical-requirements.yaml

审查流程

阶段 1：结构验证

加载并解析所有计划文件：

文件发现
- 定位 milestones.yaml
- 查找所有 milestone-m*.tasks.yaml 文件
- 验证所有引用的任务文件均存在
架构验证
- 验证 YAML 语法
- 检查必填字段是否存在
- 验证数据类型和格式
引用完整性
- 验证里程碑依赖项是否存在
- 验证任务依赖项是否存在
- 检查任务文件引用是否与里程碑匹配

阶段 2：最佳实践合规性

依据内置最佳实践进行审查。注意： 部分检查项会因目标受众不同而有所变化：

AI 受众： 预期包含完整的 TDD 检查清单、偏离策略和明确的分步说明
人类受众： 预期仅包含高层目标、约束和成功标准
混合受众： 预期包含适度详细的信息和关键指导要点

审查说明详细程度时，应相应调整预期。

目标受众验证

元数据包含 target_audience — milestones.yaml 中存在 meta.target_audience 字段
受众值有效 — 必须为以下值之一："ai"、"human"、"hybrid"
说明详细程度与受众匹配 — 检查示例任务以确认：
- AI：包含实施步骤、TDD 检查清单、明确约束和偏离策略
- 人类：仅包含目标、风格范例、关键要求和成功标准
- 混合：包含目标、风格范例、实施方法和验证指南
任务间保持一致 — 所有任务遵循相同的详细程度

任务摘要

存在 task_summaries 部分，且位于每个 milestone-m*.tasks.yaml 文件顶部
所有任务均有摘要（tasks 数组中的每个任务 ID 都有对应条目）
摘要简洁（20–300 个字符，通常为 1–2 句话）
使用通俗英语（不使用技术术语或实施细节）
使用主动语态（“创建 X”，而非“X 已创建”）
聚焦于内容和原因，而非方法
概览便于快速浏览 — 仅阅读摘要即可了解里程碑范围

风格范例

每个里程碑任务文件包含 2–3 个风格范例
使用具体文件路径（而非抽象描述）
提供具体行号
示例完整（适用时包含代码、测试和 README）
体现当前模式，符合最佳实践
描述清晰，说明所展示的模式

任务规模（参见 task-sizing.md）

每项任务至少 30 分钟（若更短，则记录理由）
大多数任务的最佳时长为 30–150 分钟
最长 150 分钟（2.5 小时）——更长的任务应拆分
文件范围有限（优先 1–3 个文件；超过 5 个文件需说明理由）
每项任务的交付成果明确
已定义验收测试

TDD 要求（仅限 AI 受众）

代码任务包含 TDD 检查清单 — 仅限 AI
明确采用测试优先的方法 — 仅限 AI
提供验证命令 — AI/混合：明确列出；人类：提供一般性指导
记录预期输出 — 仅限 AI
测试失败时禁止修改测试 — 仅限 AI

对于人类/混合受众，应验证成功标准中包含测试要求，但不要求提供规定性的 TDD 检查清单。

肯定式指令

明确列出允许的操作（例如，“仅使用：X、Y、Z”）— 仅限 AI/混合
约束清晰且可执行 — 所有受众

漂移防范（仅面向 AI）

任务说明中注明漂移策略——仅面向 AI
停止条件明确（意外依赖项、文件范围违规）——仅面向 AI
提供回退说明——仅面向 AI
指定事件记录流程——仅面向 AI
明确允许的偏差（格式、空白）——仅面向 AI

面向人类或混合受众时，仍应明确约束，但不应包含明确的漂移策略。

质量门禁

定义提交前钩子
为每项任务指定验证命令
成功标准可衡量
记录失败处理方式

提示词位置

将关键规格放在任务说明开头
在任务定义前部放置风格参考
在末尾重申硬性规则
不要将要求埋在中间

第 3 阶段：漂移策略合规性

根据内嵌的漂移策略进行检查：

停止与回退标准覆盖情况

检查任务是否包含以下指导：

检测新增依赖项——如何识别未经授权的依赖项
文件范围违规——触及超过 3 个意外文件时该怎么做
Lint 或类型错误——如何处理无法解决的错误
测试失败——关于修改测试还是修复实现的策略

即时操作说明

停止指令明确——使用“立即停止”的表述
错误消息格式——如何概述偏差
回退流程——何时以及如何回退
事件记录位置——记录位置（docs/drift-incidents/）

记录经验

提及规则更新流程
指明更新位置（.cursor/rules/、CLAUDE.md）

允许的偏差

轻微格式调整——明确可接受
空白字符编辑——允许，无需审核
单行重构——在范围内且已进行类型检查

第 4 阶段：任务规模分析

根据内嵌的任务规模指南进行检查：

时长合规性

生成报告：

task_sizing_report:
  total_tasks: [count]
  by_duration:
    too_small:  # < 30m
      - task_id: [id]
        estimate_minutes: [n]
        rationale: [why small]
        recommendation: [merge or accept]
    optimal:    # 30-150m
      count: [n]
      percentage: [%]
    too_large:  # > 150m
      - task_id: [id]
        estimate_minutes: [n]
        recommendation: [split into X, Y, Z]

文件范围分析

优先选择 1-3 个文件
对 超过 5 个文件的任务进行说明或拆分
每项任务都提供明确的文件列表
明确标注仅触及的文件

任务拆分质量

定义最小可用交付成果
为每项任务提供明确的验收测试
提供示例文件
制定每项任务完成后提交的策略

大型任务检测

找出需要拆分的任务：

decomposition_needed:
  - task_id: [id]
    current_estimate: [minutes]
    suggested_split:
      - name: [subtask 1]
        estimate: [minutes]
      - name: [subtask 2]
        estimate: [minutes]
      - name: [subtask 3]
        estimate: [minutes]

第 5 阶段：完整性检查

里程碑结构

任务拆分

任务质量

第 6 阶段：一致性检查

业务需求（如有提供）

所有功能需求都映射到任务
优先级与业务优先级一致
明确定义 MVP 范围
成功标准可用于验证业务目标

生成覆盖矩阵：

business_requirement_coverage:
  FR-1: [task-ids]
  FR-2: [task-ids]
  FR-3: [gap]  # Not covered

技术要求（如有提供）

生成覆盖矩阵：

technical_requirement_coverage:
  architecture:
    - decision: [description]
      enforced_in: [task-ids]
  technology:
    - choice: [description]
      enforced_in: [task-ids]

阶段 7：依赖分析

关键路径

生成依赖图：

dependency_analysis:
  critical_path:
    - [milestone-id]
    - [milestone-id]
  critical_path_duration: [time]
  
  parallel_opportunities:
    - can_parallelize: [[m1, m2], [m3, m4]]
      time_saved: [duration]
  
  dependency_issues:
    - task: [id]
      issue: [description]
      recommendation: [fix]

循环依赖检查

里程碑之间没有循环依赖
任务之间没有循环依赖
依赖图是有向无环图（DAG）

阶段 8：差距识别

常见差距

生成差距报告：

gaps:
  missing_task_types:
    - type: [infrastructure/tests/docs/etc]
      importance: [high/medium/low]
      recommendation: [description]
  
  missing_requirements_coverage:
    - requirement: [id]
      category: [functional/non-functional]
      impact: [high/medium/low]
  
  undocumented_assumptions:
    - task: [id]
      assumption: [description]
      recommendation: [document explicitly]

线框图覆盖（软性门槛）

如果任何任务引用 .tsx／.jsx／.vue／.svelte 文件，或提及 UI 组件（表单、表格、导航、模态框、页面、布局）：

是否存在 ux/wireframe-spec.yaml？
每个包含 UI 任务的页面是否都有对应的线框图条目？
线框图规范是否涵盖所有检测到的组件？
是否记录了关键交互的用户流程？

这是 WARN 级门槛（不是 CRIT）。 不会阻止后续推进。

如果线框图缺失或不完整，请在审核输出中添加：

wireframe_coverage:
  ui_tasks_detected: [count]
  wireframe_spec_exists: [true/false]
  missing_pages:
    - page: [name]
      tasks: [task-ids]
  recommendation: "Consider running Step 6 (UX/Wireframe Planning) before development"

用户将看到：

"WARN-001: 检测到 [n] 个 UI 任务，但没有线框图覆盖。建议在开发前运行步骤 6。仍要继续吗？（yes/no）"

阶段 9：风格参考验证

参考项指向现有文件（如有代码库）
行号准确（如可验证）
正确展示模式
描述有帮助
每种新模式都有足够的参考项
包含测试参考项
在适用情况下包含 README 参考项

阶段 10：质量门验证

已指定 Linter 命令——AI：明确指定，Human/Hybrid：一般性说明
已指定类型检查器命令——AI：明确指定，Human/Hybrid：一般性说明
已指定测试命令——AI：明确指定，Human/Hybrid：一般性说明
命令可执行（如有指定）
已定义预期输出——仅 AI
已记录失败处理方式——仅 AI

对于 Human/Hybrid 受众，请确认成功标准提到了运行测试、Lint 和类型检查，且不要求明确写出命令文本。

审核输出

生成完整的审核报告，保存为 implementation-plan-review.yaml。

输出文档包含：metadata（计划文件、审核日期）、overall_scores（结构、最佳实践、任务规模、完整性、对齐度、开发就绪度——各项 1–10 分）、critical_issues、high_priority_issues、medium_priority_issues、best_practices_violations（按类别）、gaps、strong_areas、optimization_opportunities、specific_recommendations 和 readiness_assessment。

完整的文档规范包含所有字段、问题 ID（CRIT-NNN/WARN-NNN/INFO-NNN）和评分标准，详见 references/output-spec.md。

完整示例请参阅 references/example.yaml。

用法

审核实施计划：

/implementation-plan-review path/to/milestones.yaml

该技能将：

加载所有里程碑和任务文件
验证结构和架构
检查是否符合所有最佳实践
分析任务规模和依赖关系
识别差距和问题
生成完整的审核报告
提供具体建议

输出文件

生成：

implementation-plan-review.yaml - 全面审查报告
task-sizing-analysis.yaml - 详细的任务规模分析
requirement-coverage.yaml - 需求与任务映射
dependency-graph.yaml - 里程碑和任务依赖关系

最佳实践参考

此技能直接融入并强制执行最佳实践：

1. 实施计划最佳实践

核心原则：

模型会进行局部优化；应通过分层验证（提示词 → IDE → 提交 → CI → 运行时）来强制执行全局约束。

关键实践：

风格范例： 始终将 2-3 个示范文件作为模板，注明准确的路径和行号。优先选择仓库中的具体范例（代码 + 测试 + README）。尽早强制采用这些范例，避免架构偏移。
任务规模： 将工作拆分为 30 分钟至 2.5 小时的原子任务（30–150 分钟为最佳范围）。将范围限定在特定文件。每完成一个小任务就提交。发生偏移时立即回退。如果任务短于 30 分钟，要么增加预估时长，要么说明理由后进一步拆分。
肯定式指令： 明确说明允许执行的操作（例如，“仅使用：X、Y、Z”）。避免采用否定式表述。
分层规则： 全局规则（用户偏好）、项目规则（持久保存于 CLAUDE.md 或 .cursor/rules/）、上下文感知规则（按目录/文件设置）。
以 TDD 为锚点： 实施前要求提供 TDD 检查清单（测试 → 最少代码 → 更多测试 → 重构）。测试失败时，返回失败输出并附上指令：“修改实现以通过此测试，同时保留所有先前通过的测试。不要修改测试。不要添加依赖项。”
偏移处理： 遇到意外依赖项或不熟悉的模式时，立即停止并回退。不要在过程中修复。记录经验，并在每次会话后更新持久规则。
提示词布局： 将关键规格、风格范例和硬性规则放在提示词开头，并在结尾重申（避免把要求埋在中间）。
外部数据验证： 切勿对外部数据使用类型断言。使用适当的错误处理和验证来检查所有外部输入。

IDE/代码检查：

强制执行严格的代码检查（go vet、golangci-lint、gofmt）
通过竞态检测运行测试
零警告政策

质量门禁：

提交前：运行 make lint 和 make test，确保没有警告
CI：统计违规数量，超出阈值时判定失败

2. 偏移政策

目的： 明确模型编辑偏离项目规则时，何时停止、回退并记录。

停止与回退标准：

模型引入了未列入允许技术栈的新依赖项
编辑涉及指定目标之外的文件（超过 3 个意外文件）
引入了无法在任务范围内解决的代码检查或类型错误
测试失败，且模型提议修改测试以通过

立即采取的行动：

停止模型会话并返回清晰的错误消息，总结偏差情况
将工作区恢复到任务开始前的状态（适当时使用 git）
在 docs/drift-incidents/ 中创建事件记录，说明：发生了什么、更改了哪些文件、新增了哪些依赖项、补救步骤

记录经验：

问题解决后，更新 .cursor/rules/ 或 CLAUDE.md，加入新规则以防止再次发生

允许的偏差：

轻微的格式更改（编辑器配置）或仅空白字符的编辑
在目标文件范围内且通过类型检查的单行重构

审查与批准：

任何回退或事件记录都必须由人工维护者审查后，才能重新运行

3. 任务规模指导

目的： 将面向模型的工作划分为可预测、便于审查的任务块，以减少偏离和意外扩大范围的情况。

指导原则：

目标任务时长：30 分钟至 2.5 小时
尽可能将修改限制在 1-3 个文件内
如果请求的修改涉及超过 5 个文件或需要超过 2.5 小时，则拆分为更小的任务

流程：

明确最小且有用的交付成果，以及清晰的验收测试
提供示例文件和要修改的确切路径
每完成一项任务后，运行测试并使用清晰的说明提交

拆分大型任务：

拆分为：（a）测试 + 脚手架，（b）最小实现，（c）重构与润色
创建计划说明，列出子任务和验收标准

示例：

小型：修复 src/utils/parse.ts 中的一个 Bug — 30-60 分钟
中型：添加新的 API 端点 src/server/user.ts 并编写测试 — 1-2.5 小时
大型：迁移身份验证系统 — 拆分为设计 + 增量 PR

决策支持

审查后，提供建议：

如果发现关键问题

“我发现了 [n] 个阻碍开发的关键问题：

[关键问题 1]

[关键问题 2]

建议： 在开始开发前修复这些问题。

你希望：

现在修复问题（我会重新生成受影响的任务）

手动审查问题

了解情况后继续（不推荐）”

如果发现高优先级问题

“我发现了 [n] 个应当处理的高优先级问题：

[问题 1]

[问题 2]

建议： 在开发前或里程碑 0 早期处理这些问题。

你希望：

现在处理（我会更新计划）

记录下来，留待里程碑 0 处理

继续进行，之后酌情处理”

如果修改后即可就绪

“计划基本就绪，建议进行 [n] 项改进。

优势：

[规划完善之处]

建议改进：

[改进 1]

[改进 2]

对时间线的影响： [估算]

你希望：

现在应用改进

记录下来，实施时再处理

按当前方案开始开发”

如果已做好开发准备

“实施计划已做好开发准备！

优势：

[出色之处]

[遵循的最佳实践]

小幅优化机会：

[机会 1]

[机会 2]

预计时间线： [时长] 关键路径： [时长]

你可以放心开始开发。”

集成

此技能与以下内容集成：

implementation-planner - 审查此技能生成的计划
business-requirements-interview - 验证与业务需求的一致性
technical-requirements-interview - 验证技术规范的覆盖情况

示例

完整的审查输出示例请参见 references/example.yaml。

支持 Markdown

登录后评论

基本信息

作者: validkeys
仓库: validkeys/sherpy
分类: 测试与质量
安装次数: 93
GitHub Stars: 1

报告问题