《Claude Code 从入门到精通》试读篇：写好 Prompt 的结构化思维，10组正反对比，看完直接套用（三）

┌──────────────────────────────────────────────────┐
│  ① 目标描述：你要 Claude 做什么                      │
│     → 动作 + 对象 + 范围                            │
│     → 回答的问题："做什么事？改哪里？"                  │
│                                                    │
│  ② 上下文信息：Claude 需要知道的背景                   │
│     → 项目现状、业务逻辑、技术栈约定                    │
│     → 回答的问题："为什么要做？现在是什么情况？"          │
│                                                    │
│  ③ 质量标准：做到什么程度算完成                        │
│     → 具体的、可验证的完成条件                         │
│     → 回答的问题："怎么判断做好了？"                    │
│                                                    │
│  ④ 约束条件：什么不能做、必须遵守什么                   │
│     → 技术限制、业务红线、风格规范                      │
│     → 回答的问题："边界在哪？雷区在哪？"                │
└──────────────────────────────────────────────────┘

❌ 模糊目标：
"我们的订单系统需要改进一下"

Claude 内心：改进什么？性能？功能？UI？安全？你没说，我只能猜。

✅ 清晰目标：
"在 src/modules/order/ 下新增订单导出功能，
 支持按时间范围筛选，导出为 CSV 格式"

→ 动作：新增
→ 对象：订单导出功能
→ 范围：src/modules/order/ 目录
→ 具体交付：CSV 格式，支持时间筛选

❌ 模糊目标：
"用户反馈登录有问题，你查一下"

Claude 内心：什么问题？登录不上？登录慢？登录后跳转错误？
所有用户都有这个问题还是部分用户？我得猜着排查。

✅ 清晰目标：
"修复用户登录后 token 刷新失败的问题：
 用户登录成功后，在 token 过期时自动刷新机制没有生效，
 导致用户需要重新登录。问题出在 src/auth/ 模块。"

→ 动作：修复
→ 对象：token 刷新机制
→ 范围：src/auth/ 模块
→ 症状描述：具体到"自动刷新没生效"

❌ 缺少上下文：
"审查 src/services/payment.ts 的代码质量"

Claude 会按通用标准审查：命名规范、函数长度、注释覆盖……
给你一堆正确但没用的建议。

✅ 提供上下文：
"审查 src/services/payment.ts 的代码质量。

背景：
- 这个文件上周由新入职的同事编写，还没有经过任何 review
- 项目使用 DDD 架构，service 层不应该直接操作数据库，
  必须通过 repository 层
- 支付模块是核心链路，对错误处理和日志要求比其他模块更严格
- 上线时间是下周三，需要在此之前完成修改"

→ Claude 知道了审查重点：
  新人代码 → 重点看架构规范有没有遵守
  DDD 架构 → 检查有没有绕过 repository 直接操作数据库
  核心链路 → 错误处理和日志要从严审查
  时间紧 → 只提必须改的问题，不纠结代码风格小事

❌ 缺少上下文：
"优化 getUserList 接口的性能"

Claude 可能给你加索引、加缓存、分页优化……什么都试一遍。

✅ 提供上下文：
"优化 getUserList 接口的性能。

现状：
- 当前响应时间 P99 = 2.3s，目标降到 500ms 以内
- 用户表 320 万条数据，每天增长约 5000 条
- 已有 Redis 缓存，但命中率只有 12%（怀疑缓存 key 设计有问题）
- 数据库是 MySQL 8.0，已有 user_id 和 created_at 的索引
- 前端分页每页 20 条，支持按注册时间和活跃度排序"

→ Claude 的优化方向立刻聚焦：
  不用建议"加缓存"（已有，但命中率低）
  优先排查缓存 key 设计
  不用建议"加索引"（已有基础索引，可能需要复合索引）
  分页策略可能需要从 OFFSET 改成游标分页（320万数据量）

❌ 没有质量标准：
"给 orderService.createOrder 写单元测试"

Claude 会写 3-5 个基础测试用例，覆盖最明显的路径。
能用，但远远不够。

✅ 明确质量标准：
"给 orderService.createOrder 写单元测试。

完成标准：
- 覆盖所有正常流程（单商品、多商品、使用优惠券、不使用优惠券）
- 覆盖所有异常路径（库存不足、优惠券过期、支付超时、重复下单）
- 每个 mock 的外部依赖要有独立的测试（支付服务、库存服务、通知服务）
- 测试命名用 should_[预期行为]_when_[条件] 格式
- 代码覆盖率目标：语句覆盖 > 90%，分支覆盖 > 85%"

❌ 没有质量标准：
"给支付模块写个 API 文档"

Claude 会按照通用 API 文档模板写，格式正确但内容可能跟你们团队的文档风格完全不同。

✅ 明确质量标准：
"给支付模块写 API 文档。

完成标准：
- 参照 docs/api/user-module.md 的格式和详细程度
- 每个接口包含：路径、方法、请求参数（含类型和是否必填）、
  响应示例（成功+失败各一个）、错误码说明
- 包含一个完整的「快速开始」章节，
  新同事看完能在 10 分钟内跑通第一个支付请求
