mirror of
https://github.com/jnMetaCode/superpowers-zh.git
synced 2026-09-02 22:54:06 +08:00
refactor(skills): 同步上游 C 块 —— 说服性段落改为 rationalization 表（#19 收尾）
对齐上游 14 个 refactor commit 中尚未同步的 11 个（另 3 个已随 A/B 块完成）。 audit 上游结构漂移告警由此清零：150 pass / 0 warn / 0 fail。 ## 盘点先行：不是所有改动都是风格性的 C 块开工前做了逐 commit 盘点，判定标准定为「删掉的文字里有没有别处没写的 规则」。结论纠正了我之前的假设 —— 其中 3 项是实质改动，不是纯瘦身： - cfb6281 新增了一张 rationalization 表（2 行全新规则），替换掉 「与工作流的集成」那份工作流清单 - 03147d2 给 executing-plans 加了「先确保隔离工作区」作为步骤 1 （SDD 那一半已随 A 块完成） - bc86802 把「常见错误」5 个小节 + 「红线」Never/Always 双清单压成 5 行表， 规则一条不少 —— 这也是此前唯一有客观漂移证据的 skill ## 逐项核实后才删 每处删除都先确认规则在别处仍在： - receiving-code-review「底线」：概述已有「核心原则：先验证再实施。先提问再假设」 - writing-skills「总结」：铁律节 + TDD 循环表已完整承载 - writing-plans「注意事项」：精确路径 / Run: / 预期输出 三条都内建在任务结构 模板里 —— 上游是把「告知」改成「示范」 - brainstorming「核心原则」6 条：5 条已在流程详述里逐条体现（每次一个问题、 优先选择题、2-3 种方案、增量验证、回头澄清），YAGNI 按上游移到「探索方案」 的使用现场 - systematic-debugging / dispatching-parallel-agents / verification-before-completion 删的是「实际效果」「核心优势」「为什么这很重要」这类社会证明与说服段， 核心原则行全部保留 - systematic-debugging 的「相关技能」块折入第四阶段「验证修复」 - executing-plans 删掉的质量宣称按上游改写为平铺的平台清单 ## 验证 结构 - 10 个 skill 的 H2 数与上游逐一对齐（8 个完全相同、2 个差 1） - executing-plans / using-git-worktrees / requesting-code-review 的 superpowers: 引用集与上游完全一致 行为 eval —— 两轮共 11 题全对 专门考被删段落里的规则是否仍生效： - 原生 worktree 工具 vs git worktree add（答出「第一大错误」与「幽灵状态」） - 跳过 check-ignore 的后果、目录名优先级顺序 - 基线测试失败能否继续、能否无证据宣称完成 - 审查建议技术上有疑问时该照做还是反驳 - 能否先打补丁再查根因 - 能否自己读 diff 代替派审查者（命中 cfb6281 新增的表行） - 方案里的「以后可能用得上」功能怎么处理（命中 YAGNI 的新落点） 回归：audit.sh 150 pass / 0 warn / 0 fail、verify-release.sh 82 pass / 0 fail 注：audit PASS 由 152 降至 150 —— 上游有意删除的两个「集成」节里各有 superpowers: 引用，Category 4b 因此少 2 项检查；引用集已核对与上游一致。
This commit is contained in:
AI不止语
@@ -87,6 +87,7 @@ digraph brainstorming {
|
||||
- 提出 2-3 种不同的方案及其权衡
|
||||
- 以对话的方式展示选项，附上你的推荐和理由
|
||||
- 先展示你推荐的方案并解释原因
|
||||
- 严格遵循 YAGNI —— 从每个方案和设计里移除不必要的功能
|
||||
|
||||
**展示设计：**
|
||||
|
||||
@@ -140,15 +141,6 @@ digraph brainstorming {
|
||||
- 调用 writing-plans 技能创建详细的实现计划
|
||||
- 不要调用任何其他技能。writing-plans 是下一步。
|
||||
|
||||
## 核心原则
|
||||
|
||||
- **每次一个问题** — 不要同时抛出多个问题
|
||||
- **优先选择题** — 在可能的情况下比开放式问题更容易回答
|
||||
- **严格遵循 YAGNI** — 从所有设计中移除不必要的功能
|
||||
- **探索替代方案** — 在做决定之前始终提出 2-3 种方案
|
||||
- **增量验证** — 展示设计，获得批准后再继续
|
||||
- **保持灵活** — 有不明确的地方就回头澄清
|
||||
|
||||
## 视觉伴侣
|
||||
|
||||
一个基于浏览器的伴侣工具，用于在头脑风暴过程中展示原型、图表和视觉选项。它是一个工具——不是一种模式。接受伴侣意味着它可用于适合视觉呈现的问题；并不意味着每个问题都要通过浏览器。
|
||||
|
||||
@@ -160,15 +160,6 @@ Task("修复 tool-approval-race-conditions.test.ts 的失败")
|
||||
|
||||
**集成：** 所有修复互相独立，无冲突，完整测试套件全部通过
|
||||
|
||||
**节省的时间：** 3 个问题并行解决 vs 顺序解决
|
||||
|
||||
## 核心优势
|
||||
|
||||
1. **并行化** - 多个排查同时进行
|
||||
2. **聚焦** - 每个智能体范围窄，需要跟踪的上下文少
|
||||
3. **独立性** - 智能体之间互不干扰
|
||||
4. **速度** - 3 个问题在 1 个问题的时间内解决
|
||||
|
||||
## 验证
|
||||
|
||||
智能体返回后：
|
||||
@@ -177,11 +168,3 @@ Task("修复 tool-approval-race-conditions.test.ts 的失败")
|
||||
3. **运行完整套件** - 验证所有修复协同工作
|
||||
4. **抽查** - 智能体可能犯系统性错误
|
||||
|
||||
## 实际效果
|
||||
|
||||
来自调试会话（2025-10-03）：
|
||||
- 3 个文件中 6 个失败
|
||||
- 并行分派 3 个智能体
|
||||
- 所有排查并发完成
|
||||
- 所有修复成功集成
|
||||
- 智能体之间的更改零冲突
|
||||
|
||||
@@ -16,16 +16,17 @@ metadata:
|
||||
|
||||
**开始时宣布：** "我正在使用 executing-plans 技能来实现此计划。"
|
||||
|
||||
**注意：** 告诉你的人类伙伴，Superpowers 在有子代理支持时效果好得多。如果在支持子代理的平台上运行（如 Claude Code 或 Codex），其工作质量会显著提高。如果子代理可用，请使用 superpowers:subagent-driven-development 而非此技能。
|
||||
**注意：** 告诉你的人类伙伴，Superpowers 在有子代理支持时效果好得多（Claude Code、Codex CLI、Codex App、Copilot CLI 与 Gemini CLI 都算；见 `../using-superpowers/references/` 下的各平台工具参考）。如果子代理可用，请使用 superpowers:subagent-driven-development 而非此技能。
|
||||
|
||||
## 流程
|
||||
|
||||
### 步骤 1：加载并审查计划
|
||||
|
||||
1. 读取计划文件
|
||||
2. 批判性审查——识别计划中的任何问题或疑虑
|
||||
3. 如果有疑虑：在开始之前向你的人类伙伴提出
|
||||
4. 如果没有疑虑：创建 TodoWrite 并继续
|
||||
1. 确保有一个隔离的工作区：用 superpowers:using-git-worktrees 创建一个，或者核实已有的那个
|
||||
2. 读取计划文件
|
||||
3. 批判性审查——识别计划中的任何问题或疑虑
|
||||
4. 如果有疑虑：在开始之前向你的人类伙伴提出
|
||||
5. 如果没有疑虑：创建 TodoWrite 并继续
|
||||
|
||||
**审查时重点检查：**
|
||||
- 步骤之间是否有依赖遗漏？（A 依赖 B，但 B 排在 A 之后）
|
||||
@@ -172,9 +173,3 @@ $ git commit -m "feat: 添加用户输入验证（任务 2/5）"
|
||||
- 遇到阻塞时停下来，不要猜测
|
||||
- 未经用户明确同意，绝不在 main/master 分支上开始实现
|
||||
|
||||
## 集成
|
||||
|
||||
**必需的工作流技能：**
|
||||
- **superpowers:using-git-worktrees** - 必需：开始前建立隔离的工作空间
|
||||
- **superpowers:writing-plans** - 创建此技能要执行的计划
|
||||
- **superpowers:finishing-a-development-branch** - 所有任务完成后收尾开发
|
||||
|
||||
@@ -209,10 +209,3 @@ metadata:
|
||||
|
||||
在 GitHub 上回复行内审查评论时，在评论线程中回复（`gh api repos/{owner}/{repo}/pulls/{pr}/comments/{id}/replies`），不要发顶层 PR 评论。
|
||||
|
||||
## 底线
|
||||
|
||||
**外部反馈 = 待评估的建议，不是必须执行的命令。**
|
||||
|
||||
验证。质疑。然后实施。
|
||||
|
||||
不要敷衍附和。始终保持技术严谨。
|
||||
|
||||
@@ -10,7 +10,7 @@ metadata:
|
||||
|
||||
# 请求代码审查
|
||||
|
||||
派遣代码审查子代理，在问题扩散之前发现它们。审查者获得的是精心组织的评估上下文——绝不是你的会话历史。这样可以让审查者专注于工作成果而非你的思考过程，同时保留你自己的上下文以便继续工作。
|
||||
派遣代码审查子代理，在问题扩散之前发现它们。审查者获得的是精心组织的评估上下文——绝不是你的会话历史。
|
||||
|
||||
**核心原则：** 早审查，勤审查。
|
||||
|
||||
@@ -77,20 +77,12 @@ HEAD_SHA=$(git rev-parse HEAD)
|
||||
[继续任务 3]
|
||||
```
|
||||
|
||||
## 与工作流的集成
|
||||
## 常见的合理化借口
|
||||
|
||||
**子代理驱动开发：**
|
||||
- 每个任务完成后审查
|
||||
- 在问题叠加之前发现它们
|
||||
- 修复后再进入下一个任务
|
||||
|
||||
**执行计划：**
|
||||
- 每个任务完成后或在自然 checkpoint 审查
|
||||
- 获取反馈，应用，继续
|
||||
|
||||
**临时开发：**
|
||||
- 合并前审查
|
||||
- 卡住时审查
|
||||
| 借口 | 现实 |
|
||||
|------|------|
|
||||
| "我自己看一下 diff 就行了，不用专门派审查者" | 你是协调者——在自己的会话里读 diff 会烧掉你继续推进工作所需的上下文窗口。派一个审查子智能体：diff 和评估过程都待在它的上下文里，只有结论回到你这里。 |
|
||||
| "审查者需要我的全部会话历史才能理解这次改动" | 给它精心组织的上下文，绝不给会话历史。这样审查者才会盯着工作成果，而不是你的思考过程。 |
|
||||
|
||||
## 红线
|
||||
|
||||
|
||||
@@ -12,8 +12,6 @@ metadata:
|
||||
|
||||
## 概述
|
||||
|
||||
随意修复既浪费时间又会引入新 bug。草率的补丁只会掩盖深层问题。
|
||||
|
||||
**核心原则：** 在尝试修复之前，务必先找到根本原因。只修症状就是失败。
|
||||
|
||||
**敷衍走流程等于违背调试的精神。**
|
||||
@@ -193,6 +191,7 @@ metadata:
|
||||
- 测试现在通过了吗？
|
||||
- 其他测试没有被破坏吧？
|
||||
- 问题真的解决了吗？
|
||||
- 宣称成功之前，使用 `superpowers:verification-before-completion` 技能
|
||||
|
||||
4. **如果修复不起作用**
|
||||
- 停下来
|
||||
@@ -288,14 +287,3 @@ metadata:
|
||||
- **`defense-in-depth.md`** - 找到根因后，在多个层级添加校验
|
||||
- **`condition-based-waiting.md`** - 用条件轮询替代硬编码等待时间
|
||||
|
||||
**相关技能：**
|
||||
- **superpowers:test-driven-development** - 用于创建失败测试用例（第四阶段，第 1 步）
|
||||
- **superpowers:verification-before-completion** - 在宣称成功之前验证修复确实有效
|
||||
|
||||
## 实际效果
|
||||
|
||||
调试实践中的数据：
|
||||
- 系统化方法：15-30 分钟修复
|
||||
- 随意修复方法：2-3 小时反复折腾
|
||||
- 一次修复成功率：95% vs 40%
|
||||
- 引入新 bug：几乎为零 vs 经常发生
|
||||
|
||||
@@ -164,62 +164,12 @@ npm test / cargo test / pytest / go test ./...
|
||||
| 基线测试失败 | 报告失败 + 询问 |
|
||||
| 无 package.json/Cargo.toml | 跳过依赖安装 |
|
||||
|
||||
## 常见错误
|
||||
## 常见的合理化借口
|
||||
|
||||
### 与 harness 对抗
|
||||
|
||||
- **问题：** 平台已经提供隔离的情况下还在用 `git worktree add`
|
||||
- **修复：** 步骤 0 检测现有隔离。步骤 1a 让位给原生工具。
|
||||
|
||||
### 跳过检测
|
||||
|
||||
- **问题：** 在已有的 worktree 内嵌套创建另一个 worktree
|
||||
- **修复：** 创建任何东西之前都先跑步骤 0
|
||||
|
||||
### 跳过忽略验证
|
||||
|
||||
- **问题：** worktree 内容被跟踪，污染 git status
|
||||
- **修复：** 创建项目本地 worktree 前始终使用 `git check-ignore`
|
||||
|
||||
### 假设目录位置
|
||||
|
||||
- **问题：** 造成不一致、违反项目约定
|
||||
- **修复：** 遵循优先级：明确 instructions > 现有项目本地目录 > 默认
|
||||
|
||||
### 带着失败的测试继续
|
||||
|
||||
- **问题：** 无法区分新 bug 和已有问题
|
||||
- **修复：** 报告失败，获得明确许可后再继续
|
||||
|
||||
## 红线
|
||||
|
||||
**绝不：**
|
||||
|
||||
- 步骤 0 已检测到现有隔离时还创建 worktree
|
||||
- 在已有原生 worktree 工具（如 `EnterWorktree`）的情况下还用 `git worktree add`。这是 #1 错误——有就用。
|
||||
- 跳过步骤 1a 直接跳到步骤 1b 的 git 命令
|
||||
- 不验证已忽略就创建项目本地 worktree
|
||||
- 跳过基线测试验证
|
||||
- 不询问就带着失败的测试继续
|
||||
|
||||
**始终：**
|
||||
|
||||
- 先跑步骤 0 检测
|
||||
- 优先原生工具，其次 git 回退
|
||||
- 遵循目录优先级：明确 instructions > 现有项目本地目录 > 默认
|
||||
- 项目本地目录验证已忽略
|
||||
- 自动检测并运行项目设置
|
||||
- 验证测试基线干净
|
||||
|
||||
## 集成
|
||||
|
||||
**被以下技能调用：**
|
||||
|
||||
- **brainstorming**（阶段 4）- 设计通过且需要实现时必需
|
||||
- **subagent-driven-development** - 执行任何任务前必需
|
||||
- **executing-plans** - 执行任何任务前必需
|
||||
- 任何需要隔离工作区的技能
|
||||
|
||||
**配合使用：**
|
||||
|
||||
- **finishing-a-development-branch** - 工作完成后清理时必需
|
||||
| 借口 | 现实 |
|
||||
|------|------|
|
||||
| "我显然不在 worktree 里，不用检查" | 跑步骤 0。宿主环境创建的隔离和 submodule 都能骗过肉眼；只有检测命令能定论。 |
|
||||
| "`git worktree add` 比去找原生工具快" | 原生工具（如 `EnterWorktree`）掌管位置、分支和清理。绕过它是**第一大错误** —— 会造出你的宿主环境看不见也管不了的幽灵状态。 |
|
||||
| "这个 worktree 目录肯定已经被忽略了" | 跑 `git check-ignore`。一个没被忽略的 worktree 目录会把整棵树提交进仓库。 |
|
||||
| "目录名随便取都行" | 明确指示 > 已存在的项目内目录 > `.worktrees/` 默认值。 |
|
||||
| "工作区是全新的，基线测试可以先放放" | 基线不干净会让之后每一次失败都含义不明。现在就跑测试；越过失败继续是你人类伙伴的决定。 |
|
||||
|
||||
@@ -12,8 +12,6 @@ metadata:
|
||||
|
||||
## 概述
|
||||
|
||||
在没有验证的情况下宣称工作完成，这不是高效，而是不诚实。
|
||||
|
||||
**核心原则：** 始终用证据支撑结论。
|
||||
|
||||
**对这条规则敷衍了事，就等于违背了它的精神。**
|
||||
@@ -110,15 +108,6 @@ metadata:
|
||||
❌ 信任代理报告
|
||||
```
|
||||
|
||||
## 为什么这很重要
|
||||
|
||||
来自 24 次失败记录：
|
||||
- 搭档说"我不信你"——信任被破坏
|
||||
- 未定义的函数被交付——会直接崩溃
|
||||
- 遗漏需求被交付——功能不完整
|
||||
- 虚假完成浪费的时间 → 返工 → 重做
|
||||
- 违反原则："诚实是核心价值。如果你说谎，就会被替换。"
|
||||
|
||||
## 何时使用
|
||||
|
||||
**以下情况之前必须使用：**
|
||||
@@ -135,10 +124,3 @@ metadata:
|
||||
- 暗示成功
|
||||
- 任何传达完成/正确性的沟通
|
||||
|
||||
## 底线
|
||||
|
||||
**验证没有捷径。**
|
||||
|
||||
运行命令。阅读输出。然后才能宣称结果。
|
||||
|
||||
这没有商量余地。
|
||||
|
||||
@@ -118,12 +118,6 @@ git commit -m "feat: add specific feature"
|
||||
- 只描述做什么而不展示怎么做的步骤（代码步骤必须有代码块）
|
||||
- 引用了未在任何任务中定义的类型、函数或方法
|
||||
|
||||
## 注意事项
|
||||
- 始终使用精确的文件路径
|
||||
- 每个步骤都包含完整代码——如果步骤涉及代码变更，就展示代码
|
||||
- 精确的命令和预期输出
|
||||
- DRY、YAGNI、TDD、频繁 commit
|
||||
|
||||
## 自检
|
||||
|
||||
编写完整计划后，以全新视角审视规格并对照检查计划。这是你自己执行的检查清单——不是子代理调度。
|
||||
|
||||
@@ -648,12 +648,3 @@ helper1、helper2、step3、pattern4
|
||||
|
||||
**为此流程优化** - 把可搜索的术语放在前面和各处。
|
||||
|
||||
## 总结
|
||||
|
||||
**创建技能就是流程文档的 TDD。**
|
||||
|
||||
同样的铁律：没有失败的测试就不写技能。
|
||||
同样的循环：红（基线）→ 绿（写技能）→ 重构（堵漏洞）。
|
||||
同样的好处：更高的质量、更少的意外、无懈可击的结果。
|
||||
|
||||
如果你对代码遵循 TDD，对技能也应如此。这是同样的纪律应用于文档。
|
||||
|
||||
Reference in New Issue
Block a user