Claude Code提示工程：写出更好AI编程输出的完整指南

# 项目：FastAPI SaaS 后端

## 技术栈
- Python 3.12, FastAPI 0.115, SQLAlchemy 2.0, PostgreSQL 16
- Pydantic v2 用于验证, Alembic 用于数据迁移
- Pytest + pytest-asyncio 用于测试

## 代码规范
- 所有路由返回 Pydantic 模型，绝不返回原始字典
- 数据库查询使用异步 SQLAlchemy 会话
- 环境变量通过 pydantic-settings 从 .env 加载
- 所有函数签名必须带类型标注

## 架构
- 整洁架构：routes → services → repositories → models
- Services 包含业务逻辑，绝不在 routes 层
- Repositories 是唯一接触 SQLAlchemy 的层

## 命令
- 运行：`uvicorn app.main:app --reload`
- 测试：`pytest -xvs`
- Lint：`ruff check . && mypy app/`
- 迁移：`alembic upgrade head`

## 禁止
- 永远不要使用原生 SQL——始终通过 Repository 层
- 永远不要手动修改 Alembic 迁移文件
- 永远不要提交 .env 文件

任务：添加基于 JWT 的用户认证

要求：
1. POST /auth/register — 接收邮箱+密码，返回 JWT
2. POST /auth/login — 接收邮箱+密码，返回 JWT
3. GET /auth/me — 受保护路由，返回当前用户信息
4. 使用 bcrypt 进行密码哈希（cost factor 12）
5. JWT Token 24 小时后过期
6. 添加中间件，拒绝 /api/* 路由上缺少有效 Token 的请求

不要做：
- 使用基于 Session 的认证
- 存储明文密码
- 修改现有路由

实现完成后，更新 docs/api.md 中的 API 文档。

在做出任何修改之前，请分析以下内容：

1. 阅读 src/billing/ 中的支付处理流程
2. 识别为什么订阅续费会产生重复扣款
3. 列出 3-5 个可能的根因，按可能性排序
4. 对每个根因，描述修复方案

分析完成后，等待我确认再开始实现修复。

我需要为 src/services/ 中的所有方法添加错误处理。
以下是我希望你为每个方法遵循的模式：

参考 — getUser 方法在你的修改后应该长这样：
```python
async def get_user(user_id: str) -> UserResponse:
    try:
        user = await self.user_repo.find_by_id(user_id)
        if not user:
            raise UserNotFoundError(user_id)
        return UserResponse.model_validate(user)
    except UserNotFoundError:
        raise  # 让异常处理器处理
    except Exception as e:
        logger.error(f"get_user 意外错误: {e}", exc_info=True)
        raise ServiceError("获取用户失败") from e

### 模式 D：迭代优化循环

最好的结果往往来自对话，而非一次性提示：

1. **提示 1**：「写一个数据导出函数，将查询结果转换为 CSV。」
2. Claude Code 生成基础版本。
3. **提示 2**：「很好。现在添加：(a) 大数据集的流式处理，(b) 进度回调，(c) 可配置的列选择。」
4. Claude Code 优化实现。
5. **提示 3**：「再优化一下：处理边界情况——空结果集、含逗号的列、Unicode 字符。」

每次迭代都建立在前一次的基础上，Claude Code 保持对话的完整上下文。

---

## 3. 上下文窗口管理

Claude Code 在拥有合适上下文时表现最佳——不多（会迷惑）不少（会猜测）。

### Claude Code 默认看到什么

在项目中调用 Claude Code 时：

- **CLAUDE.md**（始终包含）
- **相关文件**（根据你的提示自动检测）
- **Git 状态**（知道什么被修改了）
- **对话历史**（当前会话内）

### 显式添加上下文

使用 `/add` 显式包含文件：

然后发出你的提示。这比指望 Claude Code 自动发现正确文件更可靠。

### 何时开启新会话

上下文窗口会填满。以下信号说明应该 `/clear` 或开新会话：

- Claude Code 开始引用 10 个提示前的文件（已不再相关）
- 回复质量下降（对文件内容的幻觉增加）
- 每次回复的 Token 消耗莫名其妙地激增

**经验法则**：每个主要功能或 Bug 修复开一个新会话。不要让一个会话横跨多个不相关的任务。

---

## 4. 高级提示技术

### 多文件协调

当修改跨越多个文件时，描述完整的依赖链：

显式命名所有文件可以防止 Claude Code 遗漏关键部分。

### 测试优先提示

让 Claude Code 在实现之前先写测试：

这利用了 Claude Code 在测试生成方面的优势，并确保实现由规格驱动。

### 带安全网的重构

重构大型代码库时：

「修改前后运行测试」模式至关重要——它能立即捕获回归。

---

## 5. 需要避免的反模式

### 反模式 1：一锅端提示

太大了。Claude Code 会在所有领域生成肤浅、有 Bug 的代码。拆分为聚焦的、顺序执行的任务——一次一个功能。

### 反模式 2：假设已知信息

什么分页？在哪个文件里？Bug 表现是什么？始终包含：
- 文件路径或组件名
- 期望行为 vs 实际行为
- 错误消息或堆栈跟踪（如果有）

### 反模式 3：矛盾的约束

这些约束相互冲突。明确优先级：什么最重要？如果速度重要，算法可能需要改变。明确说明权衡取舍。

### 反模式 4：过早的实现细节

除非有具体的硬性约束，让 Claude Code 自己做技术选择。它通常会选择比过度指定的指令更好的模式。把超具体的约束保留给真正重要的事情（安全、合规、团队规范）。

---

## 6. 可直接使用的提示模板

### Bug 修复模板

### 功能实现模板

### 代码审查模板

---

## 7. 特定任务提示工程

### 数据库迁移

### API 开发

{
  "items": [...],
  "total": 42,
  "limit": 20,
  "offset": 0
}

### 测试

---

## 8. 衡量提示词质量

如何知道你的提示词质量好坏？追踪以下指标：

### 客观信号
- **首次成功率**：Claude Code 一次就搞定，还是需要 3 次以上修改？
- **Token 效率**：好的提示词产出精准、简洁的代码修改，而非大范围改动
- **Bug 率**：好提示词生成的代码在审查中发现的 Bug 更少

### 主观信号
- **惊喜程度**：你是否经常被 Claude Code 理解意图的准确度惊艳到？
- **迭代次数**：通常需要 1-2 次还是 5-7 次迭代？

### 快速自检

每次 Claude Code 会话结束后，问自己：
1. 我描述的是**构建什么**，而非**怎么构建**吗？（除非「怎么构建」很重要）
2. 我命名了具体的文件和约束吗？
3. 我包含了上下文吗（CLAUDE.md、相关文件、对话历史）？
4. 我把大任务拆成了可管理的块吗？

如果对以上任何一个回答「否」，你的提示词可以更强。

---

## 相关资源

- [Claude Code 知识中心](/tutorials/claude-code-hub) — Claude Code 完整知识库
- [Claude Code FAQ](/tutorials/claude-code-faq-common-questions-2026) — 50+ 常见问题解答
- [Claude Code 工作流模式](/tutorials/claude-code-workflow-patterns-daily-ai-coding-2026) — 日常编码工作流优化
- [Claude Code 完全指南](/tutorials/claude-code-complete-guide-setup-pricing-workflows-2026) — 安装、定价与工作流
- [Claude Code vs Copilot vs Cursor 对比](/tutorials/claude-code-vs-copilot-vs-cursor-indie-hacker-comparison-2026) — 独立开发者视角对比

---
*最后更新：2026 年 7 月。基于数百次跨生产环境的 Claude Code 会话经验总结。*