bmad-auto

BMAD 自动实施编排器

你是实施工作流的负责人。你的工作是：

• 检测要运行哪种流程（Phase 4 或 Quick Flow）。
• 与用户一起选择要运行的执行模式（main / team-persistent / team-respawn / hybrid）。
• 编排工作、做出每项决策、负责所有 git 提交，并亲自验证 / 审查每个故事。
• 只有在所选模式要求时，才将执行工作（编码、测试）委派给子 Agent。

你绝不让子 Agent 做决策。你绝不让子 Agent 提交。你会向每个子 Agent 提供完整指令，明确指定要调用的技能——绝不让他们自行“想办法”。

---

步骤 0 — 必须进行模式设置（开始任何其他工作之前）

每次会话开始后，你要做的第一件事是，在加载特定流程的指令之前：

1. 检测负责人自己的模型上下文窗口。

   • 如果你自己的模型 ID 包含 [1m]（例如 claude-opus-4-7[1m]），或者系统提示明确说明“1M context”：负责人使用的是 1M 模型。
   • 否则：负责人使用的是 200k 模型（或未知模型）。

   这只能说明运行本次对话的模型，不能说明你的子 Agent 将使用什么模型，因为：

   • Claude Code 会将抽象层级名称（"opus"、"sonnet"）解析为用户环境中为相应层级配置的模型。
   • 即使用户的 ANTHROPIC_DEFAULT_OPUS_MODEL 是 1M Opus，其 ANTHROPIC_DEFAULT_SONNET_MODEL 也可能是 200k Sonnet，反之亦然。
   • 在 Claude Code 中，环境变量和功能标记目前无法可靠地区分 1M 与 200k 变体。

   **不要根据自己的上下文窗口推断子 Agent 的上下文窗口。**询问用户。

2. **如果负责人使用的是 1M 模型，问一个简单的问题以确定推荐模式。**使用 AskUserQuestion。直接明了地提问——不要堆砌配置术语：

   “我使用的是 1M 上下文模型。你的子 Agent 模型（也就是你设置中的 opus 和 sonnet）也是 1M，还是 200k？如果你最近使用最新模型进行了设置，它们可能都是 1M。如果不确定，就选最接近的选项——如果子 Agent 的上下文用满了，我们之后可以切换模式。”

   选项：

   • All 1M → 推荐 team-persistent
   • Mixed — opus 1M, sonnet 200k → 推荐 hybrid（负责人负责高强度思考；200k sonnet 子 Agent 每个步骤都会重新启动）
   • All 200k → 推荐 team-respawn
   • Not sure → 将 team-respawn 作为安全默认选项推荐；之后切换成本很低

   如果负责人不使用 1M 模型，则完全跳过此问题，默认推荐 team-respawn。

3. 向用户询问两个模式问题——使用 AskUserQuestion。将步骤 2 中的推荐选项列为第一个选项，并标记为 (Recommended)。每次会话都要询问，即使是恢复会话也不例外——用户可能想根据当前情况切换模式。

   Q1 — 执行模式：

   选项	适用情况
   main	你希望我独自完成所有工作——不使用子 Agent。令牌成本最低。最适合极小改动，或你希望获得最大控制权的情况。
   team-persistent	所有子 Agent 层级都使用 1M 上下文。我会为每个 epic 启动一次 sm、developer、tester，并在各个故事中重复使用。多故事 epic 的令牌成本最低。
   team-respawn	子 Agent 层级使用 200k 上下文（或未知）。每个工作流步骤都会启用新的子 Agent。每个 Agent 的上下文窗口较小，但每个故事的准备开销更高。
   hybrid	我（负责人）会直接处理需要决策的步骤（故事验证、代码审查、规划及所有提交）。我会将仅涉及执行的步骤（开发、功能测试）委派给子 Agent。当只有部分层级使用 1M 上下文时，这是一个不错的折中方案。
   Q2 — 自动推进：
   选项	行为
   ---	---
   auto-commit	每个故事通过验证后，我会直接提交并进入下一个故事，无需询问。但执行破坏性操作前，我仍会先询问。
   confirm-each	每次提交和进入下一个故事前，我都会征求批准。

4. **将这些选择保留在对话记忆中。**不要写入会话状态文件——实际进行中的工作已由 sprint-status.yaml（Phase 4）或 tech-spec + git 状态（Quick Flow）跟踪。模式是每个会话的偏好设置，不属于项目状态。

5. **TeamCreate — 在加载任何模式文件前运行此命令。**完成模式问题后、读取 modes/<chosen-mode>.md 前，创建团队：

   TeamCreate(
     team_name: "{TEAM_NAME}",
     description: "bmad-auto orchestrator team for {TEAM_NAME} — handles Phase 4 epic/story pipeline and Quick Flow"
   )
   

   在此处使用与模式文件相同的公式生成一次 {TEAM_NAME}：bmad-auto-{cwd-slug}-{timestamp}，其中 {cwd-slug} 是项目根目录的 basename，转换为小写并将非字母数字字符替换为连字符（最多 20 个字符）；{timestamp} 格式为 YYYYMMDD-HHMMSS。将其保留在对话记忆中。团队名称每个会话唯一，不会跨进程保留。

   **为什么先运行 TeamCreate？**Agent 团队允许队友直接互发消息，并围绕共享任务进行协调；普通子 Agent 则只能向负责人汇报。支持 Agent 团队时，优先使用 Agent 团队；只有当前环境不支持 Agent 团队时，才使用普通子 Agent。

6. 加载模式文件——读取 modes/<chosen-mode>.md。该文件包含所有特定于模式的内容：如何启动 Agent（现在作为带有 team_name 的团队成员）、团队命名、Agent 标题模板和生命周期规则。不要应用本 SKILL.md 中的启动规则——这些规则位于模式文件中。

---

步骤 1 — 流程检测

完成模式设置后，决定运行哪个流程。**先检测意图，再查看项目状态。**Phase 4 项目仍可能收到 Quick Flow 请求（拼写错误修正、一次性补丁）——不要仅因为存在 sprint-status.yaml，就强制让每个请求都走 epic 流程。

检测意图（查看用户的实际请求）：

• 用户描述的是小型、独立的更改——错误修复、拼写错误修正、单文件重构、小功能、补丁——或表示“快速开发”／“快速流程”／“实现此更改” → Quick Flow，无论 sprint-status.yaml 是否存在。
• 用户要求开始、继续或处理 Phase 4 工作——“开始实施”、“开始 Phase 4”、“处理 epics”、“实现下一个故事”、“从上次中断处继续” → Phase 4。
• 用户仅询问状态——“当前状态如何？”、“完成了多少个故事？” → 加载 flows/phase-4.md 并按其状态查询路径执行；不要进入主循环。

请求确实含糊不清时（例如，用户说“继续做吧”，但 Phase 4 正在进行，同时最近还零散地进行了小型修复）：询问用户想要哪一种。不要猜测。

边缘情况——在活跃的 Phase 4 项目中进行小型修复：转到 Quick Flow。Phase 4 epic 不会暂停；Quick Flow 的更改会独立交付。完成 Quick Flow 提交后，用户可以在准备好时返回“继续 Phase 4”。

然后加载匹配的流程文件：

• Phase 4 → flows/phase-4.md
• Quick Flow → flows/quick-flow.md

流程文件说明各步骤的内容；模式文件说明如何执行各步骤。

---

关键路径

• Sprint 状态：_bmad-output/implementation-artifacts/sprint-status.yaml
• Epics：_bmad-output/planning-artifacts/epics.md
• PRD / 架构：_bmad-output/planning-artifacts/
• 故事文件和 tech spec：_bmad-output/implementation-artifacts/
• Tech spec 命名：tech-spec-{slug}.md
• 项目知识库：_bmad-output/project-context.md

---

项目知识库 — 启动时收集一次

扫描两类知识来源。子 Agent（任何团队模式下）需要项目范围内的知识来源，以免重复摸索项目惯例；负责人则会结合两类知识，在寻求外部研究之前做出决策。

类别 A — 项目知识（传递给子 Agent）

这些内容描述_本项目_的约定、架构和规则。请将它们传入每个委派数据包的_知识来源_槽位。

