CX-08 Subagents 完整指南：App 中的多 Agent 协作

主线程确认目标
  -> 拆分独立子任务
  -> 指定 owner、文件范围、是否只读
  -> 并行执行互不依赖的部分
  -> 子 agent 返回证据和结果
  -> 主线程处理冲突和合并
  -> Review 面板统一检查 diff

子任务名称：
目标：
允许读取：
允许修改：
禁止事项：
输出：
完成条件：
遇到阻塞时：

这个重构涉及前端、API 和测试。请先制定分工计划，再并行处理互不重叠的部分。

修一个拼写错误。

先给出 subagent 分工计划，不要立刻改文件。
 
目标：重构认证模块。
范围：src/auth、tests/auth。
约束：不要改数据库迁移，不要引入新依赖。
分工：
- Agent A：阅读现有 auth 代码，列出风险。
- Agent B：核对官方 SDK 文档。
- Agent C：审查测试覆盖缺口。
汇总后再决定是否执行。

Worktree thread + Subagents + Review

让一个只读 subagent 使用 $tutorial-verifier skill 核对这篇教程的官方来源。

请合并各 subagent 输出：
1. 先列共同结论
2. 再列冲突点和证据
3. 标出每个建议影响的文件
4. 只选择一个最小可执行方案
5. 不要继续修改文件，等我确认