- 业务术语用中文，技术术语用英文（跟现有文档保持一致）"

❌ 没有约束：
"给用户表加一个 last_login_at 字段"

Claude 可能直接写一个 ALTER TABLE 语句。
在开发环境没问题，在生产环境可能锁表几分钟，直接出事故。

✅ 明确约束：
"给用户表加一个 last_login_at 字段。

约束：
- 必须通过 migration 文件添加，不要直接写 SQL
- 用户表当前 800 万行，变更不能导致锁表
  （如果 MySQL，考虑用 pt-online-schema-change 的思路）
- 新字段允许为 NULL，不设默认值（避免全表更新）
- 同步更新相关的 ORM model 和 TypeScript 类型定义
- 不要修改任何现有字段"

❌ 没有约束：
"把 utils/helpers.ts 重构一下，太乱了"

Claude 可能大刀阔斧地重构：拆文件、改函数签名、改导出方式……
结果项目里 30 个文件的 import 全挂了。

✅ 明确约束：
"重构 utils/helpers.ts，改善代码组织。

约束：
- 所有公开函数的签名和返回类型不能变（外部有大量引用）
- 如果要拆分成多个文件，必须在 utils/index.ts 里重新导出，
  确保现有的 import { xxx } from '@/utils' 不需要改
- 不要引入新的依赖
- 每一步改动后跑 tsc --noEmit 确认类型检查通过
- 改完跑全量测试，确认无回归"

❌ 四要素缺失的写法：
"支付回调有 bug，赶紧修一下"

✅ 四要素完整的写法：

【目标】
修复支付回调处理中的订单状态不一致问题。

【上下文】（紧急 Bug 这部分要写最多）
- 今天下午 14:00 开始，陆续有用户反馈：微信支付成功但订单显示未支付
- 影响范围：约 3% 的微信支付订单，支付宝支付正常
- 初步发现：支付回调日志显示收到了微信的成功通知，
  但 order 表的 status 没有更新
- 可能相关：昨天下午发了一版，改动了订单状态机的代码
  （提交记录 commit abc123）
- 当前临时方案：客服在手动帮用户改状态，但量越来越大

【质量标准】
- 找到根因，而不只是修复症状
- 修复后这 3% 的失败订单也需要补偿修复（写一个修复脚本）
- 修复上线前必须有测试覆盖这个场景

【约束】
- 不要改支付宝的回调逻辑（那边是正常的）
- 修复脚本只处理今天 14:00 之后的受影响订单
- 必须向后兼容，不能影响正在进行中的支付流程

❌ 四要素缺失的写法：
"开发一个站内消息系统"

✅ 四要素完整的写法：

【目标】
在现有项目中新增站内消息模块，支持系统通知和用户间私信。

【上下文】
- 项目技术栈：NestJS + TypeORM + MySQL + Redis
- 现有模块可参考 src/modules/notification/ 的代码风格
- 用户表已有，通过 userId 关联
- 前端会通过 WebSocket 接收实时消息（WebSocket 网关已搭好，
  在 src/gateways/ws.gateway.ts）

【质量标准】
- 数据库设计：消息表支持已读/未读状态、消息类型区分、软删除
- API 接口：获取消息列表（分页+筛选）、标记已读（单条+批量）、
  发送私信、获取未读数量
- 每个接口有完整的 DTO 验证和 Swagger 文档
- 单元测试覆盖所有 service 方法
- 写一个 seed 脚本，生成测试数据方便前端联调

【约束】
- 不要引入新的 ORM 或消息队列，用现有技术栈
- 消息内容存纯文本，第一版不支持富文本和附件
- 私信功能只做一对一，不做群聊
- 分页用游标方式，不用 OFFSET（参照现有的列表接口实现）
- 文件结构按 src/modules/message/ 组织，
  跟其他模块保持一致

【目标】
[动作] + [对象] + [范围]
（一两句话说清楚要做什么）

【上下文】
- 当前情况：……
- 相关代码/模块：……
- 业务背景（如果有）：……
（Bug 修复类多写，新功能类少写）

【质量标准】
- 具体的完成条件 1
- 具体的完成条件 2
- 参照 [现有文件] 的标准
- 测试覆盖要求
（新功能和重构类多写）

【约束】
- 不要……
- 必须……
- 兼容性要求……
- 技术栈限制……
（重构和数据库变更类多写）

任务类型             重点要素               原因
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Bug 修复             上下文 ★★★            症状、现场信息决定排查效率
新功能开发            质量标准 + 约束 ★★★    没有参照物，你的标准=方向
代码重构             约束 ★★★              "不破坏现有行为"是核心红线
性能优化             上下文 ★★★            现状数据越具体，优化越精准
代码审查             上下文 ★★★            审查重点取决于代码的背景
写测试              质量标准 ★★★           覆盖范围和规范需要你定义
数据库变更            约束 ★★★              安全性和兼容性是第一优先级
文档生成             质量标准 ★★★           格式、详细度、受众需要明确

在开始实现之前，先列出你打算怎么做、会涉及哪些文件，
以及你觉得有哪些我没提到但需要确认的问题。