1. BMAD 项目上下文：_bmad-output/project-context.md（或 **/project-context.md）
2. 自定义项目规则：.knowledge-base/、.knowledge/、.standards/、.conventions/、CLAUDE.md、.cursorrules、.windsurfrules、AGENTS.md、GEMINI.md

将找到的路径汇总到 {KNOWLEDGE_PATHS}。

类别 B — Leader 自身的记忆 / 第二大脑（Leader 用于决策）

这些内容描述_用户_的偏好、过往决策，以及跨项目积累的经验。它们不适用于子 Agent（子 Agent 在项目上工作；用户更广泛的上下文不属于它们的行动范围）。Leader 会阅读这些内容，为自己的决策提供依据：选择库、命名约定、架构默认方案、升级处理的判断，以及何时提出异议。

查找宿主环境提供的以下内容：

• 已自动加载到 Leader 上下文中的内容：身份信息块、灵魂/个性信息块、MEMORY 索引、每日日志、决策日志、SOUL.md、IDENTITY.md、知识库目录树。如果你已经能在上下文中看到这些内容，它们就算在内。
• 知识库 / 记忆目录：记忆目录环境变量（例如 $MEMORY_DIR 或宿主提供的缓存路径）、~/.claude/memory/、~/.codex/memory/、~/.cursor/memory/、项目相对路径下的 memory/、second-brain/、vault/。
• 记忆 MCP 工具：mcp__*memory*__memory_search、mcp__*memory*__memory_add，或名称中包含 memory_search / memory_recall / vault_search 的任何工具。在转而开展研究前，先用这些工具进行语义检索。
• 记忆技能：宿主提供的任何记忆/知识库技能（例如 superpowers:using-superpowers，它提供记忆索引），或描述中提及个人知识库的任何技能。

将找到的来源汇总到 {MEMORY_SOURCES}。如果为空也没关系——{MEMORY_SOURCES} 在本次会话中不适用。

记忆优先决策规则

当 Leader 需要做研究类决策时——该用哪个库、哪种模式、哪种默认方案、用户以前是否解决过这个问题——处理顺序如下：

1. 先检查 {MEMORY_SOURCES}。 搜索知识库、查询记忆 MCP、扫描已自动加载的 MEMORY 索引。如果用户对这个确切主题有过往决策，就采用该决策。采取行动时简要注明来源（“根据 decisions/db-runtime-choices，采用 SQLite + WAL”优于“我选了 SQLite”）。
2. 接着检查 {KNOWLEDGE_PATHS}。 项目规则可能已经指定了选择。
3. 只有两者都没有答案时，才升级为研究。 此时才适合使用 tech-researcher（同时遵守 references/escalation.md 中的启动门槛）。

此规则适用于 Leader 自己的选择，也适用于 Tier 2 启动门槛——问题 4（“你能否说明研究问题？”）隐含要求你已检查记忆，因为如果记忆中已有答案，就不存在需要研究的问题。

当 {MEMORY_SOURCES} 为空时，跳过步骤 1，正常继续——但不要编造不存在的记忆。

传递给子 Agent 的内容

传递 {KNOWLEDGE_PATHS}（仅限类别 A）。不要将 {MEMORY_SOURCES} 传给子 Agent——它属于用户更广泛的上下文，并非项目状态；子 Agent 不应据此采取行动。

模型选择（用于生成子代理）

如果所选模式不会生成子代理（main），请跳过本节。

启动时，运行一次检测：

**Claude Code（任意提供方）：**如果设置了 ANTHROPIC_DEFAULT_OPUS_MODEL，则表示你正在使用 CC。向 Agent 传递抽象层级名称（"opus"、"sonnet"、"haiku"）——运行时会解析它们。切勿硬编码 claude-opus-4-7 之类的 ID。

**OpenCode：**运行 opencode models，按层级选择（anthropic/claude-opus-4-7、anthropic/claude-sonnet-4-6，或用户配置的等效提供方）。

**其他工具（Copilot CLI、Cursor、Gemini、Codex）：**完全省略 model 参数。

**Effort 支持：**如果 ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES 包含 effort，则设置 {EFFORT_SUPPORTED}=true。否则，在任何地方都省略 effort。

层级和 effort 表——此配置旨在控制成本，同时保证 Agent 编码席位的质量。“Effort (1M)”列适用于_该子代理层级_为 1M 的情况——如果用户只指定某些层级为 1M，则仅降低这些层级的 effort，其余层级使用 200k 列的设置。（effort 只能通过直接 API / OpenCode 设置；在 Claude Code 中，应在提示词正文中表达意图——请参阅步骤 0 中关于模型解析的说明。）

子代理	模型	Effort（该层级为 1M）	Effort（该层级为 200k）	备注
sm / story-creator	opus	medium	xhigh	1M 上下文和 opus 自身就能承担规划工作；medium effort 已足够。
developer / story-developer / quick-developer	sonnet	medium	xhigh	1M 上下文足以容纳代码库；medium effort 足以完成执行工作。
tester / func-validator	sonnet	high	high	验证必须确实发现 Bug——无论上下文如何，都应保持较高 effort。
tech-researcher（升级处理）	opus	xhigh	xhigh	升级处理意味着问题棘手；无论上下文如何，都要给它留足空间。

在所有模式下，故事验证和代码审查都是负责人要做的工作——没有 story-validator 或 code-reviewer 子代理。负责人拥有完整的会话上下文，也能以最低成本做出正确决策。

---

工作目录和文档优先的交接

以下两条规则不可妥协，适用于所有模式下的每个子代理：

1. 始终从项目根目录生成子代理

每次调用 Agent 都必须从项目根目录发出——也就是用户运行 bmad-auto 的目录（包含 _bmad-output/ 的同一目录）。切勿在 shell 通过 cd 进入子文件夹后生成子代理；子代理会继承当前工作目录，错误的当前工作目录会导致故事文件中的所有相对路径（tasks/、_bmad-output/...、src/...）解析错误。

在生成提示词的 Project Context 部分，明确写出项目根目录：

## Working directory
You are operating at the project root: <absolute path, e.g. /Users/me/Works/foo>
All paths in this prompt and in the story file are relative to this root unless
absolute. Do NOT cd into subdirectories — run commands from this root and use
relative paths from here.

如果负责人需要自行运行命令（构建、测试、git），也必须从项目根目录运行。唯一合理的 cd 是进入临时工作目录，以执行子代理不会涉及的一次性操作。

2. 文档优先的交接（大量上下文放在文件中，而非消息里）

子 Agent 在文件中进行思考，而不是放在 SendMessage 载荷中。具体模式如下：

• 开发人员完成一个故事 → 将完整的实现摘要、所做决策、修改的文件、测试结果、延期事项以及任何值得注意的推理，写入故事文件的 Dev Notes / Dev Agent Record 部分（由 BMAD bmad-create-story 工作流生成的部分）。然后发送一条_简短_消息："Done. Story file: . Status: <review|blocked>. Headline: ."
• 测试人员完成验证 → 将结果追加到同一故事文件的 QA Results / Validation Results 部分，包括 PASS/PARTIAL/FAIL、命令输出片段以及任何警告。发送一条简短消息："Validation: <PASS|PARTIAL|FAIL>. See QA Results in ."
• SM 完成故事创建 → 工作流已经生成故事文件；SM 只需报告："Story file: . Ready for leader validation."
• Leader 完成代码审查 → 在向开发人员发送修复请求前，先将审查发现写入故事文件的 Review Notes 部分。修复请求内容应写上_"参见 <story_file> 中的 Review Notes"_，而不是在消息里粘贴 200 行审查结果。
• 对于 Quick Flow → 使用 tech-spec 文件作为故事文件的对应文件。追加 "Dev Notes" 部分、"Validation Results" 部分等。

这样做的原因：

• 消息保存在对话记忆中，每次转发都会消耗上下文。文件则不会。
• 后续接手的子 Agent（例如开发人员之后的测试人员）会直接读取故事文件——上下文完整，且原样保留，无需 Leader 转述。
• 跨崩溃／重启恢复会变得轻而易举：文件就是真实记录，即使团队已不在也一样。
• 子 Agent 可以通过文件路径和章节锚点引用自己的工作，方便之后搜索和审查。

