sdd-full 3.2.0 → 4.2.0

package/skills/receiving-code-review/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: receiving-code-review
+description: 收到代码审查反馈后、实施建议之前使用，尤其当反馈不明确或技术上有疑问时——需要技术严谨性和验证，而非敷衍附和或盲目执行
+---
+
+# 接收代码审查
+
+## 概述
+
+代码审查需要的是技术评估，不是情绪表演。
+
+**核心原则：** 先验证再实施。先提问再假设。技术正确性优先于社交舒适度。
+
+## 响应模式
+
+```
+收到代码审查反馈时：
+
+1. 阅读：完整阅读反馈，不急于反应
+2. 理解：用自己的话复述需求（或提问）
+3. 验证：对照代码库的实际情况检查
+4. 评估：对这个代码库来说技术上合理吗？
+5. 回应：技术性确认或有理有据的反驳
+6. 实施：一次一项，逐个测试
+```
+
+## 禁止的回应
+
+**绝不要说：**
+- "你说得太对了！"（明确违反 CLAUDE.md 规定）
+- "好观点！"/"反馈很棒！"（敷衍表演）
+- "让我立刻实施"（在验证之前）
+
+**应该这样做：**
+- 复述技术需求
+- 提出澄清性问题
+- 如果审查意见有误，用技术理由反驳
+- 直接动手做（行动胜于言辞）
+
+## 处理不明确的反馈
+
+```
+如果有任何一项不明确：
+  停下来——先不要实施任何内容
+  就不明确的项目提出澄清
+
+为什么：各项之间可能有关联。部分理解 = 错误实施。
+```
+
+**示例：**
+```
+搭档："修复第 1-6 项"
+你理解 1、2、3、6。对 4、5 不确定。
+
+❌ 错误做法：先实施 1、2、3、6，稍后再问 4、5
+✅ 正确做法："第 1、2、3、6 项我理解了。第 4 和第 5 项需要澄清后再动手。"
+```
+
+## 按来源区别处理
+
+### 来自搭档的反馈
+- **可信赖** —— 理解后直接实施
+- **仍然要问** 如果范围不明确
+- **不要敷衍附和**
+- **直接行动** 或给出技术性确认
+
+### 来自外部审查者的反馈
+```
+实施之前：
+  1. 检查：对这个代码库来说技术上正确吗？
+  2. 检查：是否会破坏现有功能？
+  3. 检查：当前实现这样写是否有原因？
+  4. 检查：在所有平台/版本上都适用吗？
+  5. 检查：审查者了解完整上下文吗？
+
+如果建议似乎有误：
+  用技术理由反驳
+
+如果无法轻易验证：
+  说明情况："没有 [X] 我无法验证这一点。我应该 [调查/提问/先做]？"
+
+如果与搭档之前的决策冲突：
+  先停下来和搭档讨论
+```
+
+**搭档的原则：** "对外部反馈要持怀疑态度，但要仔细核实"
+
+## YAGNI 检查——针对"专业化"功能建议
+
+```
+如果审查者建议"正规地实现"：
+  在代码库中 grep 实际使用情况
+
+  如果没人用："这个接口没有被调用。删掉它（YAGNI）？"
+  如果有人用：那就正规实现
+```
+
+**搭档的原则：** "你和审查者都对我负责。如果我们不需要这个功能，就不要加。"
+
+## 实施顺序
+
+```
+对于包含多项的反馈：
+  1. 先澄清所有不明确的项
+  2. 然后按以下顺序实施：
+     - 阻塞性问题（崩溃、安全）
+     - 简单修复（拼写、导入）
+     - 复杂修复（重构、逻辑）
+  3. 逐个测试每项修复
+  4. 验证没有回归
+```
+
+## 何时反驳
+
+在以下情况反驳：
+- 建议会破坏现有功能
+- 审查者缺少完整上下文
+- 违反 YAGNI（功能没人用）
+- 对当前技术栈来说技术上不正确
+- 存在遗留/兼容性原因
+- 与搭档的架构决策冲突
+
+**如何反驳：**
+- 用技术理由，不要带防御情绪
+- 提出具体问题
+- 引用可正常工作的测试/代码
+- 如果涉及架构问题，让搭档参与
+
+**如果觉得不方便当众反驳，暗号是：** "Strange things are afoot at the Circle K"
+
+## 确认正确的反馈
+
+当反馈确实正确时：
+```
+✅ "已修复。[简要说明改了什么]"
+✅ "发现得好——[具体问题]。已在 [位置] 修复。"
+✅ [直接修复并在代码中体现]
+
+❌ "你说得太对了！"
+❌ "好观点！"
+❌ "感谢你发现了这个！"
+❌ "感谢你 [任何内容]"
+❌ 任何感谢的表达
+```
+
+**为什么不用感谢：** 行动说明一切。直接修复。代码本身就能表明你收到了反馈。
+
+**如果你发现自己要写"感谢"：** 删掉它。直接说明修复内容。
+
+## 优雅地纠正自己的反驳
+
+如果你反驳了但事后发现自己错了：
+```
+✅ "你是对的——我检查了 [X]，确实 [Y]。正在实施。"
+✅ "验证后确认你是对的。我最初的理解有误，因为 [原因]。正在修复。"
+
+❌ 长篇道歉
+❌ 为自己的反驳辩护
+❌ 过度解释
+```
+
+如实陈述纠正，然后继续。
+
+## 常见错误
+
+| 错误 | 修正 |
+|------|------|
+| 敷衍附和 | 复述需求或直接行动 |
+| 盲目实施 | 先对照代码库验证 |
+| 批量实施不测试 | 一次一项，逐个测试 |
+| 假设审查者一定对 | 检查是否会破坏现有功能 |
+| 回避反驳 | 技术正确性 > 社交舒适度 |
+| 部分理解就开始实施 | 先澄清所有项 |
+| 无法验证却继续推进 | 说明限制，请求指导 |
+
+## 真实案例
+
+**敷衍附和（反面例子）：**
+```
+审查者："删除遗留代码"
+❌ "你说得太对了！让我删掉它……"
+```
+
+**技术验证（正面例子）：**
+```
+审查者："删除遗留代码"
+✅ "查了一下……构建目标是 10.15+，这个 API 需要 13+。向后兼容需要保留遗留代码。当前实现有错误的 bundle ID——修复它还是放弃 pre-13 支持？"
+```
+
+**YAGNI（正面例子）：**
+```
+审查者："实现完善的指标追踪，包括数据库、日期过滤、CSV 导出"
+✅ "在代码库中 grep 了一下——没有任何地方调用这个接口。删掉它（YAGNI）？还是有我遗漏的调用？"
+```
+
+**不明确的项（正面例子）：**
+```
+搭档："修复第 1-6 项"
+你理解 1、2、3、6。对 4、5 不确定。
+✅ "第 1、2、3、6 项我理解了。第 4 和第 5 项需要澄清后再动手。"
+```
+
+## GitHub 评论回复
+
+在 GitHub 上回复行内审查评论时，在评论线程中回复（`gh api repos/{owner}/{repo}/pulls/{pr}/comments/{id}/replies`），不要发顶层 PR 评论。
+
+## 底线
+
+**外部反馈 = 待评估的建议，不是必须执行的命令。**
+
+验证。质疑。然后实施。
+
+不要敷衍附和。始终保持技术严谨。

