diff --git a/skills/brainstorming/SKILL.md b/skills/brainstorming/SKILL.md index f6e9f7a..e01d423 100644 --- a/skills/brainstorming/SKILL.md +++ b/skills/brainstorming/SKILL.md @@ -27,7 +27,7 @@ description: "在任何创造性工作之前必须使用此技能——创建功 4. **提出 2-3 种方案** — 附带权衡分析和你的推荐 5. **展示设计** — 按复杂度分节展示,每节展示后获得用户批准 6. **编写设计文档** — 保存到 `docs/superpowers/specs/YYYY-MM-DD--design.md` 并 commit -7. **规格审查循环** — 调度 spec-document-reviewer 子代理,提供精心组织的审查上下文(绝不是你的会话历史);修复问题后重新调度直到通过(最多 3 次迭代,之后交给人工处理) +7. **规格自检** — 快速内联检查占位符、矛盾、模糊性、范围(详见下方) 8. **用户审查书面规格** — 在继续之前请用户审查规格文件 9. **过渡到实现** — 调用 writing-plans 技能创建实现计划 @@ -43,8 +43,7 @@ digraph brainstorming { "分节展示设计" [shape=box]; "用户批准设计?" [shape=diamond]; "编写设计文档" [shape=box]; - "规格审查循环" [shape=box]; - "规格审查通过?" [shape=diamond]; + "规格自检\n(内联修复)" [shape=box]; "用户审查规格?" [shape=diamond]; "调用 writing-plans 技能" [shape=doublecircle]; @@ -57,10 +56,8 @@ digraph brainstorming { "分节展示设计" -> "用户批准设计?"; "用户批准设计?" -> "分节展示设计" [label="否,修改"]; "用户批准设计?" -> "编写设计文档" [label="是"]; - "编写设计文档" -> "规格审查循环"; - "规格审查循环" -> "规格审查通过?"; - "规格审查通过?" -> "规格审查循环" [label="发现问题,\n修复后重新调度"]; - "规格审查通过?" -> "用户审查规格?" [label="通过"]; + "编写设计文档" -> "规格自检\n(内联修复)"; + "规格自检\n(内联修复)" -> "用户审查规格?"; "用户审查规格?" -> "编写设计文档" [label="要求修改"]; "用户审查规格?" -> "调用 writing-plans 技能" [label="批准"]; } @@ -116,19 +113,22 @@ digraph brainstorming { - 如果可用,使用 elements-of-style:writing-clearly-and-concisely 技能 - 将设计文档 commit 到 git -**规格审查循环:** -编写规格文档后: +**规格自检:** +编写规格文档后,以全新的视角审视它: -1. 调度 spec-document-reviewer 子代理(参见 spec-document-reviewer-prompt.md) -2. 如果发现问题:修复,重新调度,重复直到通过 -3. 如果循环超过 3 次迭代,交给人工指导 +1. **占位符扫描:** 有没有"待定"、"TODO"、未完成的章节或模糊的需求?修复它们。 +2. **内部一致性:** 各章节之间有矛盾吗?架构和功能描述匹配吗? +3. **范围检查:** 这是否聚焦到可以用一个实现计划覆盖,还是需要进一步拆分? +4. **模糊性检查:** 有没有需求可以被两种方式理解?如果有,选择一种并明确写出来。 + +发现问题就直接内联修复。无需重新审查——修好继续推进。 **用户审查关卡:** -规格审查循环通过后,请用户在继续之前审查书面规格: +规格自检完成后,请用户在继续之前审查书面规格: > "规格已编写并 commit 到 ``。请审查一下,如果在我们开始编写实现计划之前你想做任何修改,请告诉我。" -等待用户回复。如果他们要求修改,做出修改并重新运行规格审查循环。只有在用户批准后才继续。 +等待用户回复。如果他们要求修改,做出修改并重新运行规格自检。只有在用户批准后才继续。 **实现:** diff --git a/skills/writing-plans/SKILL.md b/skills/writing-plans/SKILL.md index 2ddb41e..e51c0e8 100644 --- a/skills/writing-plans/SKILL.md +++ b/skills/writing-plans/SKILL.md @@ -103,26 +103,33 @@ git commit -m "feat: add specific feature" ``` ```` +## 禁止占位符 + +每个步骤都必须包含工程师需要的实际内容。以下是**计划缺陷**——绝不要写出来: +- "待定"、"TODO"、"后续实现"、"补充细节" +- "添加适当的错误处理" / "添加验证" / "处理边界情况" +- "为上述代码编写测试"(没有实际测试代码) +- "类似任务 N"(重复代码——工程师可能不按顺序阅读任务) +- 只描述做什么而不展示怎么做的步骤(代码步骤必须有代码块) +- 引用了未在任何任务中定义的类型、函数或方法 + ## 注意事项 - 始终使用精确的文件路径 -- 计划中包含完整代码(而非"添加验证") +- 每个步骤都包含完整代码——如果步骤涉及代码变更,就展示代码 - 精确的命令和预期输出 -- 使用 @ 语法引用相关技能 - DRY、YAGNI、TDD、频繁 commit -## 计划审查循环 +## 自检 -编写完整计划后: +编写完整计划后,以全新视角审视规格并对照检查计划。这是你自己执行的检查清单——不是子代理调度。 -1. 调度一个 plan-document-reviewer 子代理(参见 plan-document-reviewer-prompt.md),提供精心组织的审查上下文——绝不是你的会话历史。这样可以让审查员专注于计划本身,而非你的思考过程。 - - 提供:计划文档路径、规格文档路径 -2. 如果发现问题:修复问题,重新调度审查员审查整个计划 -3. 如果通过:进入执行交接 +**1. 规格覆盖度:** 浏览规格中的每个章节/需求。你能指出实现它的任务吗?列出所有遗漏。 -**审查循环指南:** -- 编写计划的同一个代理负责修复(保留上下文) -- 如果循环超过 3 次迭代,交给人工指导 -- 审查员是顾问性质的——如果你认为反馈不正确,可以解释你的理由 +**2. 占位符扫描:** 搜索计划中的红旗——上方"禁止占位符"章节中的任何模式。修复它们。 + +**3. 类型一致性:** 后续任务中使用的类型、方法签名和属性名是否与前面任务中定义的一致?任务 3 中叫 `clearLayers()` 但任务 7 中叫 `clearFullLayers()` 就是 bug。 + +如果发现问题,直接内联修复。无需重新审查——修好继续推进。如果发现规格中的需求没有对应任务,就添加任务。 ## 执行交接 diff --git a/skills/writing-skills/SKILL.md b/skills/writing-skills/SKILL.md index 27d765c..1103b5b 100644 --- a/skills/writing-skills/SKILL.md +++ b/skills/writing-skills/SKILL.md @@ -92,7 +92,7 @@ skills/ ## SKILL.md 结构 **Frontmatter(YAML):** -- 仅支持两个字段:`name` 和 `description` +- 两个必需字段:`name` 和 `description`(完整支持字段参见 [agentskills.io/specification](https://agentskills.io/specification)) - 总计最多 1024 字符 - `name`:只使用字母、数字和连字符(不要用括号、特殊字符) - `description`:第三人称,仅描述何时使用(不是做什么) @@ -603,7 +603,7 @@ helper1、helper2、step3、pattern4 **绿色阶段 - 编写最小技能:** - [ ] 名称只使用字母、数字、连字符(无括号/特殊字符) -- [ ] YAML frontmatter 仅包含 name 和 description(最多 1024 字符) +- [ ] YAML frontmatter 包含必需的 `name` 和 `description` 字段(最多 1024 字符;参见 [spec](https://agentskills.io/specification)) - [ ] 描述以"Use when..."开头并包含具体的触发条件/症状 - [ ] 描述用第三人称 - [ ] 全文包含搜索关键词(错误、症状、工具)