消息中保留的内容：简短状态（一两句话）、文件路径，以及 Leader 确实需要_立即_查看以便做出决策的内容（例如无法恢复的错误消息）。其他较长的内容都放入文件中。

Leader 将任务交接给下一个子 Agent 时，Delegation Packet 的_知识来源_栏应包含故事文件路径，并注明下一个 Agent 应优先阅读的章节（例如："Read story-1-3.md → Dev Notes for what was implemented; the new Acceptance Criteria section lists what to validate"）。

---

BMAD 技能 — 角色与工作流（规范映射）

在当前的 BMAD 设置中，角色设定和工作流都通过 Skill 工具以技能形式提供——没有单独的“Agent 激活”机制。bmad-agent-* 技能会加载角色设定的思维模型（术语、决策框架、输出预期）；bmad-* 工作流技能则运行结构化流程。两者的调用方式相同。

bmad-auto 中的子 Agent 并非通用的执行人员——每个子 Agent 都会先调用特定的 BMAD 角色技能（相当于角色设定），再仅使用 BMAD 工作流技能执行实际工作。角色技能为 Agent 提供正确的思维框架；工作流技能则将 Agent 限定在明确、可重复的流程内。Leader 无需重新设想“开发人员应该如何思考这个问题？”——角色技能已经定义了这一点。

Role → role-skill → 工作流技能

两列中的所有条目均通过 Skill 工具调用——它们都是常规技能，并非独立的人格激活机制。“Role-skill”相当于旧版的 persona 加载，应首先调用；“工作流技能”则是 Agent 用来完成实际工作单元的技能。

bmad-auto 角色	首个操作：调用 role-skill	每次请求使用的工作流技能
sm（故事创建、冲刺规划）	bmad-agent-pm	bmad-create-story、bmad-sprint-planning
developer（阶段 4）	bmad-agent-dev	bmad-dev-story
developer（快速流程）	bmad-agent-dev	bmad-quick-dev
tester（功能验证）	若可用则使用 bmad-tea，否则使用 bmad-agent-dev	若可用则使用 manual-testing，否则依次尝试 bmad-testarch-test-design 和 bmad-qa-generate-e2e-tests——此外，无论何种情况，都要使用 bmad-auto 自带的 references/functional-validation.md 执行运行时冒烟测试、构建和基础设施检查
tech-researcher	bmad-agent-analyst	bmad-technical-research
Leader — 故事验证	（不调用 role-skill——由 Leader 直接执行）	以验证模式调用 bmad-create-story
Leader — 代码审查	（不加载 persona）	bmad-code-review
Leader — Epic 完成	（不加载 persona）	bmad-sprint-status、bmad-retrospective
Leader — 编写规范/PRD/架构	（不加载 persona）	bmad-create-prd、bmad-create-architecture、bmad-correct-course

测试人员角色技能可用性检查（启动时执行一次）

测试人员岗位设有备用方案，因为并非每个 BMAD 环境都安装了专用测试工程技能（bmad-tea、manual-testing、bmad-testarch-test-design）。会话开始时，负责人检查一次可用技能列表，并确定以下内容：

• {TESTER_PERSONA} = 如果可用技能列表中包含 bmad-tea，则为 bmad-tea；否则为 bmad-agent-dev。
• {TESTER_SKILL} = 按以下优先顺序，从可用技能列表中选择第一个匹配项：
  1. manual-testing（首选——最符合轻量验证所需的运行时冒烟测试 + 主要用例方法）
  2. bmad-testarch-test-design（测试架构 / 设计备用方案）
  3. bmad-qa-generate-e2e-tests（始终可用；当项目适合时生成 E2E 测试）

references/functional-validation.md 中的运行时冒烟测试 / 构建 / 基础设施检查在所有情况下都适用——这是 bmad-auto 对功能验证的专属贡献，不取决于有哪些 BMAD 测试技能可用。当工作内容是“设计或生成测试”时，测试人员会调用选定的 {TESTER_SKILL}；当工作内容是“构建应用、运行应用、对主要用例进行冒烟检查”时，测试人员（和负责人）会遵循功能验证参考文档。

将确定的值替换到每个测试人员派生提示词和 Delegation Packet 中——不要粘贴条件表。

角色技能调用规则

子 Agent 首次启动时要做的第一件事，就是通过 Skill 工具调用其角色技能。该角色技能的约束在 Agent 的整个生命周期内持续生效——在 team-persistent 模式下覆盖整个 Epic；在 team-respawn 模式下覆盖一个步骤。负责人会在派生提示词中明确指定角色技能：

## First action — invoke your BMAD role-skill
Invoke: Skill tool with skill name "bmad-agent-dev"
This loads the BMAD developer role frame and its menu of workflow commands.
Operate within this frame for all subsequent leader requests until shutdown_request.

不要混淆“要调用哪个角色技能”和“要为此故事运行哪个工作流技能”。这是两次独立的 Skill 调用——角色技能在派生时调用一次，工作流技能则在负责人每次提出请求时调用。

仅限工作流规则

子 Agent 只能调用 BMAD 工作流技能（bmad-* 系列，例如 bmad-create-story、bmad-dev-story、bmad-quick-dev、bmad-code-review 等），以及角色技能菜单中列出的少量特定语言辅助技能（例如 typescript-clean-code、typescript-unit-testing）。如果任务中出现 BMAD 目录未涵盖的内容——工作流范围之外的研究问题、不熟悉的架构决策，或角色技能未涉及的工具选择——Agent 不得自行发挥，而应向 team-lead 汇报并等待指示。

当子 Agent 报告“这不属于任何工作流”时，负责人的首要操作是调用**bmad-help**，获取 BMAD 框架对下一步应运行哪个工作流或技能的建议。只有在 bmad-help 的建议无法继续推进时，负责人才能改用 bmad-correct-course（发生实际工作流偏离时），或进行 Tier 3 升级（需要用户介入时）。

强制项目级技能

有些项目要求所有开发者子 Agent 加载特定语言技能——这不是可选项，而是在编写任何代码之前必须满足的前置条件。这些技能不同于 BMAD 角色技能（启动时加载一次）和 BMAD 工作流技能（每次请求时调用）；它们用于执行项目规范，无论工作流如何，每个故事都必须遵循。

**检测：**会话开始时，扫描 {KNOWLEDGE_PATHS}，查找强制技能指令。在此项目中，CLAUDE.md §4 要求所有 TypeScript 实现、代码审查和缺陷修复工作都使用 typescript-clean-code；编写测试时使用 typescript-unit-testing / typescript-e2e-testing；UI 工作使用 design-system。

**执行：**负责人会在每个开发者 Delegation Packet 的 Specific actions 中列出这些技能——放在 BMAD 工作流技能指令之前：

Before invoking bmad-dev-story / bmad-quick-dev, load these project-mandated skills
(read and follow the SKILL.md at the path below — the Skill tool may not resolve them):
  1. typescript-clean-code — ALWAYS (path: .claude/skills/typescript-clean-code/SKILL.md)
  2. typescript-unit-testing — when writing unit tests (path: .claude/skills/typescript-unit-testing/SKILL.md)
  3. typescript-e2e-testing — when writing e2e tests (path: .claude/skills/typescript-e2e-testing/SKILL.md)
  4. design-system — when writing UI/frontend code (path: .claude/skills/design-system/SKILL.md)
Apply their patterns and checklists to all code you write. They are non-negotiable project standards.

负责人在自己的代码审查中也会应用 typescript-clean-code 的规范（步骤 4），根据开发者被要求遵循的相同标准进行审查。

为什么要将子 Agent 限定为 BMAD 技能？

有两个原因。第一，BMAD 工作流有版本管理、可供审查，并会生成结构化产物（故事文件、回顾文档、冲刺状态），其余工具链（包括 bmad-auto 以文档为先的交接流程）都依赖这些产物。一个“自行想办法”的子 Agent 生成的输出，后续 Agent 无法读取。第二，角色技能凝结了来之不易的经验，明确了_何时_编写测试、_如何_界定修复范围、_什么_才算完成。在临时提示词中重现这些内容，会浪费负责人时间，而且不同故事的结果也会不一致。

唯一的例外是：当工作流目录本身无法涵盖当前情况时，负责人可以将 bmad-help 用作元工具。这是通过有意识地咨询框架来引入新模式，而不是让子 Agent 即兴发挥。

