你的 Claude Code 指令，还在让它自由发挥？

Claude Code 火了，一天 12 万 GitHub Star。我第一时间装到终端试用——确实快，但很快发现：指令写得好不好，跑出来的东西天差地别。

很多人习惯说“帮我解释这段代码”“写个测试”，结果 Claude Code 给你一堆通用答案，甚至把项目里的其他文件也扯进来，弄出一堆垃圾。

我折腾了几天，总结出 3 个实战模板。直接复制改一改，能让 Claude Code 一次性给出你想要的输出，少很多来回对话。

1. 代码解释：别只给文件，给函数+关注点

差 Prompt

解释一下 utils.py 里的代码。

Claude Code 会扫整个文件，把每个函数都解释一遍，你真正想知道的细节可能一句话带过。

核心思路

显式指定：文件名、函数名/行号、你想知道的维度（性能、逻辑、依赖）。抑制无关信息。

好 Prompt 模板

请你解释文件 `src/analysis/metrics.py` 中的 `calculate_auc` 函数（第 45-62 行）。

要求：
1. 用一段话说明该函数的输入、输出和核心逻辑
2. 分析它的时间复杂度（基于最内层循环）
3. 指出它依赖了哪些外部库或类，并标注依赖路径
4. 如果逻辑有潜在 bug 或边界情况，请列出来

不要解释文件中的其他函数。

效果对比

• 差 Prompt：输出 800 字涵盖所有函数，时间复杂度假泛泛说 O(n²)，没指出依赖。
• 好 Prompt：输出 300 字，只聚焦 calculate_auc，指出它在嵌套循环里用了 sklearn.metrics.roc_curve，时间复杂度为 O(n²) 但 n 是类别数而非样本数，实际可接受。还发现排序逻辑里没处理平局。

变体

• 改成“以 Markdown 列表输出”让信息更结构化。
• 加“如果某行可能出错，用 ⚠️ 标记”来快速定位问题。

2. 生成测试：注入被测代码的上下文 + 风格约束

差 Prompt

给 fetch_user_data 写单元测试。

Claude Code 可能用 unittest 写一个简单的 mock，但你的项目用 pytest + pytest-asyncio，它写的测试跑不通。

核心思路

告诉它：测试框架、mock 策略、你关心的边界情况、覆盖率的门槛。

好 Prompt 模板

在 `tests/test_api.py` 中为类 `UserAPI` 的方法 `fetch_user_data(user_id: int) -> dict` 编写单元测试。

测试框架：pytest + pytest-asyncio
Mock 库：unittest.mock（项目中已配置）

被测代码的路径：`app/api.py`，关键实现细节：
- 内部调用了 `httpx.AsyncClient.get`，URL 为 `{BASE_URL}/users/{user_id}`
- 成功时返回 JSON 对象，包含 `id`、`name`、`email`
- 失败时抛 `UserNotFoundError`（在 `app/exceptions.py` 中定义）

测试要求：
1. 至少包含 3 个 case：正常返回、用户不存在（404）、网络超时
2. 每个测试函数用 `@pytest.mark.asyncio`
3. Mock 方式：使用 `aioresponses` 或者 `mock.patch('httpx.AsyncClient.get')`，请优先使用项目中已有的 mock 方案（检查 `conftest.py` 中的 fixture）
4. 如果你看不到 `conftest.py`，就用 `mock.patch` 并自行创建 fixture
5. 输出时只输出测试代码，不要解释

效果对比

• 差 Prompt：生成 5 个测试，全部用 unittest，mock 依赖未安装的库，边界少。
• 好 Prompt：生成 4 个测试（正常、404、超时、异常继承验证），自动引用了 conftest.py 中的 async_client fixture，代码可直接 pytest 通过。

变体

• 加“覆盖率达到 95% 以上”可让 Claude Code 补 branch。
• 改成“用 property-based testing”能触发使用 hypothesis 库。

3. 项目重构：指定范围 + 输出格式，避免误改

差 Prompt

帮我重构这个项目里的数据库查询，改用 ORM。

后果：Claude Code 可能动了几十个文件，把之前的 SQL 全换成 SQLAlchemy，但有些地方根本不适合，而且没给你选择。

核心思路

锁死范围：只重构特定文件/模式，保留原逻辑，且给出备选方案。

好 Prompt 模板

重构以下 3 个文件中的数据库查询语句，改用 SQLAlchemy 2.0 的 ORM 风格。
文件列表：
- src/models/user.py（只重构 __init__ 和 get_by_email 方法）
- src/repositories/order_repo.py（全部方法）
- src/scripts/migrate.py（第 10-30 行）

约束：
1. 保持现有函数签名不变，只改内部实现
2. 不要修改 `src/migrations/` 下的任何文件
3. 输出格式：
   - 每个文件单独列出一个代码块
   - 代码块前写清楚修改了哪些行
   - 对于每个修改，给出两种方案：方案 A（性能优先）、方案 B（可读性优先）
4. 如果发现某个函数直接使用 raw SQL 且性能敏感（比如批量插入），保留 raw SQL 并加注释说明原因
5. 操作前先展示当前逻辑的概要，让我确认后你再执行

效果对比

• 差 Prompt：改了 12 个文件，其中 migrations 下的文件被改坏导致回滚不了。
• 好 Prompt：只改了要求的 3 个文件，且在 order_repo.py 的批量插入处保留了 raw SQL 并加了注释。方案 A 使用 bulk_insert_mappings，方案 B 使用逐条 add。我选择了方案 A，直接应用。

变体

• 加“如果重构后性能下降超过 5%，回退并报告”让 Claude Code 自动做性能断言。
• 如果想全局预览，把输出格式改为“只输出 diff，不直接修改文件”。

一点个人看法

Claude Code 的 Agent 能力很强，但越强的工具越需要“缰绳”。给指令时，你越具体，它越听话。不要怕啰嗦，把你脑子里的约束写成文字，比让它猜然后你手动改要快得多。

如果你也用它写过代码，欢迎在评论区贴出你常用的指令模板，我们一起攒个“Claude Code 提示词菜谱”。