Claude Code 实战（八）：Sub-Agent 与计划模式

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

你：为 API 添加限流功能，要求每 IP 每分钟最多 100 次请求。

[Mode: plan]

Claude：以下是添加限流功能的完整计划：

1. 安装 `express-rate-limit`（它已在 `package.json` 中作为 devDependency 存在，但未列入 dependencies —— 我将把它移至 dependencies）。

2. 创建 `src/middleware/rate-limit.ts`：
   - 导出一个可配置的限流器工厂函数
   - 默认配置：基于 `req.ip`，每 IP 每分钟 100 次请求
   - 开发环境使用内存存储；备注生产环境应改用 Redis 存储

3. 在 `src/app.ts` 中接入限流中间件：
   - 导入限流器
   - 使用 `app.use()` 全局注册，置于路由处理器之前
   - 位置要求：CORS 中间件之后、body parser 之前

4. 在响应中添加限流相关 Header：
   - `X-RateLimit-Limit`
   - `X-RateLimit-Remaining`
   - `X-RateLimit-Reset`

5. 创建 `tests/middleware/rate-limit.test.ts`：
   - 测试：前 100 次请求被允许
   - 测试：第 101 次请求被拒绝
   - 测试：时间窗口过期后计数重置
   - 测试：不同 IP 地址拥有独立限流计数

6. 更新 `src/types/env.d.ts`，新增环境变量类型声明：
   - `RATE_LIMIT_MAX`
   - `RATE_LIMIT_WINDOW_MS`

是否确认执行此计划？

1
2
3
4
5
6
7
8

你：[plan mode] 添加认证功能。聚焦于数据库 schema 变更。
     我已熟悉 API 层。

Claude：仅聚焦 schema 变更：

1. 新增 `sessions` 表……
2. 为 `users` 表添加 `last_login` 字段……
3. 生成迁移文件……

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

---
name: research
description: Reads a topic across the codebase and reports findings. No edits.
tools: Read, Grep, Glob, WebFetch
---

You are a research sub-agent. Your job:
1. Search the codebase for the requested topic.
2. Read enough files to understand it deeply.
3. Return a structured report with file paths and quotes.

Do not edit. Do not run shell commands. Stay focused.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

---
name: test-writer
description: 为指定模块编写测试。读取源码，生成测试，不修改源码。
tools: Read, Grep, Glob, Write, Bash
---

你是一个测试编写 sub-agent。你的任务：
1. 读取被测模块的源码；
2. 识别所有公开函数及其边界场景（edge cases）；
3. 按项目所用测试框架，编写全面的测试；
4. 运行测试，验证其通过。

规则：
- 禁止修改任何源文件，仅可创建或修改测试文件；
- 严格遵循项目中已有的测试模式与结构；
- 每个测试用例名称须具备描述性，清晰表达所覆盖的场景；
- 侧重覆盖边界场景，而非仅“快乐路径”（happy paths）。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

---
name: doc-writer
description: 为代码变更生成文档。读取源码与现有文档，输出 Markdown。
tools: Read, Grep, Glob, Write
---

你是一个文档编写 sub-agent。你的任务：
1. 读取被指定的代码变更或模块；
2. 读取现有文档，理解上下文、语气与风格；
3. 编写或更新文档，确保与项目整体风格一致。

规则：
- 严格匹配现有文档的语气（voice）与格式（format）；
- 每个公开 API 均须附带可运行的代码示例；
- 不执行任何命令（如 Bash）；
- 不修改源代码。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

你：请使用 research agent，调研 payment 模块如何处理退款。

Claude：我将启动 research sub-agent，分析 payment/refund 流程。

[Sub-agent: research]
正在搜索与 refund 相关的代码……
找到 12 个含 refund 的文件：
  - src/payments/refund.ts（主处理逻辑）
  - src/payments/refund-validator.ts（校验逻辑）
  ...

[Sub-agent 报告返回至父 Agent]

Claude：根据 research sub-agent 的分析，该代码库中退款流程如下：……

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