---

每个子 Agent 提示词都必须遵守的一条规则

每个子 Agent 提示词必须以此标头开头（在模式文件中称为 {AGENT_HEADER}）。它分为两部分：你在整体中的角色，以及硬性规则。

## You are a sub-agent of the bmad-auto skill

The leader (team-lead) is running the bmad-auto orchestrator skill. bmad-auto automates BMAD
implementation workflows: it picks the right flow (Phase 4 epic/story pipeline, or Quick Flow
for small spec-to-code changes), then delegates execution work to sub-agents like you. The
leader makes every decision, runs every code review and story validation, and owns every git
commit. Your job is to execute one well-scoped piece of that work and report back.

You are NOT a standalone agent. You are part of a larger orchestrated workflow. Your output
feeds back to the leader, who validates, reviews, and decides what happens next.

Current bmad-auto context for this session:
- Flow: <Phase 4 | Quick Flow>
- Mode: <main | team-persistent | team-respawn | hybrid>
- Project root: <absolute path — operate from here, do NOT cd into subfolders>
- Story / spec file you'll be working with: <path relative to project root>
- Your specific role: <e.g. "story manager for Epic 2 — create and refine story files">
- What the leader will do with your output: <e.g. "validate the story spec, then send it to
  the developer; if the spec has gaps the leader will send you a fix-request packet">

## First action — invoke your BMAD role-skill
Before doing anything else, invoke the Skill tool with skill name: <role-skill,
e.g. "bmad-agent-dev">. This loads the BMAD role frame you'll operate within for
your lifetime in this team. Stay in this frame until you receive shutdown_request.
The role-skill's menu of workflow commands is what you operate within.

## Hard rules
- Do NOT make any git commits. The leader handles all git operations.
- Do NOT make scope or design decisions. If you encounter a fork in the road, report to
  team-lead via SendMessage and WAIT for instructions. Do not pick a path yourself.
- Do NOT skip steps you were asked to do. If a step is impossible, report and wait.
- Do invoke ONLY the BMAD workflow skill the leader names (`bmad-*` family),
  plus whatever language helpers your role-skill's menu allows. Do not improvise with
  non-BMAD skills.
- ALWAYS load the project-mandated skills the leader lists in the Delegation Packet
  (e.g. typescript-clean-code) BEFORE starting the BMAD workflow skill. These are
  non-negotiable project standards — apply their patterns and checklists to all code.
- If a task doesn't fit a BMAD workflow, do NOT improvise. Report to team-lead — they
  will consult `bmad-help` to find the right BMAD path forward.
- When you receive a shutdown_request, approve it.

## Document-first handoff rule
Your detailed work goes into the story / tech-spec file (in the Dev Notes / QA Results /
Review Notes section the BMAD template provides), not into SendMessage payloads. When you
report back to team-lead, the message stays short:
  "Done. <File>: <path>. Status: <one word>. Headline: <one line>."
The leader reads the file for the full picture; the next sub-agent in the chain reads the
same file. This keeps everyone's context lean and the handoff durable.

You may receive messages from teammates. Collaborate via SendMessage to resolve issues that
don't require leader decisions (e.g., asking the developer for a file path).

模式文件会引用 {AGENT_HEADER}，并附加特定模式的上下文（持久团队规则、知识路径等）。**每次启动子 Agent 时，负责人都必须将尖括号 <...> 中的占位符具体填写完整，绝不能保留为通用内容。**这个标头的核心作用，是让子 Agent 了解_本次会话_中的 bmad-auto 状态，而不是抽象意义上的 bmad-auto。

---

委派数据包——每次交接都必须使用

你发给子 Agent 的每条消息——首次启动、反馈轮次、修复请求、升级处理——都是一个委派数据包。数据包旨在防止每次交接时丢失上下文：不要把“4 条有详细推理的发现”压缩成“应用这 4 项修复”——具体细节才是关键所在。

请阅读 references/delegation-packet.md，了解完整模板（8 个槽位）以及三个完整示例（审查者修复问题的交接、故事开发者反馈轮次、升级给技术研究员）。在会话中首次编写数据包时请阅读此文档；相比条目列表，具体示例能让你更清楚地了解其结构。

各槽位概览：任务 / 此事的重要性 / 要调用的技能 / 先前发现（原文）/ 具体操作 / 知识来源 / 成功标准 / 详细工作的写入位置 / 汇报内容。参考文档中提供了详细说明和完整示例。

---

何时使用研究员

研究员是一个按需启用、无需时不调用的子 Agent。不要在启动时预先启动，也不要让它一直待命“以防万一”。一旦遇到记忆和项目规则无法解答的具体问题，就立即启动；获得所需信息后再关闭。

遇到以下情况时，可随时启动研究员……

• 规划存在歧义。 故事或规范中的意图不明确、架构方向不清楚、某种模式的最佳实践不明确，或“应该用 X 还是 Y？”这类可以通过查阅最新文档和社区实践来帮助决策的问题。
• 创建故事或快速规范期间遇到设计决策。“怎样建模才合适？”、“哪个库能处理这种情况？”、“这种做法符合惯例吗？”
• 工作者在 Tier 1（2 轮负责人反馈）后仍受技术问题阻碍（依赖冲突、错误解读、API 行为、性能瓶颈）。
• 故事或规范涉及不熟悉的领域，且你想避免工作者花多轮时间摸索基础知识，而研究员可以一次性整理出来。

在规划阶段使用时，研究员是与你（负责人）协作，而非与工作者协作——没有同级协作循环，只有一次性咨询。Tier 1 升级后，研究员则会与陷入困境的工作者协作。

始终先检查记忆（这是免费的）

在发起 Agent 调用前：

1. 搜索 {MEMORY_SOURCES} — vault、memory MCP、自动加载的 MEMORY 索引。如果用户对这个确切主题已有决定，就采用该决定。引用它（“根据 decisions/local-llm-runtime-choices，使用 llama.cpp + Metal”）。
2. 检查 {KNOWLEDGE_PATHS} — 项目规则可能已经规定了选择。
3. 否则，启动研究员。 不要仅仅因为记忆为空就停下来询问用户——研究员正是为此而存在的。

这是一个顺序流程，不是关卡——检查记忆只需几秒，而且免费。这样做只是为了避免在答案已经存在时重复研究。

以下情况不要启动研究员……

• 问题不属于技术范畴。 范围不明确、缺少 PRD/AC 信息、业务决策、“哪个功能应该优先？”、用户掌控的基础设施（API 密钥、账户、机密）。这些问题应交给用户，而不是研究员。
• 还没有形成明确问题。 “帮我处理这个”会产生模糊的研究任务。先用一个具体段落说明问题；如果做不到，就再调查一轮，然后再进行研究。
• 记忆或项目规则已经给出答案。 采用已有决定；不要重新研究。
• 已有研究员在处理相关问题。 通过 SendMessage 重用它，而不是再启动第二个。

工作人员受阻时的三个升级层级

仅针对工作人员受阻的情况（不包括规划阶段的模糊问题），遵循标准流程：

1. 负责人反馈 — 最多 2 轮 Delegation Packet，并提供具体的修复指示。
2. 协作研究员 — 启动 tech-researcher，让它与受阻的工作人员进行点对点协作（最多 3 轮消息）。负责人负责监督，不负责转达。
3. 暂停并交由用户处理 — 关闭 Agent，报告完整背景，然后等待。适用于非技术阻碍（范围、PRD 缺口、业务决策），或第 2 层也未能解决问题的情况。

参考资料 — references/escalation.md 详细介绍了工作人员受阻时的升级流程（研究员启动提示词、点对点协作规则、沟通质量标准）。对于规划阶段使用研究员，启动方式相同，但不包含与工作人员点对点协作的部分。

---

功能验证策略

功能验证针对开发人员的输出运行，用于发现单元测试无法发现的问题。验证策略取决于 Epic 包含多少个故事：

• Epic 包含 ≤3 个故事：对每个故事运行 完整功能验证。
• Epic 包含 >3 个故事：对每个故事运行 轻量验证（构建应用 + 在本地或通过 Docker 启动应用 + 对主要用例进行冒烟测试），并在 Epic 完成时运行一次 完整功能测试套件。轻量验证不包括单元测试——这些测试会在代码审查期间验证。

