Claude Code 提示词工程 — 结构化指令、ultrathink 与反模式

# 糟糕的提示词
claude -p "修一下代码"

# 好的提示词（CRISPE 框架）
claude -p "
作为资深 Python 后端工程师，
请重构 src/auth/ 目录下的用户认证模块。

背景：
- 当前使用 Flask-Session 进行认证
- 需要迁移到 JWT token 认证
- 数据库使用 SQLAlchemy

要求：
1. 保留原有 API 接口不变
2. 添加完整的类型注解
3. 包含单元测试
4. 更新相关文档

约束：
- 不要修改数据库 schema
- 不要改变外部 API 行为
- 使用 PyJWT 库
"

# [任务类型]

## 角色
[设定 Claude 的专业角色]

## 任务
[清晰描述要完成的任务]

## 上下文
[提供必要的背景信息]

## 输入
[描述输入文件或数据]

## 输出要求
[描述期望的输出格式和内容]

## 约束
[列出必须遵守的规则]

## 验收标准
[定义完成的标准]

# 代码审查模板
claude -p "
# 代码审查

## 角色
你是一位有 10 年经验的高级代码审查员，擅长发现潜在的安全漏洞、性能问题和设计缺陷。

## 任务
审查以下代码变更，提供详细的审查意见。

## 上下文
- 项目: FastAPI 用户管理系统
- 语言: Python 3.11
- 变更范围: src/auth/ 目录

## 输出要求
请按以下结构输出:

### 📊 概览
- 变更文件数
- 变更行数
- 风险评估（低/中/高）

### ✅ 优点
- 做得好的地方

### 🔴 问题
按严重程度分类:
- 🔥 阻塞级（必须修复）
- ⚠️ 建议级（应该修复）
- 💡 优化级（可以优化）

### 💡 改进建议
- 具体的改进方案和代码示例

### 📋 检查清单
- [ ] 安全性检查
- [ ] 性能检查
- [ ] 可维护性检查
"

# 方式一：在提示词中声明
claude -p "
<ultrathink>
请设计一个高并发的用户认证系统架构。
考虑以下方面：
1. 水平扩展能力
2. 故障恢复机制
3. 安全策略
4. 性能优化
</ultrathink>
"

# 方式二：使用系统提示
claude --system-prompt "启用深度推理模式" -p "分析系统瓶颈"

# 方式三：在 CLAUDE.md 中配置
echo "
## Claude Code 行为
- 对于架构设计和复杂分析任务，自动启用深度推理模式
" >> CLAUDE.md

<思考过程>
1. 首先分析当前架构的瓶颈...
   - 数据库连接池已满
   - 认证服务是单点
   - 缺少缓存层

2. 提出改进方案...
   - 引入 Redis 缓存
   - 认证服务无状态化
   - 添加负载均衡

3. 评估方案可行性...
   - Redis 缓存可减少 80% 数据库查询
   - JWT 使认证服务可水平扩展
   - 负载均衡需要修改部署配置

4. 最终方案...
   [详细架构设计]
</思考过程>

[最终输出]
...

claude -p "
生成一个 FastAPI 用户注册端点。

要求：
- 使用 Pydantic v2 验证
- 密码使用 bcrypt 哈希
- 返回标准 APIResponse
- 包含完整的错误处理
- 添加类型注解和 docstring

现有依赖：
from fastapi import APIRouter, HTTPException
from pydantic import BaseModel, EmailStr
import bcrypt

数据库模型：
class User(Base):
    id = Column(Integer, primary_key=True)
    email = Column(String, unique=True)
    password_hash = Column(String)
"

claude -p "
重构以下函数，使其符合 SOLID 原则。

当前问题：
1. 函数太长（>100 行）
2. 职责不单一
3. 硬编码配置
4. 缺少错误处理

请：
1. 拆分为多个小函数
2. 提取配置到配置类
3. 添加适当的异常处理
4. 保持原有功能不变
"

claude -p "
分析以下错误日志，定位根因并提供修复方案。

错误日志：

项目信息：
- ORM: SQLAlchemy 2.0
- 数据库: SQLite (开发) / PostgreSQL (生产)
- 相关代码在 src/services/user_service.py

请提供：
1. 错误原因分析
2. 修复代码
3. 预防措施
"

claude -p "
为以下模块编写 API 文档。

要求：
- 使用 Google 风格的 docstring
- 包含参数说明、返回值、异常
- 提供使用示例
- 标注废弃的方法

模块: src/api/users.py

文档格式: Markdown
输出文件: docs/api/users.md
"

# ❌ 模糊
claude -p "优化代码"

# ✅ 具体
claude -p "优化 src/data_processor.py 中的数据处理函数，
将时间复杂度从 O(n²) 降低到 O(n log n)，
使用哈希表替代嵌套循环。
保持原有功能不变，添加性能基准测试。"

# ❌ 过度约束
claude -p "
用恰好 50 行代码重写这个函数，
必须使用 for 循环，
不能使用任何内置函数，
变量名必须是一个字母，
不要添加注释。
"

# ✅ 合理约束
claude -p "
重写这个函数以提高可读性和性能。
- 保持简洁（建议在 30-60 行）
- 使用描述性变量名
- 添加关键逻辑的注释
- 可以合理使用内置函数
"

# ❌ 缺少上下文
claude -p "修复这个 bug"

# ✅ 充分上下文
claude -p "
修复以下 bug：

现象：用户注册时，重复邮箱未被正确拒绝

预期行为：返回 409 Conflict
实际行为：返回 500 Internal Server Error

相关代码：src/api/users.py 第 42-55 行
数据库：PostgreSQL，user 表有 email 唯一约束
ORM：SQLAlchemy 2.0

请分析原因并提供修复。
"

# ❌ 不验证
claude -p "生成测试用例"

# ✅ 验证输出
claude -p "
生成测试用例，然后：
1. 运行测试验证通过
2. 检查覆盖率是否达到 80%
3. 如果有失败，分析原因并修复
"

# ❌ 忽略边界
claude -p "写一个排序函数"

# ✅ 考虑边界
claude -p "
写一个排序函数，考虑以下边界条件：
- 空列表
- 单元素列表
- 已排序列表
- 逆序列表
- 包含重复元素
- 包含负数
- 大数据量（性能）

添加对应的测试用例。
"

# 第一步：分析
claude -p "分析 src/ 目录的代码质量问题" > analysis.json

# 第二步：基于分析结果生成修复方案
jq -r '.issues[] | .file + ": " + .description' analysis.json \
  | xargs -I {} claude -p "修复以下问题: {}" > fixes.patch

# 第三步：验证修复
claude -p "验证以下修复是否正确: $(cat fixes.patch)" > validation.md

claude -p "
请依次扮演以下角色完成任务：

1. 【架构师】分析当前系统架构，识别瓶颈
2. 【开发者】根据架构师的建议编写代码
3. 【审查员】审查开发者的代码
4. 【测试工程师】编写测试用例

每个角色的输出用分隔线标明。
"

claude -p "
我将逐步提供信息，请在每一步给出反馈：

步骤 1: 我描述需求
步骤 2: 你提出设计方案
步骤 3: 我确认或调整方案
步骤 4: 你生成代码
步骤 5: 你编写测试

现在开始步骤 1：
需求是：实现一个支持 OAuth2 的登录系统...
"

# 将提示词保存为模板文件
mkdir -p prompts/

cat > prompts/code-review.md << 'EOF'
# 代码审查提示词模板

## 角色
...

## 任务
...
EOF

# 使用模板
claude -p "$(cat prompts/code-review.md)" --file src/main.py