fix: 任务定位
This commit is contained in:
282
.agents/skills/subagent-driven-development/SKILL.md
Normal file
282
.agents/skills/subagent-driven-development/SKILL.md
Normal file
@@ -0,0 +1,282 @@
|
||||
---
|
||||
name: subagent-driven-development
|
||||
description: 当在当前会话中执行包含独立任务的实现计划时使用
|
||||
version: "1.0.0"
|
||||
license: MIT
|
||||
metadata:
|
||||
hermes:
|
||||
tags: [agents, development]
|
||||
---
|
||||
|
||||
# 子智能体驱动开发
|
||||
|
||||
通过为每个任务分派一个全新的子智能体来执行计划，每个任务完成后进行两阶段审查：先审查规格合规性，再审查代码质量。
|
||||
|
||||
**为什么用子智能体：** 你将任务委派给具有隔离上下文的专用智能体。通过精心设计它们的指令和上下文，确保它们专注并成功完成任务。它们不应继承你的会话上下文或历史记录——你要精确构造它们所需的一切。这样也能为你自己保留用于协调工作的上下文。
|
||||
|
||||
**核心原则：** 每个任务一个全新子智能体 + 两阶段审查（先规格后质量）= 高质量、快速迭代
|
||||
|
||||
## 何时使用
|
||||
|
||||
```dot
|
||||
digraph when_to_use {
|
||||
"有实现计划?" [shape=diamond];
|
||||
"任务基本独立?" [shape=diamond];
|
||||
"留在当前会话?" [shape=diamond];
|
||||
"subagent-driven-development" [shape=box];
|
||||
"executing-plans" [shape=box];
|
||||
"手动执行或先头脑风暴" [shape=box];
|
||||
|
||||
"有实现计划?" -> "任务基本独立?" [label="是"];
|
||||
"有实现计划?" -> "手动执行或先头脑风暴" [label="否"];
|
||||
"任务基本独立?" -> "留在当前会话?" [label="是"];
|
||||
"任务基本独立?" -> "手动执行或先头脑风暴" [label="否 - 紧密耦合"];
|
||||
"留在当前会话?" -> "subagent-driven-development" [label="是"];
|
||||
"留在当前会话?" -> "executing-plans" [label="否 - 并行会话"];
|
||||
}
|
||||
```
|
||||
|
||||
**与 Executing Plans（并行会话）的对比：**
|
||||
- 同一会话（无上下文切换）
|
||||
- 每个任务全新子智能体（无上下文污染）
|
||||
- 每个任务后两阶段审查：先规格合规性，再代码质量
|
||||
- 更快的迭代（任务间无需人工介入）
|
||||
|
||||
## 流程
|
||||
|
||||
```dot
|
||||
digraph process {
|
||||
rankdir=TB;
|
||||
|
||||
subgraph cluster_per_task {
|
||||
label="每个任务";
|
||||
"分派实现子智能体 (./implementer-prompt.md)" [shape=box];
|
||||
"实现子智能体有疑问?" [shape=diamond];
|
||||
"回答问题，提供上下文" [shape=box];
|
||||
"实现子智能体实现、测试、提交、自审" [shape=box];
|
||||
"分派规格审查子智能体 (./spec-reviewer-prompt.md)" [shape=box];
|
||||
"规格审查子智能体确认代码匹配规格?" [shape=diamond];
|
||||
"实现子智能体修复规格差距" [shape=box];
|
||||
"分派代码质量审查子智能体 (./code-quality-reviewer-prompt.md)" [shape=box];
|
||||
"代码质量审查子智能体通过?" [shape=diamond];
|
||||
"实现子智能体修复质量问题" [shape=box];
|
||||
"在 TodoWrite 中标记任务完成" [shape=box];
|
||||
}
|
||||
|
||||
"读取计划，提取所有任务的完整文本，记录上下文，创建 TodoWrite" [shape=box];
|
||||
"还有剩余任务?" [shape=diamond];
|
||||
"分派最终代码审查子智能体审查整体实现" [shape=box];
|
||||
"使用 superpowers:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen];
|
||||
|
||||
"读取计划，提取所有任务的完整文本，记录上下文，创建 TodoWrite" -> "分派实现子智能体 (./implementer-prompt.md)";
|
||||
"分派实现子智能体 (./implementer-prompt.md)" -> "实现子智能体有疑问?";
|
||||
"实现子智能体有疑问?" -> "回答问题，提供上下文" [label="是"];
|
||||
"回答问题，提供上下文" -> "分派实现子智能体 (./implementer-prompt.md)";
|
||||
"实现子智能体有疑问?" -> "实现子智能体实现、测试、提交、自审" [label="否"];
|
||||
"实现子智能体实现、测试、提交、自审" -> "分派规格审查子智能体 (./spec-reviewer-prompt.md)";
|
||||
"分派规格审查子智能体 (./spec-reviewer-prompt.md)" -> "规格审查子智能体确认代码匹配规格?";
|
||||
"规格审查子智能体确认代码匹配规格?" -> "实现子智能体修复规格差距" [label="否"];
|
||||
"实现子智能体修复规格差距" -> "分派规格审查子智能体 (./spec-reviewer-prompt.md)" [label="重新审查"];
|
||||
"规格审查子智能体确认代码匹配规格?" -> "分派代码质量审查子智能体 (./code-quality-reviewer-prompt.md)" [label="是"];
|
||||
"分派代码质量审查子智能体 (./code-quality-reviewer-prompt.md)" -> "代码质量审查子智能体通过?";
|
||||
"代码质量审查子智能体通过?" -> "实现子智能体修复质量问题" [label="否"];
|
||||
"实现子智能体修复质量问题" -> "分派代码质量审查子智能体 (./code-quality-reviewer-prompt.md)" [label="重新审查"];
|
||||
"代码质量审查子智能体通过?" -> "在 TodoWrite 中标记任务完成" [label="是"];
|
||||
"在 TodoWrite 中标记任务完成" -> "还有剩余任务?";
|
||||
"还有剩余任务?" -> "分派实现子智能体 (./implementer-prompt.md)" [label="是"];
|
||||
"还有剩余任务?" -> "分派最终代码审查子智能体审查整体实现" [label="否"];
|
||||
"分派最终代码审查子智能体审查整体实现" -> "使用 superpowers:finishing-a-development-branch";
|
||||
}
|
||||
```
|
||||
|
||||
## 模型选择
|
||||
|
||||
使用能胜任每个角色的最低成本模型，以节省开支并提高速度。
|
||||
|
||||
**机械性实现任务**（隔离的函数、清晰的规格、1-2 个文件）：使用快速、便宜的模型。当计划编写得足够详细时，大多数实现任务都是机械性的。
|
||||
|
||||
**集成和判断类任务**（多文件协调、模式匹配、调试）：使用标准模型。
|
||||
|
||||
**架构、设计和审查类任务**：使用最强的可用模型。
|
||||
|
||||
**任务复杂度信号：**
|
||||
- 涉及 1-2 个文件且有完整规格 → 便宜模型
|
||||
- 涉及多个文件且有集成考虑 → 标准模型
|
||||
- 需要设计判断或广泛的代码库理解 → 最强模型
|
||||
|
||||
## 处理实现者状态
|
||||
|
||||
实现子智能体报告四种状态之一。根据每种状态进行相应处理：
|
||||
|
||||
**DONE：** 进入规格合规性审查。
|
||||
|
||||
**DONE_WITH_CONCERNS：** 实现者完成了工作但标记了疑虑。在继续之前阅读这些疑虑。如果疑虑涉及正确性或范围，在审查前解决。如果只是观察性说明（如"这个文件越来越大了"），记录下来并继续审查。
|
||||
|
||||
**NEEDS_CONTEXT：** 实现者需要未提供的信息。提供缺失的上下文并重新分派。
|
||||
|
||||
**BLOCKED：** 实现者无法完成任务。评估阻塞原因：
|
||||
1. 如果是上下文问题，提供更多上下文并用同一模型重新分派
|
||||
2. 如果任务需要更强的推理能力，用更强的模型重新分派
|
||||
3. 如果任务太大，拆分为更小的部分
|
||||
4. 如果计划本身有问题，上报给人类
|
||||
|
||||
**绝不** 忽略上报或在不做任何更改的情况下让同一模型重试。如果实现者说卡住了，说明有什么东西需要改变。
|
||||
|
||||
## 提示词模板
|
||||
|
||||
- `./implementer-prompt.md` - 分派实现子智能体
|
||||
- `./spec-reviewer-prompt.md` - 分派规格合规审查子智能体
|
||||
- `./code-quality-reviewer-prompt.md` - 分派代码质量审查子智能体
|
||||
|
||||
## 示例工作流
|
||||
|
||||
```
|
||||
你：我正在使用子智能体驱动开发来执行这个计划。
|
||||
|
||||
[一次性读取计划文件：docs/superpowers/plans/feature-plan.md]
|
||||
[提取全部 5 个任务的完整文本和上下文]
|
||||
[用所有任务创建 TodoWrite]
|
||||
|
||||
任务 1：Hook 安装脚本
|
||||
|
||||
[获取任务 1 的文本和上下文（已提取）]
|
||||
[分派实现子智能体，附带完整任务文本 + 上下文]
|
||||
|
||||
实现者："在我开始之前——hook 应该安装在用户级别还是系统级别？"
|
||||
|
||||
你："用户级别（~/.config/superpowers/hooks/）"
|
||||
|
||||
实现者："明白了。现在开始实现……"
|
||||
[稍后] 实现者：
|
||||
- 实现了 install-hook 命令
|
||||
- 添加了测试，5/5 通过
|
||||
- 自审：发现遗漏了 --force 参数，已添加
|
||||
- 已提交
|
||||
|
||||
[分派规格合规审查]
|
||||
规格审查者：✅ 符合规格 - 所有需求已满足，无多余内容
|
||||
|
||||
[获取 git SHA，分派代码质量审查]
|
||||
代码审查者：优点：测试覆盖好，代码整洁。问题：无。通过。
|
||||
|
||||
[标记任务 1 完成]
|
||||
|
||||
任务 2：恢复模式
|
||||
|
||||
[获取任务 2 的文本和上下文（已提取）]
|
||||
[分派实现子智能体，附带完整任务文本 + 上下文]
|
||||
|
||||
实现者：[无疑问，直接开始]
|
||||
实现者：
|
||||
- 添加了 verify/repair 模式
|
||||
- 8/8 测试通过
|
||||
- 自审：一切正常
|
||||
- 已提交
|
||||
|
||||
[分派规格合规审查]
|
||||
规格审查者：❌ 问题：
|
||||
- 缺失：进度报告（规格要求"每 100 项报告一次"）
|
||||
- 多余：添加了 --json 参数（未被要求）
|
||||
|
||||
[实现者修复问题]
|
||||
实现者：移除了 --json 参数，添加了进度报告
|
||||
|
||||
[规格审查者再次审查]
|
||||
规格审查者：✅ 现在符合规格
|
||||
|
||||
[分派代码质量审查]
|
||||
代码审查者：优点：扎实。问题（重要）：魔法数字（100）
|
||||
|
||||
[实现者修复]
|
||||
实现者：提取了 PROGRESS_INTERVAL 常量
|
||||
|
||||
[代码审查者再次审查]
|
||||
代码审查者：✅ 通过
|
||||
|
||||
[标记任务 2 完成]
|
||||
|
||||
...
|
||||
|
||||
[所有任务完成后]
|
||||
[分派最终代码审查]
|
||||
最终审查者：所有需求已满足，可以合并
|
||||
|
||||
完成！
|
||||
```
|
||||
|
||||
## 优势
|
||||
|
||||
**与手动执行相比：**
|
||||
- 子智能体自然遵循 TDD
|
||||
- 每个任务全新上下文（不会混淆）
|
||||
- 并行安全（子智能体不会互相干扰）
|
||||
- 子智能体可以提问（工作前和工作中都可以）
|
||||
|
||||
**与 Executing Plans 相比：**
|
||||
- 同一会话（无交接）
|
||||
- 持续进展（无需等待）
|
||||
- 审查检查点自动化
|
||||
|
||||
**效率提升：**
|
||||
- 无文件读取开销（控制者提供完整文本）
|
||||
- 控制者精确策划所需上下文
|
||||
- 子智能体预先获得完整信息
|
||||
- 问题在工作开始前就被提出（而非工作结束后）
|
||||
|
||||
**质量关卡：**
|
||||
- 自审在交接前发现问题
|
||||
- 两阶段审查：规格合规性，然后代码质量
|
||||
- 审查循环确保修复确实有效
|
||||
- 规格合规防止过度/不足构建
|
||||
- 代码质量确保实现良好
|
||||
|
||||
**成本：**
|
||||
- 更多子智能体调用（每个任务需要实现者 + 2 个审查者）
|
||||
- 控制者需要更多准备工作（预先提取所有任务）
|
||||
- 审查循环增加迭代次数
|
||||
- 但能及早发现问题（比后期调试更省成本）
|
||||
|
||||
## 红线
|
||||
|
||||
**绝不：**
|
||||
- 未经用户明确同意就在 main/master 分支上开始实现
|
||||
- 跳过审查（规格合规性或代码质量）
|
||||
- 带着未修复的问题继续
|
||||
- 并行分派多个实现子智能体（会冲突）
|
||||
- 让子智能体读取计划文件（应提供完整文本）
|
||||
- 跳过场景铺设上下文（子智能体需要理解任务在哪个环节）
|
||||
- 忽视子智能体的问题（在让它们继续之前先回答）
|
||||
- 在规格合规性上接受"差不多就行"（规格审查者发现问题 = 未完成）
|
||||
- 跳过审查循环（审查者发现问题 = 实现者修复 = 再次审查）
|
||||
- 让实现者的自审替代正式审查（两者都需要）
|
||||
- **在规格合规性审查通过之前开始代码质量审查**（顺序错误）
|
||||
- 在任一审查有未解决问题时就进入下一个任务
|
||||
|
||||
**如果子智能体提问：**
|
||||
- 清晰完整地回答
|
||||
- 必要时提供额外上下文
|
||||
- 不要催促它们进入实现阶段
|
||||
|
||||
**如果审查者发现问题：**
|
||||
- 实现者（同一子智能体）修复
|
||||
- 审查者再次审查
|
||||
- 重复直到通过
|
||||
- 不要跳过重新审查
|
||||
|
||||
**如果子智能体失败：**
|
||||
- 分派修复子智能体并提供具体指令
|
||||
- 不要尝试手动修复（上下文污染）
|
||||
|
||||
## 集成
|
||||
|
||||
**必需的工作流技能：**
|
||||
- **superpowers:using-git-worktrees** - 必需：在开始前建立隔离工作区
|
||||
- **superpowers:writing-plans** - 创建本技能执行的计划
|
||||
- **superpowers:requesting-code-review** - 审查子智能体的代码审查模板
|
||||
- **superpowers:finishing-a-development-branch** - 所有任务完成后收尾
|
||||
|
||||
**子智能体应使用：**
|
||||
- **superpowers:test-driven-development** - 子智能体对每个任务遵循 TDD
|
||||
|
||||
**替代工作流：**
|
||||
- **superpowers:executing-plans** - 用于并行会话而非同会话执行
|
||||
@@ -0,0 +1,26 @@
|
||||
# 代码质量审查者提示词模板
|
||||
|
||||
分派代码质量审查子智能体时使用此模板。
|
||||
|
||||
**目的：** 验证实现是否构建良好（整洁、有测试、可维护）
|
||||
|
||||
**仅在规格合规性审查通过后才分派。**
|
||||
|
||||
```
|
||||
Task tool (superpowers:code-reviewer):
|
||||
使用模板 requesting-code-review/code-reviewer.md
|
||||
|
||||
WHAT_WAS_IMPLEMENTED: [来自实现者的报告]
|
||||
PLAN_OR_REQUIREMENTS: [plan-file] 中的任务 N
|
||||
BASE_SHA: [任务开始前的提交]
|
||||
HEAD_SHA: [当前提交]
|
||||
DESCRIPTION: [任务摘要]
|
||||
```
|
||||
|
||||
**除标准代码质量关注点外，审查者还应检查：**
|
||||
- 每个文件是否有单一明确的职责和定义清晰的接口？
|
||||
- 各单元是否拆分得足以独立理解和测试？
|
||||
- 实现是否遵循了计划中的文件结构？
|
||||
- 本次实现是否创建了已经很大的新文件，或显著增大了现有文件？（不要标记已有的文件大小问题——聚焦于本次变更带来的影响。）
|
||||
|
||||
**代码审查者返回：** 优点、问题（关键/重要/次要）、评估结论
|
||||
113
.agents/skills/subagent-driven-development/implementer-prompt.md
Normal file
113
.agents/skills/subagent-driven-development/implementer-prompt.md
Normal file
@@ -0,0 +1,113 @@
|
||||
# 实现子智能体提示词模板
|
||||
|
||||
分派实现子智能体时使用此模板。
|
||||
|
||||
```
|
||||
Task tool (general-purpose):
|
||||
description: "实现任务 N：[任务名称]"
|
||||
prompt: |
|
||||
你正在实现任务 N：[任务名称]
|
||||
|
||||
## 任务描述
|
||||
|
||||
[计划中任务的完整文本 - 粘贴到这里，不要让子智能体去读文件]
|
||||
|
||||
## 上下文
|
||||
|
||||
[场景铺设：这个任务在哪个环节、依赖关系、架构上下文]
|
||||
|
||||
## 开始之前
|
||||
|
||||
如果你对以下内容有疑问：
|
||||
- 需求或验收标准
|
||||
- 方案或实现策略
|
||||
- 依赖或假设
|
||||
- 任务描述中任何不清楚的地方
|
||||
|
||||
**现在就问。** 在开始工作之前提出任何疑虑。
|
||||
|
||||
## 你的工作
|
||||
|
||||
当你确认需求清晰后：
|
||||
1. 严格按照任务指定的内容实现
|
||||
2. 编写测试（如果任务要求则遵循 TDD）
|
||||
3. 验证实现是否正常工作
|
||||
4. 提交你的工作
|
||||
5. 自审（见下文）
|
||||
6. 汇报
|
||||
|
||||
工作目录：[directory]
|
||||
|
||||
**工作过程中：** 如果遇到意料之外或不清楚的情况，**提问**。
|
||||
随时可以暂停并澄清。不要猜测或做假设。
|
||||
|
||||
## 代码组织
|
||||
|
||||
你在能一次性放入上下文的代码上推理效果最好，文件聚焦时编辑也更可靠。
|
||||
请牢记：
|
||||
- 遵循计划中定义的文件结构
|
||||
- 每个文件应有单一明确的职责和定义清晰的接口
|
||||
- 如果你正在创建的文件超出了计划预期的规模，停下来并以
|
||||
DONE_WITH_CONCERNS 状态报告——不要在没有计划指导的情况下自行拆分文件
|
||||
- 如果你正在修改的现有文件已经很大或很混乱，小心操作
|
||||
并在报告中将其标注为疑虑
|
||||
- 在已有代码库中，遵循已建立的模式。像一个好的开发者那样
|
||||
改善你接触的代码，但不要重构你任务范围之外的东西。
|
||||
|
||||
## 当你力不从心时
|
||||
|
||||
说"这对我来说太难了"完全没问题。劣质的工作比不做更糟。
|
||||
上报不会受到惩罚。
|
||||
|
||||
**遇到以下情况时停下来上报：**
|
||||
- 任务需要在多个有效方案之间做架构决策
|
||||
- 你需要理解提供内容之外的代码但找不到答案
|
||||
- 你对自己的方案是否正确感到不确定
|
||||
- 任务涉及计划未预期的现有代码重构
|
||||
- 你一直在逐个读文件试图理解系统但没有进展
|
||||
|
||||
**如何上报：** 以 BLOCKED 或 NEEDS_CONTEXT 状态汇报。具体描述
|
||||
你卡在哪里、尝试了什么、需要什么帮助。
|
||||
控制者可以提供更多上下文、用更强的模型重新分派，
|
||||
或将任务拆分为更小的部分。
|
||||
|
||||
## 汇报前：自审
|
||||
|
||||
用全新的视角审查你的工作。问自己：
|
||||
|
||||
**完整性：**
|
||||
- 我是否完全实现了规格中的所有内容？
|
||||
- 我是否遗漏了任何需求？
|
||||
- 是否有我没处理的边界情况？
|
||||
|
||||
**质量：**
|
||||
- 这是我最好的工作吗？
|
||||
- 命名是否清晰准确（匹配事物做什么，而非怎么做）？
|
||||
- 代码是否整洁且可维护？
|
||||
|
||||
**纪律：**
|
||||
- 我是否避免了过度构建（YAGNI）？
|
||||
- 我是否只构建了被要求的内容？
|
||||
- 我是否遵循了代码库中的已有模式？
|
||||
|
||||
**测试：**
|
||||
- 测试是否真正验证了行为（而非只是 mock 行为）？
|
||||
- 如果要求了 TDD，我是否遵循了？
|
||||
- 测试是否全面？
|
||||
|
||||
如果在自审中发现问题，在汇报前就修复。
|
||||
|
||||
## 汇报格式
|
||||
|
||||
完成后汇报：
|
||||
- **状态：** DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT
|
||||
- 你实现了什么（或尝试了什么，如果被阻塞）
|
||||
- 你测试了什么以及测试结果
|
||||
- 修改了哪些文件
|
||||
- 自审发现（如果有）
|
||||
- 任何问题或疑虑
|
||||
|
||||
如果你完成了工作但对正确性有疑虑，使用 DONE_WITH_CONCERNS。
|
||||
如果你无法完成任务，使用 BLOCKED。如果你需要
|
||||
未提供的信息，使用 NEEDS_CONTEXT。绝不默默产出你不确定的工作。
|
||||
```
|
||||
@@ -0,0 +1,61 @@
|
||||
# 规格合规审查者提示词模板
|
||||
|
||||
分派规格合规审查子智能体时使用此模板。
|
||||
|
||||
**目的：** 验证实现者是否构建了所要求的内容（不多不少）
|
||||
|
||||
```
|
||||
Task tool (general-purpose):
|
||||
description: "审查任务 N 的规格合规性"
|
||||
prompt: |
|
||||
你正在审查一个实现是否与其规格匹配。
|
||||
|
||||
## 要求的内容
|
||||
|
||||
[任务需求的完整文本]
|
||||
|
||||
## 实现者声称构建了什么
|
||||
|
||||
[来自实现者的报告]
|
||||
|
||||
## 关键：不要信任报告
|
||||
|
||||
实现者完成得疑似过快。他们的报告可能不完整、
|
||||
不准确或过于乐观。你必须独立验证所有内容。
|
||||
|
||||
**不要：**
|
||||
- 相信他们关于实现内容的说法
|
||||
- 信任他们关于完整性的声明
|
||||
- 接受他们对需求的解读
|
||||
|
||||
**要做的：**
|
||||
- 阅读他们写的实际代码
|
||||
- 逐行对比实际实现和需求
|
||||
- 检查他们声称已实现但实际遗漏的部分
|
||||
- 寻找他们未提及的多余功能
|
||||
|
||||
## 你的工作
|
||||
|
||||
阅读实现代码并验证：
|
||||
|
||||
**缺失的需求：**
|
||||
- 他们是否实现了所有被要求的内容？
|
||||
- 是否有他们跳过或遗漏的需求？
|
||||
- 是否有他们声称可用但实际未实现的功能？
|
||||
|
||||
**多余/不需要的工作：**
|
||||
- 他们是否构建了未被要求的内容？
|
||||
- 他们是否过度工程化或添加了不必要的功能？
|
||||
- 他们是否添加了规格中没有的"锦上添花"功能？
|
||||
|
||||
**理解偏差：**
|
||||
- 他们是否以不同于预期的方式解读了需求？
|
||||
- 他们是否解决了错误的问题？
|
||||
- 他们是否实现了正确的功能但方式不对？
|
||||
|
||||
**通过阅读代码来验证，而非信任报告。**
|
||||
|
||||
报告：
|
||||
- ✅ 符合规格（如果经过代码检查后一切匹配）
|
||||
- ❌ 发现问题：[具体列出缺失或多余的内容，附带 file:line 引用]
|
||||
```
|
||||
Reference in New Issue
Block a user