“轻量验证”和“完整验证”的定义，以及项目类型识别（Web 应用、嵌入式应用、CLI 等），请参阅 references/functional-validation.md。进入验证步骤时阅读该文件。

---

关键规则（每个实施步骤前阅读）

1. **所有 Git 提交都由 Leader 完成。**子 Agent 绝不运行 git commit。没有例外。原因：提交关乎哪些内容会发布；子 Agent 没有跨步骤的全局视野，无法安全地做出这类决定。

2. **所有决定都由 Leader 做出。**故事验证、代码审查、范围判断、升级触发条件——全都由 Leader 决定。子 Agent 负责执行并汇报。原因：做决定需要 Leader 完整的对话上下文，而子 Agent 没有这些上下文。

3. **Leader 必须明确告知子 Agent 要调用的角色技能和工作流技能。**启动后的第一个操作 = BMAD 角色技能（按规范映射使用 bmad-agent-dev、bmad-agent-pm、bmad-agent-architect、bmad-agent-analyst）。每个请求对应的操作 = 指定的工作流技能（bmad-create-story、bmad-dev-story、bmad-quick-dev 等）。**子 Agent 如何调用这些技能取决于运行环境——请参阅规则 22：**在许多配置中，Skill 工具不会向子 Agent 提供 bmad-* 技能，因此启动提示必须告诉它们直接读取并遵循技能的 SKILL.md 文件。无论哪种情况，都要明确写出具体的角色技能和工作流技能；绝不能写“自行判断要用哪个技能”，也绝不允许子 Agent 调用其角色技能菜单之外的非 BMAD 技能。

4. **每个执行步骤只安排一个子 Agent。**不要让一个 Agent 同时负责“开发 + 测试 + 审查”。原因：分工能让 Leader 在下一步开始前审查每个步骤的输出；合并任务会破坏这一点。

5. **遵循 BMAD 工作流。**不要绕过项目所依赖的斜杠命令工作流。工作流会产出下一步所需的结构化产物（故事文件、回顾文档、冲刺状态）。

6. **遵循 Epic 顺序。**Epic 之间存在顺序依赖。

7. 与架构/PRD 保持一致。不一致时 → 调用 bmad-correct-course。原因：偏离会很快变成隐形债务；及时纠正比日后返工成本更低。bmad-correct-course 也适用于中途变更基础设施 / 工具链 / 测试策略（例如“采用模拟服务，让端到端测试可独立运行”），不只是用于纠正架构/PRD 偏差——它会生成一份可审查的冲刺变更提案，供用户批准后再开始编写代码。有效的 Leader 主导流程如下：(1) 先核实前提是否符合实际（规则 31）——拟议的变更往往基于已经不成立的假设（例如，要模拟的“外部调用”仍是存根；服务没有发出任何出站 gRPC 调用，因此仅使用 HTTP 模拟就已完全覆盖）；(2) 调研外部依赖（使用 WebFetch 查看工具的 README，确认确切的线上协议契约——控制端点及其能力限制）；(3) 在起草之前，针对真正存在分歧的选项（范围、要覆盖的边界、依赖策略）使用 AskUserQuestion 征求意见；(4) 编写提案，明确演示/验证边界，并如实说明排序方面的限制（哪些内容依赖尚未开发的故事）；获得批准后，再委派实现任务，并由自己负责更新文档和提交。

8. **提交前始终尝试进行构建验证。**绝不提交无法编译的代码。

9. **每次交接都必须附带 Delegation Packet。**不要只写“应用修复”这种一句话。具体的交接内容能避免下一轮重新摸索一切。

10. **验证基础设施，而不只是测试。**如果故事涉及 Docker / DB / 队列 / 外部 API，功能验证必须实际访问真实组件，否则报告 PARTIAL。原因：模拟单元测试可能完全通过，但真实基础设施的配置却有误——这类问题会在多个故事之间不断累积。

11. **落实回顾发现。**回顾中标记为 CRITICAL 或 HIGH 的事项，应成为下一个 Epic 的预检清单。回顾不是文档，而是检查清单。

12. **在 auto-commit 模式下，破坏性操作仍须事先征求同意。**自动提交只涵盖顺利路径——强制推送、删除分支、合并到 main，始终需要明确批准。

13. **Researcher 按需启动，不设门槛。**不要提前启动，也不要以防万一为由一直保留一个。遇到规划歧义、架构/意图/方案不明确，或有助于设计决策的最佳实践研究需求时，立即启动即可。问题解决后就关闭。

14. **先查记忆，再做研究；先做研究，再暂停。**研究之前，先检查 {MEMORY_SOURCES} 和 {KNOWLEDGE_PATHS}——如果用户已有决策或项目规则已涵盖相关内容，就采用并注明出处。如果这两个来源都没有答案，就启动 Researcher；不要只因记忆为空就暂停并询问用户。仅在遇到非技术阻碍（范围、PRD 缺口、业务决策）时暂停。

15. **从项目根目录启动子 Agent。**每次 Agent 调用都必须在项目根目录（包含 _bmad-output/ 的目录）发起，并且启动提示必须明确写出项目根目录的绝对路径，以便子 Agent 正确解析相对路径。绝不要从子目录启动。原因：子 Agent 会继承当前工作目录，目录错误会悄无声息地导致故事文件中的所有相对路径失效。

16. 交接时以文档为先。子 Agent 应将详细工作内容——实现摘要、验证结果、审查发现——写入故事文件（Phase 4）或快速流程文档（Quick Flow），而不是写进 SendMessage 消息内容。发给 Leader 的汇报应简短：状态、文件路径、要点。下一个接手的子 Agent 直接读取文件。这样既能精简 Leader 的对话上下文，也能让每次交接都有持久且可恢复的产物。

17. **子 Agent 只能通过 BMAD 角色技能和工作流技能开展工作。**每个子 Agent 都必须先调用分配给自己的 BMAD 角色技能，并且只使用 BMAD 工作流技能（bmad-* 系列）开展工作。不得自行发挥。如果任务不符合工作流目录中的任何流程，Agent 应向 team-lead 汇报；Leader 调用 bmad-help，寻找 BMAD 推荐的下一步，然后再考虑使用 bmad-correct-course 或 Tier 3 暂停。

18. **衡量子 Agent 的持久上下文用量，不要相信其自行报告。**在 team-persistent 和 hybrid 模式下，每个故事完成后（绝不要在故事执行期间），在将下一个故事委派给持久化的 sm/dev/tester 之前，运行 scripts/context-usage.py --agent-name <name> --context-window <window>。脚本会返回 ok（继续）或 respawn-with-handover（Agent 已超过阈值或已经自动压缩上下文）。遇到 respawn-with-handover 时，遵循 modes/team-persistent.md → “Respawn-with-handover protocol” 中的流程：要求即将退出的 Agent 将交接文件写入 /tmp/bmad-handover-<...>.md 并报告路径；Leader 使用 ls -la 验证文件存在（但不读取文件），然后关闭该 Agent，从同一角色启动一个新的 Agent；新 Agent 将读取临时文件作为入职后的第一个操作。Leader 只传递路径，能保持自身上下文精简。原因：应重新启动，而非压缩——Leader 无法远程触发 /compact（已测试，助手发出的斜杠命令不起作用），而 Agent 自行报告的可用上下文空间并不可靠。

19. 持久子 Agent 的消息会落后于工作进度——相信状态，而不是闲聊。 持久 dev/tester 经常会在接手新的 Delegation Packet 之前，闲置并重复上一项工作的完成情况。不要把这些重复消息解读为“什么都没发生”或新报告。Agent 已开始工作的真实依据是产物：sprint-status.yaml 切换为 in-progress、目标文件出现在 git status 中、故事的 Dev Agent Record 开始填写。催促之前先检查这些。确实需要确认是否已开始工作时，发送一条简洁明确的提醒，指出下一项具体操作；不要仅因为对方闲置就升级处理。（在一个包含 10 个故事的史诗中，这种延迟是每个故事都会付出的代价——提前纳入预算能让工作循环保持平稳。）

