同样是Claude Code，为什么别人用它能一次写出可用的生产代码，而你反复让它改5次还不满意？差距不在模型能力——在你的提示词。今天分享10个实战验证过的Claude Code提示词技巧，每个都有可复制的模板。
你肯定经历过这个
打开Claude Code，输入"帮我写一个用户登录接口"。它给了你一段代码——Flask写的，用了明文密码存储，没有token刷新机制，还没有输入验证。
你告诉它"用FastAPI重写"，它又给了你一段——这次框架对了，但密码哈希用的MD5，JWT密钥硬编码，目录结构一团乱。
问题出在哪？不是Claude不够聪明，是你的提示词不够精确。
好的提示词像一个清晰的Sprint Ticket——技术栈、输入输出、边界条件、代码规范一目了然。今天我从实际项目中总结了10个技巧，覆盖从需求描述到错误修正的完整流程。
技巧1：用"角色+上下文+约束"三段式代替一句需求
这是最基础也最容易被忽视的技巧。
❌ 差的提示词：
帮我写一个用户注册功能
✅ 好的提示词：
你是一个资深Python后端工程师，项目使用FastAPI + SQLAlchemy + PostgreSQL。
请实现用户注册API：
技术约束：
- 密码使用bcrypt哈希（werkzeug.security）
- 返回JWT token（使用python-jose，密钥从环境变量JWT_SECRET读取）
- 邮箱格式验证
- 密码最少8位，包含大小写字母和数字
- 使用Pydantic v2做请求验证
- 遵循项目现有的三层架构：router → service → repository
输入：email, password, username
输出：{ "token": "xxx", "user": { "id": 1, "email": "...", "username": "..." } }
错误情况：邮箱已注册返回409，验证失败返回422
为什么有效：Claude需要三个维度的信息——
- 角色定义了它的知识范围和代码风格
- 上下文给了它技术栈和环境约束
- 约束消除了模糊地带（密码怎么哈希？错误码是什么？）
技巧2：给出反例——告诉AI"不要这样做"
大多数人只告诉AI要做什么，但没告诉它不要做什么。这导致AI踩到你项目里的隐式规则。
构建产品列表API时，注意以下反模式：
❌ 不要在router层写SQL查询（所有数据库操作在repository层）
❌ 不要使用SELECT *（显式列出需要的字段）
❌ 不要返回数据库model对象（始终转换为Pydantic schema）
❌ 不要裸except（至少捕获具体异常并记录日志）
❌ 不要硬编码分页参数（从查询参数读取，默认page=1, size=20）
实战效果：在一个有严格分层架构的项目里，加了这一段后，Claude生成代码的架构合规率从40%提升到90%。
技巧3：提供"参考实现"——用现有代码做样本
Claude Code可以读取你项目里的文件。让它参考现有代码风格是最直接的方法。
在实现新的API端点之前，请参考以下文件了解项目规范：
- src/api/v1/products.py — 学习router层的错误处理和响应格式
- src/services/product_service.py — 学习service层的事务管理模式
- src/schemas/product.py — 学习Pydantic schema的定义方式
- tests/test_products.py — 学习测试的fixture和mock模式
新端点应该与这些文件保持一致的：
- 导入顺序（标准库 → 第三方 → 项目内部）
- 命名规范（snake_case，私有方法用_前缀）
- 异常处理模式（抛出自定义BusinessException）
- 日志记录格式（使用structlog）
关键点：不要只说"参考现有代码"，要具体指出参考哪些文件，以及从每个文件里学什么。这样Claude会实际读取这些文件并理解其中的模式。
技巧4：分层要求——先给骨架再填血肉
一次性要求AI写完整实现，往往得到"看似完整但经不起推敲"的代码。
请分两步完成这个功能：
第1步：只写函数签名、类型注解和docstring
- 定义所有类和函数的接口
- 写清楚每个参数的用途和返回值
- 标注可能的异常
（等我确认接口设计后，再进行第2步）
第2步：实现函数体
为什么有效：分两步让Claude先做"设计"再做"实现"。你可以在第1步后快速验证接口设计是否正确，避免AI在错误的方向上写了一大堆代码。
技巧5：明确"完成的定义"——什么是Done
程序员和PM之间最大的沟通问题就是"完成"的定义。给AI交代任务也一样。
这个功能"完成"的标准：
✅ 所有CRUD端点通过curl可调用
✅ 使用项目的统一响应格式 {"code": 0, "data": ..., "message": "ok"}
✅ 包含输入验证（Pydantic validator）
✅ 数据库迁移文件已生成（alembic revision --autogenerate）
✅ 包含单元测试（覆盖率 > 80%）
✅ 包含API文档注释（FastAPI会自动生成OpenAPI文档）
✅ 敏感配置从环境变量读取（不要硬编码）
请在实现完成后，自己运行以下命令验证：
pytest tests/test_user_api.py -v
让AI自己验证：在"完成标准"里要求AI运行测试或其他验证命令，它会在实现后自动执行。
技巧6：时间旅行——"如果是2025年的你会怎么写？"
Claude的知识截止日期意味着它可能使用过时的API或库版本。
注意：现在是2026年7月。请使用以下版本的最新API：
- FastAPI >= 0.115.0（注意：@app.on_event已弃用，使用lifespan）
- Pydantic v2（使用model_validator而非root_validator）
- SQLAlchemy 2.0风格（使用select()函数而非Model.query）
- Python 3.12+（使用新语法：type alias用type关键字，泛型用新语法）
如果你不确定某个API在最新版本中的写法，请先搜索确认。
技巧7：具体化输出格式——"我要Markdown表格而不是段落"
Claude默认用自然语言回复。但很多时候你需要的是结构化输出。
请以以下格式输出代码审查结果：
## 审查摘要
| 严重程度 | 数量 |
|----------|------|
| 🔴 Critical | 2 |
| 🟡 Warning | 5 |
| 🔵 Info | 3 |
## Critical Issues
1. **SQL注入风险** (`src/api/login.py:45`)
- 问题：使用字符串拼接构建SQL
- 修复：使用参数化查询
```python
# 修复前（第45行）
query = f"SELECT * FROM users WHERE email='{email}'"
# 修复后
query = "SELECT * FROM users WHERE email=:email"
```
## Warnings
...（以此类推）
技巧8：场景化需求——"新手用户vs老手用户"
让AI从不同用户视角思考，能发现你遗漏的边界情况。
这个API需要考虑三种调用场景：
场景A — 新用户首次注册：
- 邮箱未注册 → 返回200 + 创建用户
- 引导填写个人资料
场景B — 老用户重复注册：
- 邮箱已存在 → 返回409 + "该邮箱已注册，是否要登录？"
- 附带登录页链接
场景C — 恶意批量注册：
- 同一IP 1分钟内超过5次 → 返回429 + 触发风控
- 记录到风控日志
请在实现时覆盖这三种场景的测试用例。
技巧9：渐进式修正——"只改X，不要动Y"
AI在修改代码时经常"顺手"重构不相关的部分。这很危险。
需要修改：将用户认证从JWT改为Session-based
修改范围（只改这些）：
✅ auth_router.py — 登录/登出端点
✅ middleware/auth.py — 认证中间件
✅ models/session.py — 新增Session模型
禁止修改（即使你觉得可以优化）：
❌ user_router.py — 用户CRUD端点
❌ config.py — 配置文件
❌ 任何测试文件（我会单独处理）
❌ 数据库迁移（我手动管理alembic）
如果发现需要修改的范围超出上述列表，请先告知我，不要自作主张。
技巧10：将CLAUDE.md当作"项目宪法"
前面9个技巧都可以写进CLAUDE.md文件里，让Claude每次打开项目时自动加载。
# CLAUDE.md
## 项目技术栈
- Python 3.12+, FastAPI 0.115+, SQLAlchemy 2.0, PostgreSQL 16
- 架构：router → service → repository 三层分离
- 测试：pytest + pytest-asyncio，覆盖率要求 > 80%
## 代码规范（不可协商）
- 所有数据库操作在repository层，router/service层不写SQL
- 异常使用自定义BusinessException(code=..., message=...)
- 密码使用bcrypt（werkzeug.security）
- 配置从环境变量读取，禁止硬编码
- 导入顺序：标准库 → 第三方 → 项目内部（空行分隔）
## 反模式（永远不要）
- SELECT *
- 裸except:
- 在循环中执行数据库查询（使用批量操作）
- 返回数据库model给API响应（始终转Pydantic）
## 完成标准
- 所有端点可通过curl测试
- 包含单元测试
- 输入有Pydantic验证
- 错误响应使用统一格式 {"code": ..., "message": ...}
把这个文件放在项目根目录，Claude Code每次启动都会读取它。相当于每次对话前都"喂"了一遍项目规范。
进阶组合：多技巧联用实例
来看一个实战案例——用技巧1+2+3+5组合写一个完整的文件上传功能：
【角色】你是资深FastAPI后端工程师
【上下文】项目在 src/ 目录下，使用三层架构，文件存储用MinIO
【参考实现】
- 参考 src/api/v1/documents.py 的router层写法
- 参考 src/services/storage_service.py 的MinIO客户端封装
【约束】实现文件上传API POST /api/v1/files/upload
- 文件大小限制10MB（在中间件配置）
- 允许类型：jpg/png/pdf/docx
- 上传到MinIO后返回访问URL（预签名，有效期1小时）
- 文件元信息存入PostgreSQL（文件名、大小、类型、上传者ID、minio路径）
- 使用Pydantic v2做响应schema
【反模式】
❌ 不要把文件内容读到内存再上传（使用流式上传）
❌ 不要直接返回minio内网URL（生成预签名URL）
❌ 不要忽略文件类型校验
【完成标准】
✅ 上传一个2MB的jpg文件，返回200 + 预签名URL
✅ 上传一个.exe文件，返回422
✅ 上传一个15MB的png，返回413
✅ 包含3个测试用例
用这个提示词，Claude Code一次性给出了包含流式上传、类型校验、预签名URL生成的完整代码——0次修改。
总结
提示词工程不是玄学，是可复制的技巧：
- 三段式 > 一句话需求
- 给反例 > 只说要求
- 给参考 > 抽象描述
- 分步骤 > 一步到位
- 给标准 > 说"做好"
- 指定版本 > 假定最新
- 指定格式 > 自由发挥
- 给场景 > 单一视角
- 限定范围 > 放开手脚
- 写入CLAUDE.md > 每次重复
一个成熟的AI程序员不是把Claude当"代码生成器"，而是把它当"初级工程师"——给它清晰的Sprint Ticket、明确的技术规范、可验证的完成标准。你花10分钟写好提示词，省下的是2小时的反复修改。