Claude Code Prompt设计模式深度实战：六大形态与反模式修复

graph TB
    subgraph "Claude Code 六大 Prompt 形态"
        A[生成 Generate] --> A1["写出执行X的新代码"]
        B[重构 Refactor] --> B1["修改Y的行为，保持Z不变"]
        C[调试 Debug] --> C1["找到X失败的原因"]
        D[解释 Explain] --> D1["描述代码Y做了什么"]
        E[编排 Orchestrate] --> E1["规划并执行多步骤任务"]
        F[审查 Review] --> F1["审计指定关注点"]
    end

    subgraph "通用原则"
        G[明确的验收标准]
        H[文件指针与上下文]
        I[约束条件与边界]
    end

    A & B & C & D & E & F --> G & H & I

claude "写一个重试函数"

claude "在 @src/utils/retry.ts 中创建一个通用重试函数 retry<T>，要求：
- 泛型支持，返回 Promise<T>
- 参数：执行函数 fn: () => Promise<T>，最大重试次数 maxRetries: number（默认3），初始延迟 baseDelay: number（默认1000ms）
- 指数退避策略：每次重试延迟翻倍
- 只在网络错误（ERR_NETWORK）和超时（ETIMEDOUT）时重试
- 最后一次重试失败后抛出 AggregateError，包含所有错误
- 验收标准：运行 npx jest src/utils/retry.test.ts 全部通过"

[目标] 在 <文件路径> 中创建 <组件/函数/模块>
[输入输出] 接收 <参数描述>，返回 <返回值描述>
[约束条件]
  - <约束1>
  - <约束2>
[验收标准] 运行 <命令> 全部通过

# 好的验收标准
"验收标准：npm test -- --grep 'UserService' 全部通过，且 ESLint 零错误"

claude "重构 @src/services/payment.ts 中的 processPayment 函数：

[变更目标]
  - 将单体函数（180行）拆分为4个独立函数：validateOrder, calculateTotal, chargeCustomer, sendConfirmation
  - 主函数 processPayment 编排这4个子函数

[保持不变]
  - 公共API签名：processPayment(order: Order): Promise<PaymentResult> 不变
  - 错误处理策略：所有错误必须通过 PaymentError 包装后抛出
  - 日志格式：保持 @CLAUDE.md 中定义的结构化日志格式

[参考模式]
  - 参照 @src/services/shipping.ts 中 shipOrder 的拆分模式

[验收标准]
  - 所有现有测试通过：npx jest tests/payment.test.ts
  - 新函数各有独立的单元测试
  - processPayment 的集成测试行为不变"

# 危险！这是最常见的反模式
claude "重构 payment.ts 让它更干净"

"更干净" → "提取超过30行的函数为独立命名函数，添加TypeDoc注释"
"优化性能" → "将N+1查询替换为JOIN查询，目标响应时间<200ms"
"模块化" → "拆分为独立文件，每个文件单一职责，导出明确的公共API"

claude "在执行重构前，先为 @src/services/payment.ts 的 processPayment 函数编写完整的单元测试。
覆盖以下场景：正常支付流程、余额不足、网络超时、并发支付。
使用 @tests/services/shipping.test.ts 作为测试模式参考。"

# 方法一：直接传入错误输出
claude "调试测试失败：

<test_output>
FAIL tests/integration/user-auth.test.ts
  ● User Auth › should refresh expired token

    AssertionError: expected undefined to equal 'new-access-token'

      at Object.<anonymous> (tests/integration/user-auth.test.ts:45:23)

    console.error:
      TokenRefreshError: Refresh token has expired at epoch 1716123456
      at TokenService.refresh (src/services/token.ts:78:13)
</test_output>

涉及文件：@src/services/token.ts @src/middleware/auth.ts @tests/integration/user-auth.test.ts
最近的变更：PR #567 修改了 token 过期逻辑
修复后要求：npm test 全部通过"

# 方法二：管道传入测试输出
npm test 2>&1 | claude "以下是测试输出，诊断失败原因并修复：
涉及文件：@src/services/token.ts @src/middleware/auth.ts
@CLAUDE.md 错误处理规范"

# 太模糊
claude "测试挂了，帮我修"

claude "调试回归问题：

错误：[贴入错误输出]
这个测试在PR #567合并前是通过的。
PR #567的变更：修改了 token 过期检查从绝对时间改为滑动窗口。
涉及文件：@src/services/token.ts（修改行：72-85）"

claude "调试 @src/api/users.ts:postUser 的500错误。
只在 @src/api/users.ts 和 @src/services/user-service.ts 中查找原因。
不要修改数据库层代码。
错误日志：[贴入日志]"

# 弱：太宽泛
claude "解释一下 @src/services/payment.ts"

# 强：指定维度
claude "解释 @src/services/payment.ts:processPayment 中的支付流程：

我需要理解：
1. 资金流转的时序（从用户点击支付到商户收到款项）
2. 与第三方支付网关的交互协议（请求/响应格式）
3. 失败回滚策略（哪些步骤有补偿事务）
4. 并发控制机制（如何防止重复扣款）