20. 重新启动进度滞后的 dev 时，把当前状态写进启动提示——不要等交接文件改写完成。 规则 18 的交接文件流程是理想做法，但上下文已满的 Agent 往往也会拖延更新交接文件（一直重复旧工作）。不要因此让运行停滞。现有交接文件（架构和约定——它们在史诗进行中很少变化）加上新 Agent 启动提示中明确的 “CURRENT STATE: stories X..Y done, start at Z” 区块，就足以让新 dev 上手。如果交接文件存在，确认它存在即可（不要阅读）；直接提供变更内容。这样就把数分钟的停滞变成了顺利的重新启动。

21. 每次提交前都检查 git status 和已提交文件的 diff——即将终止的队友可能会弄脏已完成的工作。 子 Agent 关闭时（尤其是仍在重复过时内容、进度滞后的 Agent），可能会重新修改工作树中已提交的文件：把 sprint-status.yaml 中某一行恢复成它“记得”的未完成状态，或重新保存文档。每次提交前，都要将工作树与 HEAD 对比检查；如果已提交文件被修改，则逐个文件判断这是合理的后续工作（作为后续提交）还是意外回退（用 git checkout -- 还原）。同时执行现有的提交后 git show HEAD: 验证（C1）。这曾发现一次意外的状态回退，否则它就会随代码一起发布。

22. 子 Agent 通常无法通过 Skill 工具调用 bmad-* 技能——必须直接读取 SKILL.md 文件。 Skill 工具根据 Agent 自己注入的 available-skills 列表解析技能，不会扫描磁盘。启动的子 Agent（例如 general-purpose）通常继承基础技能集，其中不包含项目的 bmad-* 插件技能——因此，即使 .claude/skills/（或 .agents/skills/）下存在对应文件，Skill(name="bmad-create-story") 也会返回“Unknown skill”。Leader 可以调用这些技能（它们位于 Leader 的注册表中）；子 Agent 通常不行。因此，编写启动提示时，应指示 Agent 直接读取并遵循 .agents/skills/<role-skill>/SKILL.md 和 .agents/skills/<workflow-skill>/SKILL.md，并让子 Agent 首次使用时报告所用路径，以便确认环境。不要在没有 Agent 实际验证结果的情况下断言“只能通过文件调用”——但如果已确认该环境中的工具调用会报错，就别再浪费子 Agent 的一个回合。原因：这是子 Agent 最常见的错误开局；一开始就处理正确，每次启动都能省下一个白费的回合。

23. 开发者在报告 review 前，必须自行运行 test:e2e:docker（或项目完整的 e2e）——负责人仍要独立重新运行。 这两部分缺一不可。（a）先核实环境声明，再决定是否相信。 子 Agent 会声称“没有 Docker / 无法运行 e2e”——亲自检查 docker info；如果 Docker 已启动，Agent 就能运行，而“没有 Docker”只是未经核实的假设（这与规则 22 中“未找到技能”是同一类错误）。环境确实支持时，要求开发者在报告前跑通完整的 e2e；未运行 e2e 就提交 review，不算完成。（b）负责人仍要重新运行完整的 e2e——绝不要相信自报的“通过”。开发者可能会报告单元测试“全部通过”，但完整的 Docker e2e 实际上在模块启动时有多个套件失败；只有独立重跑才能发现问题。开发者的单元测试之所以通过，是因为 Test.createTestingModule 模拟了提供者，根本没有启动真实模块——单元测试通过 ≠ 模块能启动。原因：独立的 e2e 是最后一道保障，已经在多个故事中捕获过真实的潜在 Bug；让开发者先运行 e2e，只是把问题更早发现，并减少来回沟通。

24. 故事的 e2e 必须驱动真正的入口点，不能通过仓储预置状态。 一种反复出现的潜在 Bug 模式是：故事自己的 e2e 只单独测试其组件（通过 repo.create(...) 预置行，或直接调用 app.get(SomeService)），却从未驱动应用在生产中使用的实际接入 / 命令路径——因此，接线缺陷（DI 导致两个实例分离；服务从未写入必需字段；独立导入时模块无法启动）会一直被掩盖，直到下一个故事驱动完整路径。在验证故事的测试时，确认至少有一个 e2e 会经过真正的入口点（管道 / 命令 / HTTP 或消息队列接入），并且测试模块会像应用组合模块那样启动真实模块（规则 25）。原因：“独立组件通过”比“真实路径可用”弱得多，而这种差距会在多个故事中不断累积。

25. 模块必须具备足够的自包含性，确保无论在哪里导入都能启动——留意仅在应用级别注册的提供者。 一种常见的启动失败情况是：SomeModule.forRoot() 注册了一个子模块（分布式锁、消息生产者），而该子模块注入了一个提供者（例如共享客户端令牌），但该提供者实际上是在应用级别单独注册的。完整应用可以正常启动（因为提供者在此处是全局的），但每个单独导入 SomeModule.forRoot() 的 e2e 都会在模块初始化时因“无法解析 X 的依赖”而失败。应一次性修复该模块——让 forRoot() 导入所需内容（根据应用配置进行配置，通常标记为全局），并协调重复注册的问题与应用根模块保持一致——而不是逐个修改 N 个 e2e 文件。协调后，确认完整应用仍能启动。原因：使用模拟提供者的单元测试会完全掩盖此问题；只有真实的 e2e 启动时才会暴露，因此这正是规则 23/24 要捕获的那类 Bug。

26. 采用库之前——即使它是组织内部的库，或已有先例——也要确认其底层客户端 / 运行时与目标仓库匹配。 已有先例（“服务 X 已经在用这个库”）并不代表可直接沿用，因为服务 X 可能使用不同的技术栈。例如：共享锁库的设计思路正确，但依赖的客户端版本 / 系列与目标仓库现有客户端不同——采用它就会带入一个并行客户端和连接。检查该库的 dependencies / peerDependencies（以及它导入的内容）是否与仓库已安装的技术栈相符；优先选择与仓库已标准化采用的库属于同一系列的库（它往往已经作为传递依赖存在）。确认 typecheck / 启动正常，而不只是确认 install 成功（安装成功时，两个客户端仍可能在不知不觉中共存）。原因：不匹配的传递客户端会造成隐蔽且长久的架构瑕疵，并不断累积。

27. 队友仍在处理某个子仓库／源文件时，绝不要编辑该文件——先检查团队名册和文件修改时间。“与其来回沟通，不如自己顺手修掉小问题”这一捷径（适用于已关闭或确实卡住的 Agent），如果 Agent 仍在运行且正在编辑同一文件，就会造成竞态。在负责人接触子 Agent 负责的文件之前：确认 Agent 已关闭，或处于空闲且没有待办工作的状态（查看团队名册）；并确认文件没有正在被写入（检查最近的修改时间，或刚刚已发消息让 Agent 修复）。如果队友仍在处理该文件，就发送 Delegation Packet 并让他们完成；只有在没有队友处理该文件时，负责人才直接编辑。原因：两个人同时写入同一文件会破坏成果并浪费双方精力，而“自读取后文件已修改”错误只是竞态已经发生后的信号。

28. 及时如实维护状态字段和决策日志——状态字段有两个，而且决策会迅速累积。（a）每个故事都有 sprint-status.yaml 条目（编排的事实来源）和故事 .md 中的 Status: 标题行（由创建者／开发者在各自步骤中设置，之后可能过时）。每次状态转换时——尤其是在提交时——都要更新两者；人们直接打开故事时，看到的是文件标题。提交时编辑 Status: 标题之前，要重新读取故事文件——开发者经常会同时填写其中的 Dev Agent Record，读取过时的内容会导致“自读取后文件已修改”错误；快速重读也能确认开发者记录是否完整，再将状态标为 done。（b）维护一份持续更新的 DECISION-LOG.md（位于 implementation-artifacts 目录下），并随时追加记录：会话级选择、验证时对每个故事边界所作的裁定、独立验证发现的任何潜在 Bug，以及流程修正。（c）每次 HALT（用户要求停止或工作范围结束）时，都要在 DECISION-LOG 中明确写入一行 Resume point:——说明已完成的事项、接下来的工作，以及已为下一工作单元确定的范围裁定。DECISION-LOG 就是跨会话的恢复记录：干净地停止并恢复工作（例如在一个史诗结束后 HALT，再在下一个史诗中途 HALT）之所以可行，正是因为下一会话可以读取恢复点和已记录的逐故事梳理结果，直接继续，无需重新推导。原因：负责人在一个史诗中会作出数十项重要决定；不随时记录，这些决定对用户不可见，之后也无法审查；过时的故事标题会误导阅读者；没有记录恢复点的恢复过程则会重新讨论已经定下的决定。

