# 主导实施（监控模式） ## 概述这是协调 Epic 内所有故事的 TDD 实施的主导技能。 **所有难度级别的故事都委托给代理**，并且领导不直接接触代码。 sprint-status.yaml 仅更新此 Lead（单个写入点）。 ## 何时使用 * `bf-lead-orchestrate` 在史诗循环中生成 * 不要直接打电话。 ## 先决条件 * 故事文件：`docs/stories/{TICKET}-story-*.md`（目前由 Epic 所有） * `docs/sprint-status.yaml` * `docs/conventions.md`（如果存在） * 如果重做修改：`docs/reviews/{EPIC-ID}-modification.md`（人工修改说明） ## 错误处理 * S/M Story 代理生成失败：如果重试一次后仍失败，则该故事将被视为卡住（在设置 `status: in_progress`、设置 `ralph_stuck: true` 后，stuck.md 中会记录“代理生成失败”）。在“完成”信号中，在列表中包含“完成（卡住：{STORY-ID}）”，以便编排将其视为“已跳过”。 * L/XL Story Sub-Lead 生成失败：退回到独立 Sonnet 代理（与 S/M 相同的方法） * 无法写入 sprint-status.yaml：遵循 CLAUDE.md 的 Read-yq-Verify Recover 程序（git checkout → 重试一次 → 如果失败，向 Orchestrate 报告“错误：sprint-status 更新失败”） ## 说明 ### 1\.初始加载 **yq先决条件检查**（第一次）：命令 -v yq >/dev/null 2>&1 || { echo "❌ yq 未安装。安装：brew install yq"; 1号出口； } * 阅读属于当前史诗的所有故事文档。 * 阅读 `docs/conventions.md`。 * 如果重新执行修改：请阅读“modification.md”以检查修改说明和目标Story。 * 阅读“docs/sprint-status.yaml”来检查每个故事的难度级别和状态。 * 带有“状态：完成”的故事将被跳过。 * 只有具有“status: todo”或“in_progress”的故事才有资格。 ### 1b。约定部分过滤阅读 conventions.md 后，确定要传递给每个 Story 的相关部分。 **核心部分（始终包括）：**架构、命名、测试、代码风格 **关注区域部分（根据故事文件路径过滤）：** 故事文件路径模式|包括部分 ---|--- `src/components/`、`src/pages/`、`src/views/`、`src/layouts/`、`src/hooks/`、`*.tsx`、`*.vue`、`*.svelte`、`app/` (Next.js) |用户界面模式 `src/api/`、`src/routes/`、`src/controllers/`、`src/middleware/`、`routes/`、`controllers/`、`server/` | API模式 `src/models/`、`src/entities/`、`src/repositories/`、`prisma/`、`migrations/`、`src/db/`、`drizzle/` |数据库模式 `src/auth/`、`src/security/`、`src/guards/`、`middleware/auth*` |安全模式 `Dockerfile`、`.github/`、`docker-compose*`、`infra/`、`deploy/`、`.env*` |基础设施模式 **过滤规则：** 1. 如果 conventions.md 中没有关注区域部分，则整个内容按原样传递（向后兼容）。 2. 如果故事的技术说明中没有要更改的文件，则交付全部内容（安全回退）。 3. 如果存在匹配的关注区域，则仅提取核心区域+匹配的关注区域并内联下发。 4. 将每个“##”标题视为一个部分，直到下一个“##”标题。 **内联交付格式：** 【项目约定】以下是与此故事相关的项目约定。整个大会在 Epic 审查期间由大会警卫队进行检查。 {提取的部分内容} [图书馆参考] 下面是库 API 参考，供实现此 Story 时参考。如果与项目约定发生冲突，则以约定为准。 ### {库名称} {在上下文中查看的相关 API 文档摘录7} ### {库名称2} {在上下文中查看的相关 API 文档摘录7} （在 1c 中搜索 Library Reference。如果没有搜索结果，请忽略整个 [Library Reference] 部分。） ### 1c。图书馆参考文献查找过滤 conventions.md 后，准备要传递给每个 Story 的库引用。 **文库提取：** 1. 查看 Story 技术说明中的“主库”项。 2. 如果指定了库，则使用 context7 搜索每个故事最多 3 个库。 3. 如果没有指定库，则跳过此步骤。 **context7 查找过程（每个库）：** 1. 使用 `resolve-library-id` 检查库 ID。 2.使用“query-docs”搜索Story AC相关的API文档。 * 查询是基于故事的 AC 构建的（例如“使用 zod 模式进行表单验证”、“使用 next.js 应用程序路由器进行服务器操作”） * Story AC 特定的查询比通用查询更有效。 3. 从搜索结果中仅提取**与Story AC直接相关的API/模式**（禁止投递整个文档）。 **后备：** * `resolve-library-id` 失败（未找到库）：跳过该库。 * `query-docs` 失败或结果为空：跳过库。 * context7 无法连接到 MCP 服务器：跳过整个步骤，仅传递约定。 * 所有后备都是正常操作。图书馆参考资料是补充材料，而不是必需的先决条件。 ### 2\.型号（由乐团确定）该 Lead 的模型在生成时由 `bf-lead-orchestrate` 指定： * 在 Epic 中包含 L/XL 故事时的作品 *十四行诗如果只是S/M ### 3\.故事代理生成各种难度级别的故事都委托给代理。潜在客户不直接接触代码。 #### S/M 故事 → 独家经纪人（十四行诗） * 每个故事生成 1 个十四行诗代理。 * 如果 `.ralph-progress/{STORY-ID}.json` 存在，则从该文件读取初始 retry_count/approaches_count 并传递（当从先前的中断中恢复时）。 * 发送给代理的信息： * 故事文档内容（AC、技术说明） * 与约定相关的部分（从 1b 过滤的内嵌文本） * 库参考（从 1c 检索的内嵌文本，如果存在） * 重新执行修改时：modification.md中相关Story的修改指令原文 * Ralph Loop 说明（请参阅下面的“故事代理的 Ralph Loop 说明”） * 现有的 retry_count/approaches_count （如果有的话 — 从上次中断中恢复的值） * **“不要修改 sprint-status.yaml”** * **"报告为 `"done"` \+ commit hash + retry_count + attempts_count 或 `"stuck"` \+ stuck.md + retry_count + attempts_count"** #### L Story → 副主管（作品）+ 实施者（十四行诗） * 每个故事产生 1 个 Opus 副主角。 * 传递给副主管的信息： * 故事文档内容 * 与约定相关的部分（从 1b 过滤的内嵌文本） * 库参考（从 1c 检索的内嵌文本，如果存在） * 更正说明（如有） *“生成一个十四行诗实现者并继续实施” *“根据问题解决协议进行协调”（见下文） *拉尔夫·循环说明 * **“不要修改 sprint-status.yaml”** * **"报告为 `"done"` \+ commit hash + retry_count + attempts_count 或 `"stuck"` \+ stuck.md + retry_count + attempts_count"** #### XL Story → 副队长（Opus）+ 3+ 队友 * 每个故事产生 1 个 Opus 副主角。 * 传递给副主管的信息： * 故事文档内容 * 与约定相关的部分（从 1b 过滤的内嵌文本） * 库参考（从 1c 检索的内嵌文本，如果存在） * 更正说明（如有） *“派出 3 名以上的队友来分担实施、集成和审查角色。” *“通过讨论验证设计后继续实施。” *“根据解决问题的协议进行协调。” *拉尔夫·循环说明 * **“不要修改 sprint-status.yaml”** * **"报告为 `"done"` \+ commit hash + retry_count + attempts_count 或 `"stuck"` \+ stuck.md + retry_count + attempts_count"** ### 4\.并行执行规则 **默认为并行。** 在故事文档的技术注释中检查要更改的文件，如果不满足以下顺序条件，请在一个响应中同时发送多个任务工具调用以并行生成它们。 **顺序执行条件**（只有满足该条件才顺序执行）： * 文件重叠：两个故事的目标文件中存在相同的文件 * 指定的依赖关系：在故事文档中指定对其他故事的依赖关系。 * 共享文件冲突：更改以下文件的故事被视为“重叠” * 锁定文件：`package-lock.json`、`yarn.lock`、`pnpm-lock.yaml`、`Gemfile.lock`、`poetry.lock`、`go.sum` * 共享设置：`tsconfig.json`、`webpack.config.*`、`vite.config.*`、`.env.*` * 自动生成文件：`schema.prisma`→`@prisma/client`，数据库迁移文件 * 当 Story 代理需要更改锁定文件（安装新的依赖项等）时：将 Story 从并行组中分离出来，单独或顺序运行。 ### 5\.监控回路 sprint-status.yaml 更新遵循 CLAUDE.md 的 **Read-yq-Verify** 协议。从每个 Story 代理接收完成信号： **当收到“完成”+提交哈希值时：** * 更新 sprint-status.yaml（直接由 Lead 使用 `yq -i` 命令）： yq-i' ....status = "完成" | ....tdd = "完成" | ....model_used = "十四行诗" | .<票据>.<史诗>.<故事>.ralph_retries = 1 | .<票据>.<史诗>.<故事>.ralph_approaches = 0 | ....ralph_stuck = false ' 文档/sprint-status.yaml * `model_used`: 实际使用的模型策略 (`"sonnet"` / `"opus-lead"` / `"opus-lead+3"`) * `ralph_retries`：代理报告的重试次数。 * `ralph_approaches`：代理报告的方法转换数量。 **当收到“stuck”+stuck.md时：** * 更新 sprint-status.yaml： yq-i' ....ralph_stuck = true | .<票据>.<史诗>.<故事>.ralph_retries = 3 | .<票据>.<史诗>.<故事>.ralph_approaches = 2 ' 文档/sprint-status.yaml * 将 stuck.md 保存到 `docs/reviews/{STORY-ID}-stuck.md`。 * **不要 git commit** — 文档/输出在第 4 阶段存档中集体提交。 * **其他故事继续**（即使有一个故事卡住，其余的也不会停止）。 * **卡住的故事的`status`不变** — 当orchestration自动判断它时，它会更改为`skipped`。等到所有故事都完成（完成或卡住）。 ### 6\.完成信号完成所有故事后，向编排报告： **没有卡住的故事：** * `"done"` \+ sprint-status.yaml 路径 **卡住的故事：** * `“完成（卡住：{STORY-ID}，{STORY-ID}）”` \+ sprint-status.yaml 路径 + 卡住.md 路径退出（上下文破坏）。 ** ** ## 故事代理的 Ralph Loop 说明这些是要交付给 Story 代理的 TDD 指南。代理严格遵循这些说明。 ### TDD 周期 1. **编写单元测试**（基于AC） 2. **红色确认**：运行测试→确认失败 * 修复测试代码，如果它没有按预期失败 3. **实施** 4. **绿色勾**：重新运行测试→确认通过 * 如果失败，请按照下面的护栏重试 5. **重构**（如有必要，检查以保持绿色） 6. **git commit** : `[{TICKET}] {简短描述}` * **`docs/` 子文件不包含在提交中**（不包括 sprint-status.yaml、story 文档等） 7. **向领导报告完成情况**： `"done"` \+ commit hash + `retry_count` \+ `approaches_count` ### 拉尔夫环护栏 **a) 最大重试次数：5** * 绿色验证失败→实施修改→重新执行最多重复5次。 * `retry_count` 从 0 开始，每次失败加 1。 **b) 卡住检测** * 对于每次故障，记录错误信息的核心内容（错误类型+发生文件）。 * 如果连续两次出现与前一次尝试具有相同根本原因的错误，则切换方法： 1.重新检查测试代码的期望值是否错误 2. 重新检查故事文件以查看 AC 分析是否正确。 3.从根本上改变实现策略（应用不同的算法/模式） * `approaches_count` 从 0 开始，每次转换加 1。 **c) 进度文件日志（用于崩溃恢复）** * 每次重试后，在`.ralph-progress/{STORY-ID}.json`中记录当前状态： { “重试次数”：2， “approaches_count”：1， "last_error_type": "类型错误", “last_error_file”：“src/auth/login.ts” } * 当代理崩溃后 bf-resume 恢复时，此文件用于恢复 Ralph Loop 计数。 * 完成故事（“完成”）或报告卡住后删除文件。 * **仍然不要修改 sprint-status.yaml** — 该文件仅用于 ralph-progress。 **d) 当超出限制时→“卡住”报告** * 当达到 `retry_count >= 5` 时立即中断循环。 * **写stack.md:** # 卡住报告：{STORY-ID} ## 重试次数：{retry_count}/5 ## 方法转换次数：{approaches_count} ## 尝试过的方法 1. {访问 1} — {错误摘要} 2. {访问 2} — {错误摘要} ## 最后一个错误 {完整错误输出} ## 更改的文件 {已更改文件列表} * 删除 `.ralph-progress/{STORY-ID}.json` * 向领导报告： `"stuck"` \+ stuck.md 路径 * 一起报告 `retry_count` 和 `approaches_count`。 ### 问题解决协议（适用于 L/XL 故事的副队长/队友） 1. **队友直接对话**：直接用`SendMessage`提出质疑/同意/补充 * 同意 → 仅向副主管报告结论 2. **未达成协议时的子牵头仲裁**：根据项目方向进行判断（conventions.md） * 由副主管决定确认 3. **仍然没有达成一致→丢弃（记录）**：不再使用代币 ### 特工团队失败时的后备方案 (L/XL) * 任务工具错误（代理创建失败）：回退到独立 Sonnet 代理（与 S/M 相同的方法） * 队友超过 10 分钟没有回复：除有问题的队友外，继续进行其余操作。 * 异常进程终止：回退到独立的 Sonnet 代理 ## 输出格式 * 更新sprint-status.yaml（此Lead是实现阶段唯一的写入点） * 将“完成”或“完成（卡住）”信号传递给编排。

Bf 铅具

包含技能