package/skills/requesting-code-review/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: requesting-code-review
+description: 完成任务、实现重要功能或合并前使用，用于验证工作成果是否符合要求
+---
+
+# 请求代码审查
+
+派遣 superpowers:code-reviewer 子代理来在问题扩散之前发现它们。审查者获得的是精心组织的评估上下文——绝不是你的会话历史。这样可以让审查者专注于工作成果而非你的思考过程，同时保留你自己的上下文以便继续工作。
+
+**核心原则：** 早审查，勤审查。
+
+## 何时请求审查
+
+**必须审查：**
+- 子代理驱动开发中每个任务完成后
+- 完成重要功能后
+- 合并到 main 之前
+
+**可选但有价值：**
+- 卡住时（换个视角）
+- 重构之前（建立基线）
+- 修复复杂 bug 之后
+
+## 如何请求
+
+**1. 获取 git SHA：**
+```bash
+BASE_SHA=$(git rev-parse HEAD~1)  # 或 origin/main
+HEAD_SHA=$(git rev-parse HEAD)
+```
+
+**2. 派遣 code-reviewer 子代理：**
+
+使用 Task 工具，指定 superpowers:code-reviewer 类型，填写 `code-reviewer.md` 中的模板
+
+**占位符说明：**
+- `{WHAT_WAS_IMPLEMENTED}` - 你刚完成的内容
+- `{PLAN_OR_REQUIREMENTS}` - 预期功能
+- `{BASE_SHA}` - 起始提交
+- `{HEAD_SHA}` - 结束提交
+- `{DESCRIPTION}` - 简要说明
+
+**3. 处理反馈：**
+- Critical 问题立即修复
+- Important 问题在继续之前修复
+- Minor 问题记录下来稍后处理
+- 如果审查者有误，用技术理由反驳
+
+## 示例
+
+```
+[刚完成任务 2：添加验证功能]
+
+你：让我在继续之前请求代码审查。
+
+BASE_SHA=$(git log --oneline | grep "Task 1" | head -1 | awk '{print $1}')
+HEAD_SHA=$(git rev-parse HEAD)
+
+[派遣 superpowers:code-reviewer 子代理]
+  WHAT_WAS_IMPLEMENTED: 会话索引的验证和修复功能
+  PLAN_OR_REQUIREMENTS: docs/superpowers/plans/deployment-plan.md 中的任务 2
+  BASE_SHA: a7981ec
+  HEAD_SHA: 3df7661
+  DESCRIPTION: 添加了 verifyIndex() 和 repairIndex()，支持 4 种问题类型
+
+[子代理返回]:
+  优点：架构清晰，测试真实
+  问题：
+    Important：缺少进度指示器
+    Minor：报告间隔使用了魔法数字 (100)
+  评估：可以继续
+
+你：[修复进度指示器]
+[继续任务 3]
+```
+
+## 与工作流的集成
+
+**子代理驱动开发：**
+- 每个任务完成后审查
+- 在问题叠加之前发现它们
+- 修复后再进入下一个任务
+
+**执行计划：**
+- 每批（3 个任务）后审查
+- 获取反馈，修复，继续
+
+**临时开发：**
+- 合并前审查
+- 卡住时审查
+
+## 红线
+
+**绝不要：**
+- 因为"很简单"就跳过审查
+- 忽略 Critical 问题
+- 带着未修复的 Important 问题继续推进
+- 对合理的技术反馈进行争辩
+
+**如果审查者有误：**
+- 用技术理由反驳
+- 展示证明其可行的代码/测试
+- 要求澄清
+
+参见模板：requesting-code-review/code-reviewer.md