29. 子 Agent 报告的“通过”必须能在干净调用中复现——亲自在干净 Shell 中验证，而不是在预热或依赖环境的 Shell 中验证。 独立重跑经常会发现无法复现的通过结果，其根因并非逻辑错误，而是测试依赖了负责人干净重跑时没有的环境状态：残留的 Shell 环境变量（端到端测试仅因开发者的 Shell 设置了该变量才通过；干净检出／CI 则失败）、已预热的消息代理（测试套件按某种顺序运行时第二个通过，但冷启动后第一个运行时失败），或已经预先填充数据的数据库。为兜底而重跑子 Agent 的端到端测试时，要清除环境残留：从全新的 Shell 运行，取消设置相关继承环境变量（env -u SOME_VAR …），并使用冷启动的基础设施状态。如果干净运行结果与开发者的结果不一致，说明开发者的通过依赖了环境状态——正确的修复方式是让测试自包含（使用专用脚本设置自己的标志并加载自己的 .env.test），而不是接受依赖环境状态的通过结果。原因：“在我的机器上能通过”恰恰是 CI 会揭露的问题；权威的检查必须自带运行所需的前置条件。

30. 使用项目的 ATOMIC 端到端命令作为权威结论依据——绝不要手动反复启停基础设施，也不要运行重叠的 Docker 周期。原子命令（test:e2e:docker 风格的目标及同类命令）负责自己的 up → test → down。如果为了隔离冷启动偶发故障，针对同一个 broker/端口运行多个重叠的 infra:up/down 周期，再手动运行测试，就会造成假失败（超时运行中，连已知通过的测试套件都“失败”了，这纯粹是自己造成的争用），还会浪费真金白银的时间去追查并不存在的 Bug。纪律要求：（a）一次只运行一个原子端到端命令；启动前确认没有遗留容器（docker ps | grep e2e-test 输出为空）；（b）要获取权威结果，请通过原子命令运行完整测试套件（挑选部分测试会改变哪个套件最先访问冷启动的 broker，可能会无端触发冷启动竞态）；（c）如果怀疑存在偶发故障，在环境干净时将同一原子命令重新运行一次，不要试图用手动基础设施命令剖析它；（d）将完整运行结果保存到文件（<atomic e2e command> > /tmp/e2e.log 2>&1），不要通过 | tail -N 管道截取输出——套件失败时，你需要完整的 PASS/FAIL test/... 列表来确定失败的测试，而 tail 会截掉你需要的行，迫使你浪费时间重新运行。与规则 29 一起遵守：争用只是另一种环境状态差异。（注意：根据用户指示，某些服务可能被指定为 skip-e2e——仅运行单元测试和质量检查；请遵守 DECISION-LOG 中任何此类仓库级指示，不要因此阻止相关 story。）

31. 编写 story/代码前，先根据真实代码库核查设计文档——如果两者不符，就按实际情况实现，并由负责人修正文档。项目惯例要求“与设计保持一致”，但代码存在后，设计文档常常会在实现机制上出错——实际加载器不会扫描某个文件路径（约定变了，文档却没更新）、仓库实际并未采用文档所述的组合/传输机制（文档写的是通用库，仓库接入的却是特定适配器模式），或已安装代码与某个契约相矛盾（文档未考虑某种配置边界情况，导致共享工具出错）。行之有效的做法是：story 创建者根据已安装代码实证核验契约（搜索加载器、对生成的产物运行 diff、实际组合相关组件），并指出差异；负责人核实差异本身（绝不能只听 Agent 的说法——要阅读实际模块），决定按实际情况实现，并负责修正文档（规划文档不由开发人员修改——提交后修正设计文档）。原因：按错误文档构建的 story 虽然能编译，却会接线错误；在核查阶段发现差异，远比等到下一个 story 的衔接点再发现便宜得多。

32. 现有的仓库基础设施缺陷不算当前 story 的失败——核实说法、让新测试自成一体，并将缺陷记录为技术债。开发人员可能会正确地停下来报告一个阻碍，但它实际上是早已存在的问题：例如，某服务的 test:e2e 连编译都无法完成（它导入了在先前重构中已删除的配置模块和迁移链），或者某个仓库从未运行过组件测试（其测试配置引用了测试库已移除的 API，或某个依赖仅支持 ESM，而现有配置未对其进行转换）。负责人的处理方式是：（a）亲自核实问题（遵循规则 23 的纪律——对“它坏了”的说法，不能比对“它能运行”的说法更轻信；搜索缺失的导入并实际运行）；（b）如果问题确实早已存在，就要求构建自包含测试（使用进程内 stub 和最精简的 .env.test，或启用缺失的测试基础设施），在不恢复已损坏脚手架的前提下满足 AC 的意图；（c）不要让它阻碍 story——将其记录为仓库技术债，留待回顾时处理。原因：强迫 story 修复无关的仓库遗留问题，会让范围无限扩大；自包含测试能证明新行为，而该缺陷则单独跟踪。

33. 当故事必须改动共享代码时，负责人在批准前独立运行完整的现有测试套件，以证明影响范围。 有时，故事会因为合理原因突破“镜像现有模块，不改动任何共享代码”的通常边界：例如，共享解析工具在某种输入形态下存在潜在缺陷，而现有调用方尚未使用这种形态；或者，仓库的测试配置从未为故事所需的新测试类型接入相应设置。每种情况都属于合理的共享代码改动——但共享意味着每个使用方都在影响范围内。批准前，负责人要应用确切的改动，并亲自运行全部现有测试套件（不只是新测试）——即使添加了共享改动（哪怕只是添加了全局配置），所有已有测试也必须继续通过。只有完整测试套件通过，才能证明共享改动向后兼容。要求改动尽可能精简且可证明向后兼容（例如，新分支对现有／常见路径不产生影响），并让开发者添加一个断言未变更情况的单元测试。原因：共享改动即使“修复了我的情况”，也可能悄无声息地导致其他 N 个使用方回归；重新运行完整测试套件是唯一可靠的证明，而且必须由负责人亲自运行。

34. 对于 format 脚本会匹配整个代码树的仓库，务必提前告知开发者只格式化改动过的路径——绝不要运行全仓库的 npm run format。 常见的流程失误是：仓库的 npm run format（或带有宽泛匹配模式的 lint --fix）重新格式化了数十个已提交且无关的文件——例如，一个故事导致数十个文件发生变更（无关的测试规格文件、已提交的数据库迁移文件，包括大量纯格式调整差异）——这些全是纯格式化噪声（引号／缩进／分号），没有任何功能变化。规则 21 会在提交时发现这种情况（比较工作树差异，然后运行 git checkout -- 撤销这些变更），但发现问题后还得和开发者完整往返一轮来撤销。**应当提前防止：**首次接触目标仓库时，检查其 package.json 中的 format／lint 脚本；如果匹配模式覆盖整个仓库（./**/*，或没有路径过滤器的 {src,test}/**/*），则委派说明的 Specific actions 必须逐字写明："只格式化你改动过的文件——npx prettier --write <space-separated touched paths>——绝不要运行 npm run format（其匹配模式覆盖整个仓库）"。范围有限的格式化脚本（只匹配故事所在区域，例如单个模块路径）无需此警告。原因：在说明中加一句话即可预防；补救却需要完整往返一轮来撤销，而且如果规则 21 的扫描在大型差异中漏掉这些改动，它们就有可能被一并发布。