不需要：代码逐行解释、基础概念科普"

claude "我刚接手 @src/legacy/batch-processor.js，这是2019年写的无文档代码。
帮我梳理：
1. 这个模块的对外接口和调用者（搜索整个项目中的引用）
2. 数据流向：输入从哪来，输出到哪去
3. 已知的TODO和FIXME注释
4. 外部依赖及其用途"

claude "分析 @src/middleware/ 目录下所有中间件的执行顺序和依赖关系。
用表格展示：中间件名 | 职责 | 是否阻塞 | 依赖哪些其他中间件"

claude "为 @src/api/routes/ 目录下的所有端点生成API文档。
格式：OpenAPI 3.0 YAML，包含请求/响应Schema。
@CLAUDE.md API文档规范"

flowchart TD
    A["大目标：实现用户认证系统"] --> B["原子任务1：创建User数据模型"]
    B --> C["验收：npx jest models/user.test.ts 通过"]
    C --> D["原子任务2：实现注册API"]
    D --> E["验收：curl POST /api/auth/register 返回201"]
    E --> F["原子任务3：实现登录API + JWT签发"]
    F --> G["验收：curl POST /api/auth/login 返回token"]
    G --> H["原子任务4：实现认证中间件"]
    H --> I["验收：受保护端点无token返回401"]
    I --> J["原子任务5：集成测试"]
    J --> K["验收：npm test 全部通过"]

    style A fill:#e74c3c,color:#fff
    style C fill:#2ecc71,color:#fff
    style E fill:#2ecc71,color:#fff
    style G fill:#2ecc71,color:#fff
    style I fill:#2ecc71,color:#fff
    style K fill:#2ecc71,color:#fff

claude "实现用户认证模块，按以下步骤执行：

步骤1：创建数据模型
- 在 @src/models/user.ts 创建 User 模型
- 字段：email（唯一索引）、passwordHash、createdAt、lastLoginAt
- 使用 @src/models/base.ts 作为基类模板
验收：npx jest tests/models/user.test.ts 通过

步骤2：实现注册端点
- POST /api/auth/register
- 输入验证：email格式、密码最小8位
- 密码使用 bcrypt 哈希（参照 @CLAUDE.md 安全规范）
- 返回201 + userId，不返回passwordHash
验收：curl测试返回正确状态码

步骤3：实现登录端点
- POST /api/auth/login
- 返回JWT（过期时间24小时，参考 @src/config/auth.ts 的密钥配置）
- 错误：401 + 'Invalid credentials'（不暴露是邮箱还是密码错误）
验收：curl测试返回有效token

步骤4：认证中间件
- @src/middleware/authenticate.ts
- 从 Authorization header 提取 Bearer token
- 验证JWT并注入 req.user
验收：受保护端点正确拦截无token请求

步骤5：编写集成测试
- 测试完整注册→登录→访问受保护资源的流程
- 测试错误场景：重复注册、错误密码、过期token
验收：npm test -- tests/integration/auth/ 全部通过

约束：
- 不要修改已有的 @src/routes/index.ts 路由注册方式
- 错误处理遵循 @CLAUDE.md 中定义的错误响应格式
- 所有新文件添加到 @src/types/index.ts 的类型导出中"

# 最致命的反模式
claude "帮我实现一个完整的用户认证系统，包括注册、登录、JWT、中间件、测试，
用React和Node.js，PostgreSQL数据库，用最好的实践"

# 阶段1
claude "执行步骤1：创建User数据模型。[详细描述]"
# 等验证通过后...

# 阶段2
claude "继续。执行步骤2：实现注册端点。[详细描述]"
# 依赖步骤1的产出...

# 安全审查
claude "对 @src/api/ 目录下所有端点执行安全审查：
- 检查所有用户输入是否经过验证和消毒
- 检查SQL注入可能性（特别是字符串拼接的查询）
- 检查是否有未认证的端点暴露了敏感数据
- 检查错误响应是否泄露了内部实现细节
参照 @CLAUDE.md 安全规范和 OWASP Top 10
输出格式：按严重程度排序（Critical > High > Medium > Low）"

# 性能审查
claude "审查 @src/services/ 目录的性能问题：
- 识别所有数据库查询，标记N+1查询
- 检查是否有不必要的数据获取（SELECT * 但只用了2个字段）
- 检查循环内的异步操作（应替换为批量操作或Promise.all）
- 检查是否有缺失的数据库索引（对比 @prisma/schema.prisma 的索引定义）
输出格式：每个问题包含文件名、行号、当前代码、建议修改"

# 无效的审查Prompt
claude "审查一下这个文件有没有什么问题 @src/api/users.ts"

# 有效的审查Prompt
claude "审查 @src/api/users.ts 的安全性，特别关注：
1. 所有 req.body / req.params 的输入验证
2. 用户ID是否有权限检查（横向越权）
3. 文件上传端点的大小和类型限制
参照 @CLAUDE.md 安全规范第3节"

claude "<task>重构 @src/services/order.ts 的 OrderService 类</task>