这个项目登录模块要升级。请先制定 subagent 分工计划，然后并行只读分析：
- frontend：只读 src/pages/login.tsx 和 src/components/auth/*
- backend：只读 src/api/auth/* 和 src/lib/auth/*
- test：只读 tests/auth/* 和 package.json
 
每个 subagent 只输出证据、风险和建议修改点。不要修改文件。

在 worktree 里处理登录错误提示优化。请按文件所有权拆分：
- frontend 只改 src/pages/login.tsx
- backend 只改 src/api/auth/errors.ts
- test 只改 tests/auth/login-errors.test.ts
任何 agent 发现需要改其他文件，先停下汇报。最后由主线程合并并运行 npm test -- auth。

当前 diff 已完成。请启动一个只读 review subagent，重点检查：文件所有权是否被遵守、是否有范围外改动、测试是否覆盖新增行为、是否触碰 secret 或权限配置。review agent 不要修改文件。

每个 worker 只能修改自己拥有的文件。
如果发现必须修改其他文件，先停止并汇报。
任何共享文件由主线程统一修改。
Review agent 只读，不修改文件。
最终由主线程运行测试和看 Review。

Spawn one explorer agent for the test suite.
 
Scope:
- Read package.json, test config, and failing test output.
- Do not edit files.
 
Question:
- Which tests are most relevant to this change?
- Which command should I run locally before review?
 
Return:
- 5 bullet summary
- exact commands
- files inspected

Spawn one worker agent for the documentation update.
 
Ownership:
- Only edit docs/api-auth.md and docs/api-errors.md.
- Do not edit code, tests, config, or generated files.
 
Task:
- Update the docs to match the behavior described in src/auth/errors.ts.
- Preserve existing tone and headings.
 
Verification:
- Check markdown fences and links in the two edited files.
 
Return:
- Files changed
- Summary of edits
- Any behavior questions you could not answer from source

Spawn one reviewer agent.
 
Scope:
- Review current branch diff against main.
- Read nearby code when needed.
- Do not edit files.
 
Lens:
- correctness
- security
- missing tests
 
Return:
- findings first
- file references
- severity labels: high, medium, low
- open questions

Agent A: 认为主要风险是 auth redirect。
Agent B: 认为主要风险是 missing regression test。
Agent C: 没发现安全问题，但指出日志里有 flaky test。
 
主线程应该输出：
1. 共识：auth redirect 需要补测试。
2. 分歧：是否属于安全问题还需要看威胁模型。
3. 下一步：先补 regression test，再决定是否改 redirect 行为。

请把三个 subagent 的结果合并成一个行动计划。
不要平均分配篇幅。
优先处理：
1. 有文件证据的问题
2. 多个 agent 都提到的问题
3. 会阻塞发布的问题
 
输出：
- 共同发现
- 分歧点
- 下一步最小行动
- 暂时不处理的内容和理由

Use parallel subagents for this change.
 
Worker 1:
- owns src/components/CheckoutForm.tsx
- only updates UI state and error display
 
Worker 2:
- owns src/api/checkout.ts
- only updates request validation
 
Worker 3:
- owns tests/checkout.spec.ts
- only adds or updates tests
 
Shared merge contract:
- keep ownership boundaries from the plan
- report any file that was touched outside the assigned area
- include verification evidence with each worker result
 
Main thread:
- wait for all workers
- inspect diffs
- resolve conflicts before final answer

两个 worker 都改到了 checkout validation。
请先不要继续写文件。
请分别说明：
1. 你为什么需要改这个位置
2. 你依赖的行为假设是什么
3. 你的改动和另一个 worker 的改动是否能合并
4. 最小保留方案是什么

name = "security-reviewer"
description = "Review code changes for security risks, sensitive data exposure, and unsafe external interactions."
developer_instructions = """
Review as a security-focused owner.
Prioritize concrete, reproducible issues over broad advice.
Do not edit files.
Return findings with file references and uncertainty labels.
"""
nickname_candidates = ["Sentinel", "Audit", "Shield"]

name = "fix-checkout-bug"
description = "Fix today's checkout bug in src/api/checkout.ts."
developer_instructions = "Edit checkout files and make tests pass."

name = "api-debugger"
description = "Investigate API behavior regressions and suggest minimal fixes."
developer_instructions = """
Investigate API failures by reading routes, tests, logs, and nearby code.
Prefer small fixes.
Ask the main thread before widening scope.
"""

Use subagents for read-only analysis only.
Do not run commands that modify files.
Do not request broader sandbox permissions.
If any agent believes broader access is needed, it should return the reason instead of asking for approval.

Before spawning writer agents, propose the file ownership split.
Do not start write agents until the split is clear in the main thread.
Prefer read-only explorer agents first if the code ownership is uncertain.

我想同时探索两个修复方向：
方向 A：保持现有 API，只修边界条件。
方向 B：重构 API，让调用方显式传入状态。
 
请用 worktree 隔离两个方向。
每个方向一个 worker agent。
每个 agent 只在自己的方向里实现最小改动并运行相关测试。
最后主线程比较两种方案的风险、改动范围和测试结果。

请派 5 个 agent 一起把整个项目优化一下。

The subagent results are too broad.
Please normalize them into this shape:
- finding
- evidence
- impacted files
- suggested next action
- confidence
 
Drop points that do not cite evidence.

The agents overlapped too much.
Please redesign the split by ownership:
1. one agent for data model
2. one agent for API surface
3. one agent for tests
 
Each agent should list files it will read and files it may edit before starting.

After merging subagent output, check for contradictions:
1. Are two agents assuming different behavior?
2. Did one agent change code that another agent's test does not cover?
3. Are there duplicate fixes?
4. Is any suggested action now obsolete?

Spawn three read-only explorer agents:
1. one for architecture overview
2. one for test strategy
3. one for security-sensitive files
 
No edits.
Wait for all.
Return a merged onboarding map for a new engineer.

Use two worker agents with disjoint file ownership:
- docs-worker edits docs/getting-started.md only
- tests-worker edits tests/onboarding.spec.ts only
 
Main thread reviews both diffs before final response.

After the workers finish, spawn one read-only reviewer agent.
The reviewer should check:
- behavior regression
- missing tests
- docs/code mismatch
Do not edit files.

Explorer template: 只读探索，返回地图。
Worker template: 分文件写入，返回 diff 摘要和命令。
Reviewer template: 只读审查，返回 findings 和证据。

Please review the current branch with parallel subagents.
 
Spawn three read-only agents:
1. Security reviewer
   - focus on auth, secrets, external calls, permission checks
2. Test reviewer
   - focus on missing regression tests and flaky test risk
3. Maintainability reviewer
   - focus on unnecessary complexity and coupling
 
All agents:
- read current branch diff against main
- inspect nearby code when needed
- do not edit files
- return findings with file references
 
Main thread:
- wait for all agents
- merge duplicate findings
- separate confirmed issues from open questions
- recommend the next smallest action

# PR Review Summary
 
## Confirmed Findings
 
1. Auth redirect can bypass the intended fallback path.
   Evidence: src/auth/redirect.ts and tests/auth.spec.ts.
   Next action: add regression test before changing behavior.
 
2. Error state is documented but not tested.
   Evidence: docs/auth.md and tests/auth.spec.ts.
   Next action: add one failing test, then fix implementation.
 
## Open Questions
 
- Whether legacy clients still depend on the old redirect behavior.
 
## Suggested Next Step
 
Make one small patch for the redirect behavior and run the auth test file only.

沿用上一节“三路并行审查一个 PR”的 prompt。
本节不再重复写 agent 分工，重点只训练主线程如何合并输出。
 
主线程合并时必须做三件事：
1. 合并重复发现。
2. 区分确认问题和开放问题。
3. 给出下一步最小行动。

# Parallel Review Summary
 
## Confirmed Findings
 
1. ...
 
## Cross-Agent Agreement
 
- ...
 
## Disagreements
 
- ...
 
## Open Questions
 
- ...
 
## Next Smallest Action
 
- ...

- subagent 负责独立视角。
- main thread 负责合并和排序。
- 只读 review 是最适合第一次练习的 subagent 场景。
- 不要把 reviewer 变成 writer。

- UI 文案在 CheckoutForm。
- API validation 在 checkout route。
- 测试在 checkout spec。

frontend-worker:
- may edit src/components/CheckoutForm.tsx
- may read src/api/checkout.ts
 
backend-worker:
- may edit src/api/checkout.ts
- may read src/components/CheckoutForm.tsx
 
test-worker:
- may edit tests/checkout.spec.ts
- may read src/components/CheckoutForm.tsx and src/api/checkout.ts
 
reviewer:
- read-only after workers finish

Use parallel subagents for this checkout fix.
 
Before starting, repeat the file ownership split.
 
Worker 1: frontend
- only edit src/components/CheckoutForm.tsx
- update the displayed error state
 
Worker 2: backend
- only edit src/api/checkout.ts
- tighten request validation
 
Worker 3: tests
- only edit tests/checkout.spec.ts
- add regression coverage
 
All workers:
- do not edit each other's files
- do not refactor unrelated code
- return changed files and commands run
 
Main thread:
- wait for all workers
- inspect combined diff
- ask before resolving conflicts

Now spawn one read-only reviewer agent.
Review the combined diff for:
- behavior mismatch between UI and API
- missing tests
- accidental unrelated changes
Do not edit files.

请开 8 个 agent，把整个项目优化一遍。

请先只读分析项目，提出最多 3 个适合并行处理的独立任务。
不要启动 subagents，直到任务边界清楚。

请派 3 个 read-only agent 分别看安全、测试和性能风险。
每个 agent 返回 5 条以内 findings 和文件证据。
主线程合并重复项。

请让两个 agent 同时改 src/auth.ts。
一个修 bug，一个重构。

先用一个 read-only agent 分析 bug 根因。
主线程决定最小修复后，再让一个 worker 修改 src/auth.ts。

第一步：只读摸底
- 找登录流程涉及的组件、路由、测试和文档。
- 标出哪些文件可能要改，哪些文件只读参考。
- 不做任何代码修改。
 
第二步：窄范围修改
- 只允许改已经确认的组件和测试文件。
- 每个 worker 拿到独立文件范围。
- 返回改过的文件、运行过的命令、没有覆盖的风险。
 
第三步：只读复核
- 检查 diff 是否越界。
- 检查测试和实际行为是否一致。
- 把分歧交回主线程，不直接继续扩写。

我想更新登录流程的错误提示和相关测试。
 
请先只读探索：
1. 找出登录流程相关的组件、路由、测试和文档。
2. 按“可能需要修改 / 只读参考 / 不相关”分类。
3. 给出建议拆分，不要修改文件。
 
探索完成后，再等我确认下一步。

根据刚才确认的范围执行修改。
 
约束：
1. 只修改已列入“可能需要修改”的文件。
2. 每次修改后说明改了什么行为。
3. 运行与登录流程最相关的测试。
4. 如果发现需要改新文件，先停下来说明原因。

请只读审查当前 diff。
 
重点检查：
1. 是否有超出登录错误提示目标的改动。
2. 测试是否覆盖新增提示。
3. 是否遗漏空状态、网络失败或国际化文案。
4. 哪些风险需要人工点开页面确认。

# Subagent Task Split
 
## Goal
 
...
 
## Agents
 
| Agent | Role     | May read | May edit | Return |
| ----- | -------- | -------- | -------- | ------ |
| A     | explorer |          | none     |        |
| B     | worker   |          |          |        |
| C     | reviewer |          | none     |        |
 
## Merge Plan
 
...

Explorer A：
auth redirect bug 应该改 `redirect.ts`，因为 query params 在 helper 里丢失。
 
Explorer B：
auth redirect bug 应该改 `login.tsx`，因为 form submit 时没有传 callback URL。
 
Reviewer C：
当前测试只覆盖默认 redirect，不覆盖 callback URL。

请合并三个 subagent 的结果。
 
要求：
1. 哪些结论一致。
2. 哪些结论冲突。
3. 每个结论依赖什么文件证据。
4. 下一步最小验证动作是什么。
5. 不要修改文件。

请只读检查：
1. callback URL 是在哪里读取的。
2. callback URL 是在哪里写入 redirect helper 的。
3. 当前测试覆盖哪一段。
 
只回答文件和行为，不给修复方案。

本次只修“登录后没有回到原页面”。
不处理表单文案、不处理 toast、不重构 auth。
 
请基于这个边界重新判断哪些 subagent 建议保留。

Worker A：修改 `redirect.ts`。
Worker B：修改 `login.tsx`。
Worker C：修改 `auth-redirect.test.ts`。

阶段 1：Explorer 只读确认行为链。
阶段 2：主线程决定只改 helper 还是 form。
阶段 3：一个 worker 改实现，一个 worker 改测试。
阶段 4：reviewer 只读审查完整 diff。

请不要并行写 auth redirect 的两个实现入口。
 
先只读确认行为链：
1. callback URL 从哪里进入系统。
2. 保存在哪里。
3. redirect helper 如何读取。
4. 测试应该覆盖哪一层。
 
确认后再决定一个实现修改点。

# Write Ownership
 
## Worker A
 
May edit:
 
- src/auth/redirect.ts
 
Must not edit:
 
- login component
- tests
 
Return:
 
- behavior changed
- edge cases
 
## Worker B
 
May edit:
 
- tests/auth-redirect.test.ts
 
Must not edit:
 
- source code
 
Return:
 
- covered behavior
- remaining untested paths

# Subagent Task Card
 
## Goal
 
Find why auth redirect drops callback URL.
 
## Mode
 
Read-only exploration.
 
## May Read
 
- src/auth/\*\*
- tests/auth/\*\*
- docs/auth.md
 
## Must Not
 
- Edit files.
- Run broad formatters.
- Suggest unrelated auth refactors.
 
## Return
 
1. Files inspected.
2. Behavior chain.
3. Likely root cause.
4. Next smallest verification.
5. Uncertainties.

# Worker Task Card
 
## Goal
 
Implement the minimal redirect helper fix.
 
## May Edit
 
- src/auth/redirect.ts
 
## Must Not Edit
 
- src/auth/login.tsx
- tests/auth-redirect.test.ts
- package files
 
## Stop If
 
- The fix requires changing form submission.
- A new dependency seems necessary.
- Existing tests describe conflicting behavior.
 
## Return
 
- Changed files.
- Behavior changed.
- Commands run.
- Remaining risk.

# Review Task Card
 
## Goal
 
Review the combined auth redirect diff.
 
## Mode
 
Read-only review.
 
## Focus
 
- Scope creep
- Missing tests
- Auth/security regression
- Unrelated UI changes
 
## Return
 
- Findings with file evidence.
- Blocking vs follow-up.
- Suggested next prompt.

# Subagent Merge Report
 
## Original Goal
 
...
 
## Work Split
 
- Explorer:
- Worker:
- Reviewer:
 
## Results Accepted
 
- ...
 
## Results Rejected
 
- ...
 
## Conflicts
 
- ...
 
## Files Changed
 
- ...
 
## Commands Run
 
- ...
 
## Remaining Risk
 
- ...
 
## Next Action
 
- ...

请把所有 subagent 返回结果合并成一份主线程报告。
 
要求：
1. 不逐字粘贴每个 agent 的长输出。
2. 标出哪些结论被采纳，哪些被拒绝。
3. 对冲突给出原因和下一步。
4. 列出最终改动文件和命令证据。
5. 给出用户下一步应该看的内容。

# Subagent Merge Report
 
## Original Goal
 
Fix auth redirect callback URL loss.
 
## Results Accepted
 
- Explorer confirmed callback URL enters via login route.
- Worker changed redirect helper only.
- Reviewer confirmed no payment or toast files changed.
 
## Results Rejected
 
- Explorer suggestion to refactor auth form was out of scope.
 
## Conflicts
 
- Test location was disputed. Resolved by placing regression test with existing auth redirect tests.
 
## Remaining Risk
 
- Manual browser check still useful for SSO path.

当前 PR 修改登录 redirect。
请模拟三个独立检查者：
1. 代码路径探索。
2. 测试覆盖审查。
3. scope creep 审查。
 
每个检查者只输出自己的结论。
最后由主线程合并。

请把三个检查者的结果合并。
输出：
1. 一致结论。
2. 冲突结论。
3. 需要继续查的事实。
4. 最小修复建议。
5. 不应该进入本 PR 的事项。

先给出 subagent 分工计划，不要立刻改文件。
目标：[总目标]
范围：[目录/文件]
约束：[不能做的事]
分工：
- Agent A：[任务A]
- Agent B：[任务B]
汇总后再决定是否执行。