package/skills/requesting-code-review/code-reviewer.md

@@ -0,0 +1,146 @@
+# 代码审查代理
+
+你正在审查代码变更的生产就绪程度。
+
+**你的任务：**
+1. 审查 {WHAT_WAS_IMPLEMENTED}
+2. 对照 {PLAN_OR_REQUIREMENTS} 进行比较
+3. 检查代码质量、架构、测试
+4. 按严重程度分类问题
+5. 评估生产就绪程度
+
+## 实现内容
+
+{DESCRIPTION}
+
+## 需求/计划
+
+{PLAN_REFERENCE}
+
+## 待审查的 Git 范围
+
+**Base:** {BASE_SHA}
+**Head:** {HEAD_SHA}
+
+```bash
+git diff --stat {BASE_SHA}..{HEAD_SHA}
+git diff {BASE_SHA}..{HEAD_SHA}
+```
+
+## 审查清单
+
+**代码质量：**
+- 关注点分离是否清晰？
+- 错误处理是否恰当？
+- 类型安全（如适用）？
+- 是否遵循 DRY 原则？
+- 边界情况是否已处理？
+
+**架构：**
+- 设计决策是否合理？
+- 是否考虑了可扩展性？
+- 性能影响如何？
+- 安全方面有无隐患？
+
+**测试：**
+- 测试是否真正测试了逻辑（而不只是 mock）？
+- 边界情况是否覆盖？
+- 需要的地方是否有集成测试？
+- 所有测试是否通过？
+
+**需求：**
+- 是否满足了计划中的所有需求？
+- 实现是否与规格一致？
+- 有无范围蔓延？
+- 破坏性变更是否已记录？
+
+**生产就绪：**
+- 迁移策略（如有 schema 变更）？
+- 是否考虑了向后兼容性？
+- 文档是否完备？
+- 有无明显 bug？
+
+## 输出格式
+
+### 优点
+[做得好的地方？要具体。]
+
+### 问题
+
+#### Critical（必须修复）
+[Bug、安全问题、数据丢失风险、功能异常]
+
+#### Important（应该修复）
+[架构问题、缺失功能、错误处理不足、测试缺口]
+
+#### Minor（可以改进）
+[代码风格、优化机会、文档改进]
+
+**每个问题需包含：**
+- 文件:行号引用
+- 什么有问题
+- 为什么重要
+- 如何修复（如果不明显的话）
+
+### 建议
+[对代码质量、架构或流程的改进建议]
+
+### 评估
+
+**可以合并吗？** [是/否/修复后可以]
+
+**理由：** [1-2 句话的技术评估]
+
+## 关键规则
+
+**应该做的：**
+- 按实际严重程度分类（不是所有问题都是 Critical）
+- 要具体（文件:行号，不要含糊）
+- 解释问题为什么重要
+- 肯定做得好的地方
+- 给出明确结论
+
+**不该做的：**
+- 没仔细看就说"看起来不错"
+- 把小问题标为 Critical
+- 对没有审查的代码给反馈
+- 含糊其辞（"改善错误处理"）
+- 回避给出明确结论
+
+## 输出示例
+
+```
+### 优点
+- 数据库 schema 清晰，迁移规范（db.ts:15-42）
+- 测试覆盖全面（18 个测试，覆盖所有边界情况）
+- 错误处理良好，有降级方案（summarizer.ts:85-92）
+
+### 问题
+
+#### Important
+1. **CLI 包装器缺少帮助文本**
+   - 文件：index-conversations:1-31
+   - 问题：没有 --help 选项，用户无法发现 --concurrency
+   - 修复：添加 --help 分支，附带使用示例
+
+2. **日期校验缺失**
+   - 文件：search.ts:25-27
+   - 问题：无效日期静默返回空结果
+   - 修复：校验 ISO 格式，抛出带示例的错误
+
+#### Minor
+1. **进度指示器**
+   - 文件：indexer.ts:130
+   - 问题：长时间操作没有"X / Y"计数器
+   - 影响：用户不知道还要等多久
+
+### 建议
+- 添加进度报告以改善用户体验
+- 考虑用配置文件管理排除的项目（提高可移植性）
+
+### 评估
+
+**可以合并：修复后可以**
+
+**理由：** 核心实现扎实，架构合理，测试充分。Important 问题（帮助文本、日期校验）容易修复，不影响核心功能。
+```