<changes>
- 将 createOrder 方法拆分为 validateItems、calculatePricing、processPayment 三个私有方法
- 将状态机逻辑提取到独立的 OrderStateMachine 类
</changes>

<preserve>
- 公共方法签名不变
- 所有现有测试必须继续通过
- 订单号生成算法不变
</preserve>

<reference>@src/services/subscription.ts 的 SubscriptionService 作为重构模式参考</reference>

<acceptance>
- npx jest tests/order/ 全部通过
- OrderService.ts 总行数不超过 150 行
- 每个新方法有对应的单元测试
</acceptance>"

# 好的做法：精准引用
claude "参照 @src/templates/email-templates.ts 中的模板格式，在 @src/services/notification.ts 
中添加新的邮件通知方法。@CLAUDE.md 通知服务规范"

# 不好的做法：让代理自己找
claude "参照项目中已有的邮件模板格式，在通知服务中添加新方法"

claude "修复 @src/api/orders.ts 中的分页Bug。

约束：
- 只修改 getOrders 函数中的分页逻辑（第45-60行）
- 不要修改排序逻辑
- 不要修改API响应格式
- 不要添加新依赖
- 不要修改测试文件，只确保现有测试通过"

claude "分析 @src/ 目录的依赖关系图，输出以下格式：

\`\`\`
模块名 | 依赖模块 | 被依赖次数 | 耦合等级(高/中/低)
------------------------------------------------------
auth     | database, config | 5          | 高
payment  | auth, database, stripe | 3    | 中
\`\`\`

按被依赖次数降序排列。只显示跨模块依赖，不显示同模块内的导入。"

claude "分析 @src/ 目录的现有模块架构：
1. 列出所有 service 层模块及其职责
2. 识别现有的通知机制（邮件、SMS、推送）
3. 找到事件总线或消息队列的使用模式
4. 列出 @CLAUDE.md 中关于新模块的规范要求
输出格式：结构化表格"

claude "基于上一步的分析，规划'通知中心'模块的实现步骤。

目标：创建统一的通知服务，支持邮件、SMS、站内推送三种渠道。

约束：
- 遵循 @CLAUDE.md 模块规范
- 参照 @src/services/email.ts 作为服务模板
- 使用 @src/events/ 的事件总线

输出格式：每个步骤包含名称、文件路径、依赖步骤、验收标准
不要开始编码，只输出计划"

# 先实现核心模型和接口
claude "执行计划步骤1：创建通知类型定义和接口
[步骤1的详细描述和验收标准]"

# 验证通过后继续
claude "继续执行步骤2：实现 NotificationService 核心类
[步骤2的详细描述，引用步骤1的产出文件]"

claude "对新建的所有通知模块文件执行安全审查：
- 检查通知内容模板是否有XSS注入风险
- 检查用户通知偏好设置是否有权限绕过
- 检查批量发送是否有速率限制
参照 @CLAUDE.md 安全规范
输出按严重程度排序"

claude "修复通知模块的安全问题：

问题1（Critical）：模板引擎直接注入用户输入
文件：@src/services/notification/template.ts:23
修复：使用模板参数化而非字符串拼接

问题2（High）：批量发送无速率限制
文件：@src/services/notification/sender.ts:45
修复：添加令牌桶限流器，参考 @src/utils/rate-limiter.ts

验收：npm test 全部通过 + 安全审查复查通过"

claude "优化 @src/services/notification/ 目录的代码结构：

变更：
- NotificationService.ts 超过200行，拆分为 NotificationRouter、ChannelDispatcher、TemplateEngine
- 三个渠道适配器（email、sms、push）提取到 @src/services/notification/channels/ 目录

保持不变：
- 公共API接口 NotificationService.notify()
- 事件订阅协议
- 现有测试全部通过

验收：npm test 通过 + TypeScript strict 编译零错误"

sequenceDiagram
    participant D as 开发者
    participant CC as Claude Code

    D->>CC: 解释形态：分析现有架构
    CC-->>D: 架构分析报告

    D->>CC: 编排形态：规划任务序列
    CC-->>D: 实现计划（5个原子步骤）

    Note over D,CC: 循环执行每个原子步骤
    loop 步骤 1-5
        D->>CC: 生成形态：实现步骤N
        CC-->>D: 代码 + 自动测试结果
        D->>D: 验证验收标准
    end

    D->>CC: 审查形态：安全审计
    CC-->>D: 安全问题列表

    D->>CC: 调试形态：修复安全问题
    CC-->>D: 修复代码 + 测试通过

    D->>CC: 重构形态：代码结构优化
    CC-->>D: 重构后代码 + 测试通过

    D->>D: 最终验证：完整功能测试

flowchart LR
    A[写好Prompt] --> B{目标明确?}
    B -->|No| C[补充具体描述]
    B -->|Yes| D{范围限定?}
    D -->|No| E[添加@文件引用]
    D -->|Yes| F{有验收标准?}
    F -->|No| G[添加自动化验证命令]
    F -->|Yes| H{任务原子性?}
    H -->|No| I[分解为多个子任务]
    H -->|Yes| J[发送Prompt]
    C --> B
    E --> D
    G --> F
    I --> H