# Aile Subagent Dev > 面向团队工作流的子代理开发技能（阶段3）。在用户明确要求使用 Codex subagents 执行已批准计划，且任务适合按职责或文件边界拆分时使用。 - Skill: `zhucl1006/aile-subagent-dev` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add zhucl1006/aile-subagent-dev` - Raw SKILL.md: https://api.skillmd.com/api/skills/zhucl1006/aile-subagent-dev/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: zhucl1006 (https://skillmd.com/u/zhucl1006) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/zhucl1006/aile-subagent-dev --- # Aile：子代理驱动开发（aile-subagent-dev） ## 来源原 Skill - 来源：superpowers 子代理开发能力（已迁移为 aile-only） - 团队改写：重构为面向 Codex subagent 的执行技能，明确输入为 `analysis.md` + 选定计划文件，并由主线程负责编排、审查与汇总 ## 概述 本技能用于团队阶段 3 的计划执行，但它不是“默认执行模式”。 - 输入：`docs/plans/{Story-Key}/analysis.md` + 选定的计划文件 - 输出：按计划完成实现、验证、双阶段审查与最终汇总 - 角色分工：主线程做控制器；Codex subagent 负责实现、核对、审查等可拆分工作 核心原则： - 必须同时读取 `analysis.md` 与计划文件，不能只看 `plan.md` - 只有用户明确要求使用 subagent 模式时，才派发 Codex subagents - 控制器负责读取上下文、拆任务、判定并行/串行、汇总结果 - 子代理只接收与自己任务相关的 Task Package，不自行通读整份计划 - 先做规格合规审查，再做代码质量审查 ## Codex Subagents 对齐 本技能对齐 Codex subagent 官方能力与使用原则： - 子代理适用于复杂、可拆分、可并行的执行任务 - 是否真的派发 subagent，取决于主线程是否明确发起 - 内置角色优先使用 `worker`、`explorer`、`default` - 主线程负责 orchestration，子代理负责 bounded task 因此，本技能的前提是： - 用户明确要求使用 `aile-subagent-dev` - 或用户明确要求“用 subagent / 子代理模式执行计划” - 当前任务已经有阶段 2 产物：`analysis.md` 与计划文件 ## 工作流程概览 ``` 项目初始化：aile-docs-init（创建文档） ↓ 需求分析：aile-requirement-analysis（输出 analysis.md） ↓ 计划制定：aile-writing-plans（输出 plan.md / plan-{n}.md） ↓ 执行开发：aile-executing-plans 或 aile-subagent-dev ↓ 交付总结：aile-delivery-report ``` ## 何时使用 适用场景： - 已经有可执行的 `analysis.md` 与计划文件 - 用户明确要求使用 Codex subagent 模式 - 计划可以按职责、模块或文件边界拆分 - 主线程更适合做控制器，而不是亲自串行完成全部编码细节 不适用场景： - 用户没有明确要求 subagent 模式 - 任务强耦合、顺序依赖非常强，不适合拆分 - `analysis.md` 或计划文件缺失 - 只是小改动，主线程直接完成更简单 ## 与 `aile-executing-plans` 的边界 两者都属于阶段 3 的“执行计划”技能，但执行模式不同。 **`aile-executing-plans`：** - 单主代理模式 - 主线程按批次推进任务 - 更适合强耦合、串行依赖明显、需要频繁人工检查点的计划 **`aile-subagent-dev`：** - Codex subagent 编排模式 - 主线程读取 `analysis.md` + 计划文件，构造 Task Package 后派发子代理 - 更适合复杂、可按职责拆分、存在并行空间的计划 选择原则： - 主线程自己分批做完更直接：用 `aile-executing-plans` - 需要“控制器 + 多子代理”协作执行：用 `aile-subagent-dev` ## 输入契约 ### 必读文件 1. `docs/plans/{Story-Key}/analysis.md` 2. 计划文件： - 若用户明确指定：使用指定文件 - 若存在 `plan-{序号}.md`：使用最大序号文件 - 否则使用 `plan.md` ### 控制器读取要求 - 控制器在开始阶段一次性读取 `analysis.md` 与选定计划文件 - 从两份文件中提取需求边界、验收标准、任务拆解、依赖关系、验证命令 - 之后通过 Task Package 向子代理分发上下文，避免每个子代理重复读完整文档 ## Subagent 角色选择 默认优先考虑 Codex 内置角色： - `worker` - 负责编码、修复、补测试、执行验证 - 默认承担 implementer - `explorer` - 负责只读分析、规格核对、证据提取、差异核查 - 默认承担 spec reviewer - `default` - 负责综合判断、跨任务质量评审、最终汇总 - 默认承担 code quality reviewer 或 final reviewer 如果当前系统还提供其他可用角色或自定义 subagent，控制器必须先分析其能力，再决定是否使用。不要机械地固定只用三种内置角色。 角色选择流程： 1. 先识别当前系统可用的 subagent 角色 2. 判断每个角色的主要能力边界： - 是否擅长写代码 - 是否擅长只读分析 - 是否擅长综合评审 - 是否有特定领域能力，例如前端、测试、架构、数据、性能 3. 将任务类型映射到最合适的角色 4. 若没有更合适的系统角色，再回退到内置 `worker` / `explorer` / `default` 5. 角色变了，职责边界不能变： - implementer 负责实现与验证 - spec reviewer 负责规格核查 - code quality reviewer 负责质量审查 选择原则： - 写代码、改测试、修缺陷：优先 `worker` - 读代码、对照 `analysis.md` / 计划文件核查实现：优先 `explorer` - 做综合结论、全局质量判断、最终收口：优先 `default` - 若系统存在更专业的角色，且其能力边界与任务更匹配，则优先选“更匹配的系统角色” 示例： - 如果系统有专门的测试 reviewer 或 QA reviewer，可优先承担质量审查 - 如果系统有架构 reviewer，可优先处理跨模块设计一致性检查 - 如果系统有前端/后端/数据方向 implementer，可按任务域派发给对应角色 若仓库后续提供自定义 subagent，可替换默认角色，但职责边界不能变。 ## Task Package 规范 每次派发子代理前，控制器都要构造最小充分的 Task Package，至少包含： - 任务编号与标题 - 任务目标与范围 - 来自 `analysis.md` 的需求边界、风险、验收标准 - 来自计划文件的任务步骤、依赖、约束 - 允许修改的文件范围 - 禁止修改或需谨慎处理的区域 - 验证命令与完成判定 - 前序任务产物或依赖说明 Task Package 原则： - 给子代理“做事所需的完整上下文”，但不要塞整份计划 - 控制器负责裁剪上下文，避免任务漂移 - 并行任务必须具备清晰的文件边界或写入边界 ## 执行流程 ### 第 1 步：装载上下文 1. 读取 `analysis.md` 2. 选择并读取计划文件 3. 校验两份文件是否一致： - 需求边界是否冲突 - 任务是否覆盖验收标准 - 验证命令是否足够支撑完成判定 4. 建立执行看板，标记依赖、可并行项、阻塞项 ### 第 2 步：决定调度策略 按以下顺序判断： 1. 是否存在前置依赖 2. 是否会写同一文件集 3. 是否适合并行 4. 每个任务应该使用哪种 subagent，以及是否存在比内置角色更匹配的系统角色 若多个实现任务会修改同一文件集，则必须串行。 ### 第 3 步：派发 implementer 对每个可执行任务： 1. 构造 Task Package 2. 派发 `worker` implementer 3. 要求 implementer： - 若存在阻塞疑问，先提问再动手 - 仅实现任务范围内内容 - 运行计划要求的验证 - 完成后先做自检，再回报结果 ### 第 4 步：规格合规审查 implementer 回报后，控制器派发 spec reviewer： - 默认使用 `explorer` - 对照 `analysis.md`、计划文件、验收标准、测试要求进行核查 - 必须直接阅读代码与验证结果，不信任 implementer 的口头回报 若发现问题： - 退回同一 implementer 修复 - 修复后重新做 spec review - 直到规格合规通过 ### 第 5 步：代码质量审查 规格合规通过后，再派发 code quality reviewer： - 默认使用 `default` - 若只是窄范围差异核查，也可使用 `explorer` - 关注可维护性、一致性、测试有效性、实现复杂度、边界处理 若发现问题： - 退回 implementer 修复 - 修复后重新做质量审查 - 直到质量通过 ### 第 6 步：任务完成与收口 每个任务通过后： - 更新执行看板状态 - 记录验证证据 - 决定是否释放后续依赖任务 所有任务完成后： - 视复杂度决定是否派发一次 final reviewer - 汇总实现结果、验证结果、残余风险 - 进入 `aile-delivery-report` ## 子代理提示模板 建议按以下模板派发： - [implementer-prompt.md](/Users/zhuchunlei/work/01_code/ailesuperpowers/skills/aile-subagent-dev/implementer-prompt.md) - [spec-reviewer-prompt.md](/Users/zhuchunlei/work/01_code/ailesuperpowers/skills/aile-subagent-dev/spec-reviewer-prompt.md) - [code-quality-reviewer-prompt.md](/Users/zhuchunlei/work/01_code/ailesuperpowers/skills/aile-subagent-dev/code-quality-reviewer-prompt.md) 这些模板面向 `spawn_agent` / `send_input` 的消息编排，而不是旧式“让子代理自己读文件”的做法。 ## 相关技能 - `aile-writing-plans`：生成 `analysis.md` 与计划文件 - `aile-executing-plans`：非 subagent 的计划执行模式 - `aile-delivery-report`：执行完成后的交付收尾 ## 危险信号 绝不要这样做： - 用户没有明确要求 subagent，却擅自派发 Codex subagents - 只读取计划文件，不读取 `analysis.md` - 让子代理自己通读 `analysis.md` 或整份计划文件 - 在规格合规通过前提前进入代码质量审查 - 并行派发多个会写同一文件集的 implementer - 子代理未运行验证就宣称完成 - 用 implementer 自检替代正式审查 - 跳过返工后的复审 遇到以下情况应停止并重新判断： - `analysis.md` 与计划文件冲突 - 任务无法拆出清晰边界 - 并行拆分会造成明显冲突 - 验证命令无法证明任务完成 ## 记住 - `aile-subagent-dev` 是“Codex subagent 执行模式”，不是默认执行模式 - 主线程是控制器，负责读取 `analysis.md` 与计划文件、构造 Task Package、派发与汇总 - 子代理应拿到定制上下文，而不是自己去读完整文档 - 规格合规先于代码质量 - 与 `aile-executing-plans` 的差别，不在“是否执行计划”，而在“是否使用 Codex subagent 编排”