你：我需要并行完成三件事：
     1. Research agent：该项目的认证（auth）机制是如何工作的？
     2. Test-writer agent：为 src/utils/validator.ts 编写测试
     3. Doc-writer agent：更新 `/users` 端点的 API 文档

Claude：正在并行启动三个 sub-agent...

[Sub-agent: research] 正在调研认证流程...
[Sub-agent: test-writer] 正在读取 validator.ts 并编写测试...
[Sub-agent: doc-writer] 正在读取 API 文档，并更新 `/users` 部分...

[三个 sub-agent 均已完成]

Claude：以下是三个 sub-agent 的结果：...

1
2
3
4
5
6

你：创建一个名为 “refactor-auth” 的 worktree，并切换到它。

Claude：[EnterWorktree: name="refactor-auth"]
已创建 worktree，路径为 .claude/worktrees/refactor-auth/
已切换至新分支：refactor-auth
当前工作目录为：/path/to/repo/.claude/worktrees/refactor-auth/

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

# 列出所有 worktree 分支（排除当前检出分支）
git branch | grep -v "^\*"

# 合并该 worktree 的全部变更
git merge refactor-auth

# 或仅选取特定提交
git cherry-pick abc1234

# 清理：移除 worktree 并删除分支
git worktree remove .claude/worktrees/refactor-auth
git branch -d refactor-auth

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

你：[plan mode] 我想把 auth 逻辑抽离为独立包，请规划整体方案。

Claude：auth 抽离计划如下：

1. 调研阶段：
   - 扫描所有导入 `src/auth/` 的文件
   - 识别共享类型与接口（如 `User`、`Session`）
   - 定位覆盖 auth 逻辑的测试文件
   - 检查是否存在循环依赖

2. 抽离阶段：
   - 创建 `packages/auth/` 目录并初始化 `package.json`
   - 将 `src/auth/*.ts` 迁移至 `packages/auth/src/`
   - 在 `packages/auth/index.ts` 中定义公共 API 表面
   - 全量更新单体中对 `src/auth/` 的导入路径

3. 兼容阶段：
   - 在 `src/auth/index.ts` 添加 re-export shim（透传导出）
   - 验证运行时行为无变更
   - 运行完整测试套件

4. 清理阶段：
   - 移除 re-export shim
   - 更新文档
   - 同步 CI 配置

风险：auth 模块与 user 模块存在循环依赖。  
缓解措施：优先抽离共享类型。

是否继续？

1
2
3
4
5

你：为此任务创建名为 `extract-auth` 的 git worktree。

Claude：[EnterWorktree: name="extract-auth"]
已基于分支 `extract-auth` 创建 worktree。
当前路径：`.claude/worktrees/extract-auth/`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

你：调用 research sub-agent，绘制 auth 的全部依赖关系图。

Claude：启动 research sub-agent...

[Sub-agent: research]
共发现 23 个文件导入 `src/auth/`：
  - `src/routes/api.ts`（导入：`authenticate`, `requireRole`）
  - `src/routes/admin.ts`（导入：`requireAdmin`）
  - `src/middleware/session.ts`（导入：`SessionConfig` 类型）
  ...

检测到循环依赖：
  `src/auth/user-lookup.ts` → 导入 `src/users/types.ts`  
  `src/users/service.ts` → 导入 `src/auth/types.ts`

需优先抽离的共享类型：
  - `User`（被 14 个文件使用）
  - `Session`（被 8 个文件使用）
  - `AuthConfig`（被 3 个文件使用）

1
2
3
4
5
6
7
8
9

你：开始抽离：先共享类型，再 auth 模块，最后更新导入路径。

Claude：[Working in worktree extract-auth]

Commit 1：`extract: shared types to packages/shared-types/`  
Commit 2：`extract: auth module to packages/auth/`  
Commit 3：`update: imports in monolith to use packages/auth`  
Commit 4：`add: re-export shim for backward compatibility`  
Commit 5：`test: all 47 auth tests passing in new location`

1
2
3
4
5
6
7

你：测试全部通过。退出 worktree，并合并至 main。

Claude：[ExitWorktree: action="keep"]
已返回主工作目录。

`extract-auth` 分支含 5 个 commit。  
合并命令：`git merge extract-auth`