Subagent 高级实战工作流

Subagent 是独立上下文沙箱中的子代理，用于分工协作，避免主对话被细节刷屏。

Subagent 概念

三种高级工作流

1. 批量微观重构与代码迁移

场景：将大量文件从 JS 翻写为 TS，或统一升级旧 API 格式。

配置：.claude/agents/transformer.md

Copy---
name: transformer
description: Migrates single files with strict typing
tools: Read, Edit
---
You migrate files one at a time. For each file:
- Preserve all existing logic
- Add strict TypeScript types
- Do not change runtime behavior

Prompt 示例

Use a subagent to migrate @src/utils/math.js into TypeScript.
Ensure all types are strictly defined and return the exact
refactored file content.

2. API 文档与注释生成

场景：根据 Controller 源码生成 API_DOCUMENT.md。

配置：.claude/agents/doc-writer.md

Copy---
name: doc-writer
description: Generates API documentation from source
tools: Read, Edit
---
Read controller source code and extract:
- Endpoint paths
- Query parameters
- Request/response schemas
- Error cases
Write to Markdown template with proper formatting.

Prompt 示例

Use a subagent to scan all controllers in @src/controllers/,
extract their query parameters and response schemas,
and write a complete API reference to @docs/API_v1.md.

3. 大规模代码检索与调研

场景：在陌生代码库中搜寻配置调用痕迹、理清依赖关系。

配置：.claude/agents/researcher.md

Copy---
name: researcher
description: Read-only code investigation
tools: Read, Grep, Glob
---
Investigate code without making changes. Provide:
- High-level summary
- Affected files and lines
- Dependency graph

Prompt 示例

Use a subagent to trace how `deprecated_config` is passed
through the entire repository. Just give me a high-level
summary report of affected files and lines.

定制 Subagent 配置

配置文件位置

.claude/agents/{name}.md

配置格式

Copy---
name: {agent-name}
description: {one-line description}
tools: {tool-list}    # Read, Edit, Grep, Glob, Bash
model: {model-name}   # opus, sonnet, haiku (optional)
---

{custom instructions}

完整示例：Security Reviewer

Copy---
name: security-reviewer
description: Reviews code for security vulnerabilities
tools: Read, Grep, Glob, Bash
model: opus
---
You are a senior security engineer. Review code for:
- Injection vulnerabilities (SQL, XSS, command injection)
- Authentication and authorization flaws
- Secrets or credentials in code
- Insecure data handling

Provide specific line references and suggested fixes.

使用 Prompt

Use a subagent to review this code for security issues.

工具权限说明

建议只读任务不赋予 Edit/Bash，写入任务不赋予 Bash。

Prompt 模板

基础模板

Use a subagent to [task description].
[Specific requirements].

带配置引用模板

Use the [agent-name] subagent to [task description].

强制只读模板

Use a subagent (read-only) to investigate [topic].
Just give me a summary report, do not modify any files.

适用场景总结

相关链接

• 04_plan_mode_ask - 需求不明确时先访谈
• 02_explore_plan_implement - Explore 步骤可调用 subagent
• 05_session_management - Subagent 失败时主对话纠偏