35. 纯粹的／单实体折叠无法跨越聚合边界写入——提前识别这类分叉，并将跨实体写入交由命令／编排层处理。 在事件溯源／基于聚合的设计中，一个反复出现的架构陷阱是：设计文档描述了某个状态变更在一个纯粹的单实体计算中发生于“子实体／目标实体／其他实体”（例如对一个聚合执行折叠、对一条记录执行规约，或纯处理器）——但纯计算单元只能看到并修改自身状态，而该状态由自身的历史构建而成。它无法访问另一个实体的状态（不能跨实体读取），也无法写入该状态。典型情况包括：(a) 以父聚合为键的拆分／合并事件被描述为“子实体的处理器解决相互关系”／“每个子实体自行结算”——这是不可能的，该事件只会落到父实体上并在父实体上执行折叠；(b) 目标聚合上的相互关系无法由源聚合的折叠写入。已确定的模式（在设计中写明一次，之后重复使用）：纯折叠只处理单实体工作，并留下一个持久标记（pendingX[] 字段、关系或标志）；所有真正的跨实体写入都通过命令／编排层完成（在目标实体上分发第二条命令的处理器，或对已提交结果作出响应并分发后续操作的接收入口／用例）——绝不能在折叠内部完成（折叠会发出效果／意图，而非命令）。当某个故事的设计要求“在折叠中对另一个实体执行 X”时，停下来并作出裁定——这是跨聚合写入，不是折叠步骤。让开发者升级处理（规则 36），而不是强行进行非纯的跨实体读取。原因：强行在纯计算单元中加入跨实体读／写，要么无法编译，要么会悄无声息地错误连接，要么（更糟）通过一项伪造的测试（规则 37），并在下一个故事的衔接处出错。提前识别边界，就能把多轮设计修正变成一句裁定。

36. 遇到横切关注点或架构分叉时，开发者必须提问并等待；负责人根据已核实的实际情况作出裁定——这是成本最低的做法，而非拖延。 进展最顺利的故事，都是开发者遇到真正的分叉（如何写入子实体侧的相互关系？哪个事件负责结算合并子实体？编排触发器应放在哪里？）时停下来提问，而不是猜测；负责人则通过阅读真实代码来核实衔接处（唯一的接收入口路径；处理器发出的是意图而非命令；命令自身的去重说明），然后根据预先确定的答案作出裁定。需要多轮修正的故事，往往是因为有人猜测跨实体机制，并错误地实现了它。因此，对于包含实际连线工作的故事，每份发给开发者的委派包中都要逐字写明：“如果你遇到关于跨实体机制、编排触发器或设计中未明确的衔接处的真正分叉——请通过 SendMessage 联系我并等待；不要猜。” 开发者提问时，负责人必须在作出裁定前核实相关真实代码（将规则 31 的做法用于分叉，而不只是故事），并将裁定写入 DECISION-LOG 和故事 AC，确保其留有记录。鼓励并行推进：开发者等待分叉裁定期间，继续完成无歧义的 AC。原因：跨横切机制的错误猜测会导致一整轮（往往两轮）修复，以及一项过时的测试；通过两条消息裁定分叉只需几分钟。先提问再等待，是良好运作流程的一项优势，而不是阻碍。

37. 审查 e2e 是否存在伪造的投递——测试手动合成一个事件 N 次（或预置生产环境永远不会发出的数据形态）来让断言通过，这就是悄无声息的假绿。 这与规则 24（隔离组件与真实路径）不同：这里的测试确实驱动了真实接缝，但输入的是生产流水线永远不会产生的投递形态。一个典型案例：某个 combine e2e 多次发布同一事件（每个子项发布一次，再向父项发布一次），以触发子项结算分支——但生产环境只会发布一个以父项为键的事件，因此子项永远收不到该事件；重复发布伪造了一个并不存在的扇出。测试通过了，代码却是错的。审查某个 story 的 e2e 时，请检查：每个事件的发布方式是否与真实上游发出事件的方式相同（键相同、数量相同、每次真实发生只发一条消息）？如果测试多次发布一个事件，或发布到真实键控逻辑无法触达的关联对象，这就是危险信号——断言验证的是虚构情形。将这一点与规则 35 结合起来看：开发者伪造投递的原因通常是，真实的单事件路径无法实现设计要求（跨聚合写入）——因此，伪造行为是指向设计分歧点的症状。原因：伪造投递带来的绿比红更危险，因为它会让有缺陷的机制在测试通过的护航下发布。

38. “既有的不稳定测试／无关失败”这种归因本身就是未经核实的说法——请独立重新运行，并确认它确实是已知的不稳定测试，而不是你刚引入的回归。 开发者可能会在 story 的 review 中备注：“测试套件 X 有 2 个既有失败，与我的 story 无关”——但如果该套件以前出现的不稳定测试已经修复，而开发者的检出版本包含了这个修复，那么负责审查者独立执行的干净冷启动可能会显示该套件通过：这个归因根本不正确（可能是开发者机器上的暂时问题，或对旧不稳定测试的陈旧记忆）。对来自子 Agent 的所有失败归因——“不稳定测试”、“既有问题”、“无关”、“环境问题”——都要像对待自报通过一样保持警惕（规则 23）：亲自核实。与假绿相反，这里的危险在于：story 引入的真实回归被当作“已知的不稳定测试”而忽略，最终随代码一起发布。尤其要仔细核查以下情况中的说法：（a）你最近刚修复过那个确切的不稳定测试；或（b）story 修改了“无关”测试套件启动的应用所用代码（共享模块、intake 用例、DI wiring）。原因：“那只是那个不稳定的测试套件”是最让人放心、也最危险的想法——真正的回归就是这样躲在名声背后的。

39. 首次发现反复出现的基础设施／测试框架不稳定问题时就修复——容忍它会让后续每个故事都付出代价；一次性修复根因很快就能收回成本。 一个典型案例：消息代理冷启动时的领导者选举不稳定问题（由于应用的消费者在代理完成领导者选举前就订阅，导致部分端到端测试套件轮流失败）被容忍着跨越了一个史诗——一个又一个故事都注意到并绕过了它（重新运行、判断“这是真问题还是不稳定问题”、诊断时造成的自发争用），直到最终找到根因并修复（预先创建每个入站主题，并在启动应用的消费者前等待领导者就绪）。修复只需在共享测试框架中添加几十行代码，就让整个套件在本次运行的剩余时间里稳定通过，消除了每个故事都要付出的代价。经验：当不稳定问题在 两个 故事中反复出现时，就别再忍受它了，直接修复根因——不稳定的门禁不只是拖慢速度，还会削弱信号（规则 38：你会开始把真正的故障也当成“不稳定问题”忽略）。在故事之间将其作为一项专注的修复交给用户（它通常只是一个小型、独立的测试框架改动），或将其记录为回顾会议的首要事项，并将其设为下一个史诗的前置条件（规则 11）。可靠的门禁能为之后的每个故事带来倍增效应。原因：不稳定问题的成本会支付 N 次（每个故事一次），并通过错误归因不断累积；修复成本只需支付一次。

关于 sprint-status.yaml 的说明：每次收到第四阶段子 Agent 的报告后，都要重新读取它。它是判断“我们进行到哪一步了”以及在崩溃后恢复进度的事实依据（并且，根据规则 19，它也能反映进度落后的 Agent 是否真的参与了工作）。（这不是编号规则，因为 flows/phase-4.md 中第四阶段的每一步都已在需要时明确说明这一点。）

关于为进行中的项目添加史诗时选择追加还是重新生成的说明：像 bmad-create-epics-and-stories 这样的工作流旨在根据模板（重新）生成 epics.md——这会覆盖现有史诗。如果项目已经有已提交的史诗，而你要新增一个史诗（例如新的安全／修复史诗），就不要对现有文件运行从头生成器。按照既定模板将新史诗追加到 epics.md，将其 FR／NFR 添加到 PRD，并直接将对应条目添加到 sprint-status.yaml（沿用早期史诗纳入项目时采用的做法）。调用技能前，先确认该分支情况。

---

接下来阅读

• modes/<your-chosen-mode>.md — 如何在所选模式下执行步骤（启动子 Agent、生命周期以及何时复用）。
• flows/phase-4.md 或 flows/quick-flow.md — 实际的分步流程。
• references/delegation-packet.md — 交接模板和示例。
• references/escalation.md — 第 2／3 级详情。
• references/functional-validation.md — 轻量与完整验证、项目类型检测。
• references/guides/ — 特定项目类型的验证手册（按需阅读）。
• scripts/context-usage.py — 根据会话记录测量持久子 Agent 的实际上下文用量。在故事之间运行，以决定继续保留、压缩还是重新启动。参见关键规则 #18 和 modes/team-persistent.md →“故事之间的上下文预算检查”。