Prompt 配方库

即用的 prompt 模板——按场景分类，复制粘贴即可使用。每个配方含适用场景、模板文本和注意事项。

项目搭建类

配方 1：从零搭建项目

适用场景： 创建全新项目

帮我搭建一个 [技术栈，如 Express + MongoDB + TypeScript] 项目。
项目结构按模块划分。

需求：
- [需求列表，如用户注册、登录、CRUD]

约束：
- [约束列表，如"用命名导出"、"错误用 AppError 包装"]

完成后运行 npm install 和 npm run dev，确认项目能启动。

注意事项： 需求越具体越好。避免笼统的"做一个完整项目"。

配方 2：搭建项目骨架 + spec

适用场景： 复杂项目，想先写 spec 再执行

帮我在 spec.md 中写项目需求规格，内容如下：
[你的需求描述]

然后基于 spec.md 生成 plan.md 实施计划和 tasks.md 任务清单。
不要直接创建代码文件。

配方 3：添加新模块到现有项目

适用场景： 为已有项目添加新功能模块

在现有项目中添加 [模块名称] 模块。

先读取以下文件了解项目结构：
@src/app.ts（入口文件）、@CLAUDE.md（项目约定）

然后：
1. 在 plan.md 中规划模块结构和文件列表
2. 等我确认后再创建文件

约束：
- 遵循 @CLAUDE.md 中的项目约定
- 不改动现有模块的代码（只新增）

注意事项： 必须让 AI 先读 CLAUDE.md，否则它可能不遵守项目约定。

调试排障类

配方 4：分析 bug 根因

适用场景： 发现 bug，先找根因再修复

用 Plan Mode 分析这个 bug：

现象：[bug 现象]
触发条件：[如何复现]
相关文件：@src/auth/login.ts

列出所有可能的根因和验证方法。不要修改任何代码。

配方 5：修复 bug + 验证

适用场景： 根因已确认，执行修复

修复 [文件名] 中的 [bug 描述]。

根因：[根因描述]
修复方案：[方案描述]

完成后：
1. 运行 [对应测试命令]
2. 确认测试通过
3. 如果测试失败，最多尝试修复两次

配方 6：添加调试日志

适用场景： bug 无法复现，需要加日志定位

在 [文件路径] 的 [关键位置] 添加详细日志，记录：
- [变量名] 的值
- 执行路径（进入哪个分支）
- 时间戳

日志格式：`[模块名] [函数名] [事件描述] data=%j`
使用项目的 logging utility，不要用 console.log。
不要修改业务逻辑。

配方 7：写回归测试

适用场景： bug 已修复，需要防复发

为 [bug 简述] 添加回归测试。
测试名：test_[bug简述]
放在 [对应测试文件] 中。

测试应验证：
- [正常场景]
- [bug 触发场景]（之前出 bug 的条件）

使用项目现有测试框架。

重构迁移类

配方 8：评估重构影响

适用场景： 准备重构，先评估风险

用 Plan Mode 评估重构 [目标模块] 的影响：
1. 列出所有需要变更的文件
2. 分析依赖关系
3. 检查测试覆盖情况
4. 评估风险等级

输出在 plan.md 中。不要修改任何代码。

配方 9：执行重构批次

适用场景： 分批重构执行

执行重构计划的第 [N] 批：
变更文件：[文件列表]

约束：
- 对外接口不变
- 完成后运行 [测试命令]
- 如果测试失败，最多尝试修复两次

配方 10：升级依赖

适用场景： 升级框架或依赖包版本

升级 [包名] 从 [旧版本] 到 [新版本]。

步骤：
1. 阅读 @package.json 了解当前依赖
2. 执行升级命令
3. 修复所有 breaking changes 导致的错误
4. 运行 npm test 确认通过

如果大量测试失败，先分析失败模式再批量修复，不要逐个修。

配方 11：消除重复代码

适用场景： 发现多处重复逻辑

读取 @src/utils/ 下所有文件，找出重复的逻辑。

在 plan.md 中列出：
1. 每组重复代码的位置
2. 建议的重构方案（提取到哪个公共函数）
3. 重构后对现有调用方的影响

不要直接修改代码，等我确认 plan 后再执行。

审查发布类

配方 12：PR 审查

适用场景： 审查代码变更

审查当前分支相对于 main 的所有变更。按以下维度分析：

1. 逻辑正确性（边界遗漏、类型不匹配）
2. 安全隐患（注入、泄露、未授权）
3. 性能风险（N+1、内存泄漏）
4. 架构一致性（是否符合项目约定）
5. 测试覆盖（关键逻辑是否有测试）

按严重程度分类：🔴 严重 / 🟡 中等 / 🟢 低风险
输出 Markdown 表格。

配方 13：安全专项审查

适用场景： 涉及认证/权限/数据处理的变更

对 @src/auth/ 和 @src/middleware/ 下所有文件做安全专项审查。

检查：
1. 输入验证（是否有未验证的输入）
2. 硬编码密钥/token
3. SQL 参数化查询
4. 路径遍历风险
5. 不安全的序列化

输出发现的问题和修复建议。

配方 14：发布前检查

适用场景： 准备发布

执行发布前检查：
1. 运行完整测试套件
2. 搜索残留的 console.log 和 debug 代码
3. 检查是否有硬编码的密钥或 token
4. 确认 .env 文件中无敏感值

列出所有发现的问题。

文档类

配方 15：生成 API 文档

适用场景： 为 API 端点生成文档

为 @src/api/ 下所有端点生成 API 文档。

格式：
- 端点路径和 HTTP 方法
- 请求参数（含类型和验证规则）
- 响应格式（含状态码）
- 错误响应格式
- 示例请求和响应

输出到 docs/api.md。

配方 16：更新 CLAUDE.md

适用场景： 项目约定发生变化

更新 CLAUDE.md，添加以下约定：
[新增约定列表，如"所有 API 路由用 Zod 验证输入"]

保留现有内容，只新增不删除。完成后让我审查。

测试类

配方 17：补写测试

适用场景： 模块缺少测试

为 @src/[模块路径] 补写测试。

规则：
- 使用项目现有测试框架
- 测试文件放在与源文件同目录（或按项目约定位置）
- 覆盖所有公开函数的正常场景和边界场景
- 包括错误处理场景

完成后运行测试确认通过。

配方 18：写 TDD 测试先于实现

适用场景： 用 TDD 方式开发新功能

先为 [功能描述] 写测试，不要写实现代码。

测试应覆盖：
- 正常输入场景
- 边界值场景
- 错误输入场景
- 预期的输出格式

测试写完后运行，确认测试失败（因为还没实现）。
然后告诉我测试列表，我来确认后再开始实现。

安全类

配方 19：添加输入验证

适用场景： API 端点缺少输入验证

为 @src/api/[文件] 的所有端点添加 Zod 输入验证。

约束：
- 使用项目现有的 Zod 版本
- 验证所有请求参数（query、body、path）
- 验证失败返回 400 + 详细错误信息
- 不改动现有测试

完成后运行测试确认没有引入新错误。

配方 20：安全加固 checklist

适用场景： 发布前的安全自查

对项目做安全加固检查：

1. 搜索所有硬编码的密钥、token、密码
2. 检查 .env 是否加入 .gitignore
3. 检查 CORS 配置是否限制来源
4. 检查 cookie 是否设置 secure 和 httpOnly
5. 检查是否使用 HTTPS
6. 检查认证逻辑是否正确（token 过期、刷新机制）

列出所有发现的问题和修复优先级。

使用配方的高级技巧

组合配方： 多个配方可以组合使用。例如：配方 8（评估重构） → 配方 9（执行批次） → 配方 12（审查） → 配方 14（发布检查）。

定制配方： 把常用配方保存为自定义斜杠命令（.claude/commands/ 目录），用 /project:xxx 快速调用。详见自定义斜杠命令。

配方 + CLAUDE.md： 配方中的约束如果每次都要重复，写进 CLAUDE.md 就不用每次手动加了。

社区精选 Prompt

以下 prompt 来自社区精选——经过实战验证的高质量模板。每个配方标注来源、适用场景和为什么有效。

配方 21：代码解释（学习用）

适用场景： 阅读不熟悉的代码库，理解复杂逻辑

请逐行解释 @src/[文件路径] 的代码逻辑。

要求：
1. 对每个函数，说明其输入、输出、副作用
2. 对每个条件分支，说明触发条件和对应的业务含义
3. 标出你认为可能存在的问题或改进点
4. 用通俗语言解释，假设我是刚加入这个项目的新人

为什么有效： 强制 Claude 逐行分析而非概括，输出的结构化解释便于快速上手。

配方 22：生成 Commit Message

适用场景： 写完代码后生成规范的提交信息

分析当前 git diff 的变更内容，生成 Conventional Commits 格式的 commit message。

格式：
<type>(<scope>): <subject>

<body>

<footer>

类型可选：feat / fix / docs / style / refactor / perf / test / chore

要求：
- subject 不超过 50 字符，用中文
- body 说明改了什么、为什么改
- footer 标注是否包含 breaking change

不要提交，只生成 message 让我确认。

为什么有效： Conventional Commits 是业界标准格式，Claude 能准确分类变更类型并生成结构化描述。

配方 23：架构设计评审

适用场景： 在实现新功能前评审架构设计

你是一位有 10 年经验的高级软件架构师。

请评审以下架构设计（见 @docs/architecture/design.md）：

评审维度：
1. 可扩展性：当前设计能否支撑未来 10 倍流量增长？
2. 可维护性：模块边界是否清晰？耦合度是否过高？
3. 可测试性：关键逻辑是否可独立测试？
4. 技术风险：是否有单点故障？是否有技术选型风险？
5. 成本：当前方案的成本效益如何？

对每个问题给出：严重程度（高/中/低）+ 具体改进建议。

配方 24：性能分析与优化建议

适用场景： 定位性能瓶颈并获取优化方案

分析 @src/[模块路径] 的性能特征。

请：
1. 找出可能的性能瓶颈（N+1 查询、内存泄漏、不必要计算）
2. 对每个瓶颈估算影响程度（CPU 密集 / IO 密集 / 内存密集）
3. 给出具体的优化方案和预期提升
4. 标注"快速修复"（5 分钟内能改）和"深度优化"（需要重构）

输出 Markdown 表格，按严重程度排序。

配方 25：生成 README 文档

适用场景： 为项目生成完整的 README

基于当前项目结构和代码，生成一份专业的 README.md。

必须包含：
1. 项目简介（一句话说清楚做什么）
2. 技术栈列表
3. 快速开始（安装 + 运行步骤）
4. 项目结构说明（目录树 + 每个目录的作用）
5. 环境变量说明（.env 模板）
6. API 端点概览（如果有）
7. 开发指南（代码规范、测试命令、部署流程）
8. License

参考 @package.json 和 @src/ 目录结构生成。

为什么有效： Claude 能扫描整个项目结构，生成的 README 与项目实际结构完全匹配，不会出现过时信息。

配方 26：代码翻译成另一种语言

适用场景： 将代码从一种语言翻译为另一种

将 @src/utils/helpers.js（JavaScript）翻译为 TypeScript。

要求：
1. 保持逻辑完全一致
2. 添加完整的类型注解
3. 使用 TypeScript 特有特性（如泛型、联合类型）改善类型安全
4. 保留所有注释
5. 输出到 src/utils/helpers.ts

翻译完成后，对比原文件和新文件，确认行为一致。

配方 27：错误日志分析

适用场景： 分析生产环境错误日志

以下是一段生产环境错误日志：

[粘贴错误日志]


请分析：
1. 错误的根本原因是什么？
2. 调用链中哪个环节出了问题？
3. 受影响的功能范围有多大？
4. 建议的修复方案是什么？
5. 如何防止类似问题再次发生？

如果有不确定之处，请说明"需要更多信息"而非猜测。

为什么有效： 第 5 点特别重要——防止 Claude 在信息不足时胡乱猜测，引导它诚实说明不确定性。

配方 28：生成单元测试模板

适用场景： 为新功能快速生成测试框架

为 @src/services/UserService.ts 生成完整的单元测试文件。

要求：
1. 使用项目现有测试框架（参考 @jest.config.js 或 @vitest.config.ts）
2. 每个公开函数至少包含：
   - 正常场景测试
   - 边界条件测试
   - 错误处理测试
3. Mock 外部依赖（数据库、API 调用）
4. 测试命名：describe('[函数名]', () => { it('should [行为描述]', ...) })
5. 测试文件放在 src/services/__tests__/UserService.test.ts

生成后运行测试确认通过。

配方 29：正则表达式生成器

适用场景： 写复杂的正则表达式

帮我写一个正则表达式，匹配以下规则：

[描述规则，例如："中国大陆手机号，11 位数字，以 13/15/18 开头"]

要求：
1. 给出正则表达式
2. 逐段解释每部分的含义
3. 提供 3 个匹配示例和 3 个不匹配示例
4. 给出在 JavaScript 和 Python 中的使用示例

配方 30：SQL 查询优化

适用场景： 优化慢查询

分析以下 SQL 查询的性能问题：

```sql
[粘贴 SQL]

请：

指出可能导致慢查询的原因（全表扫描、缺少索引、JOIN 过多等）
给出优化后的 SQL
说明需要创建哪些索引
预估优化后的性能提升


---

### 配方 31：API 接口迁移

**适用场景：** 重构 API 接口（如 REST → GraphQL，或 v1 → v2）

将 @src/api/v1/users.ts 中的 REST API 端点迁移到 v2 版本。

迁移规则：

GET /v1/users → GET /v2/users（响应格式变更，见下方）
POST /v1/users/create → POST /v2/users
PUT /v1/users/:id → PATCH /v2/users/:id
DELETE /v1/users/:id → DELETE /v2/users/:id

v2 响应格式： { "data": { ... }, "meta": { "page": 1, "total": 100 }, "links": { "self": "...", "next": "..." } }

约束：

v1 接口保留向后兼容
更新对应的测试
在 CHANGELOG.md 中记录变更

先列出迁移清单，确认后执行。


---

### 配方 32：Git 历史分析

**适用场景：** 了解代码变更历史

分析当前项目的 Git 历史：

用 git log --oneline -50 查看最近的 50 次提交
用 git log --since="1 month ago" --no-merges --format="%an" | sort | uniq -c 统计贡献者
用 git diff main..HEAD 查看当前分支变更摘要

输出：

过去一个月的主要变更摘要
贡献者活跃度
当前分支相对于 main 的差异统计


---

### 配方 33：Docker 容器化配置

**适用场景：** 为项目添加 Docker 支持

为当前项目生成 Docker 化配置文件。

需要创建：

Dockerfile（多阶段构建，优化镜像大小）
docker-compose.yml（本地开发环境）
.dockerignore（排除不必要的文件）

要求：

使用 alpine 基础镜像减小体积
多阶段构建：build 阶段编译，production 阶段只保留运行时依赖
非 root 用户运行
健康检查端点配置

参考 @package.json 了解项目依赖和构建脚本。


---

### 配方 34：CI/CD Pipeline 配置

**适用场景：** 为项目配置 CI/CD

为当前项目生成 GitHub Actions CI/CD 配置文件。

流程：

Push 时：运行 lint + test + build
PR 时：运行 lint + test + build，在 PR 中显示状态
打 tag 时：构建 Docker 镜像并推送到 GHCR

要求：

使用 Node.js 20
缓存 node_modules
失败时通知（在 step 中添加 TODO 标注）
并行运行 lint 和 test 加快速度

输出到 .github/workflows/ci.yml。


---

### 配方 35：技术债务评估

**适用场景：** 量化项目的技术债务

对当前项目做技术债务评估。

检查项：

TODO / FIXME / HACK / XXX 注释数量和分布
超过 300 行的文件
缺少类型注解的代码（any 使用）
未使用的导入
过期依赖
缺少测试的文件

输出 Markdown 表格：

文件	问题	严重程度	预估修复时间

按严重程度排序，标注"快速修复"（< 10 分钟）的项目。


---

### 配方 36：生成变更日志

**适用场景：** 发布前生成 CHANGELOG

基于 git log 生成版本变更日志。

规则：

只包含 main 分支的提交
按 Conventional Commits 类型分组（feat/fix/docs/perf 等）
过滤 merge commit 和 chore 类型的内部提交
每个变更附带 commit hash 链接

格式：

[版本号] - 日期

Added

Fixed

Changed

输出到 CHANGELOG.md，追加到文件开头。


---

### 配方 37：依赖安全审计

**适用场景：** 检查第三方依赖的安全性

对当前项目做依赖安全审计。

步骤：

运行 npm audit --json 获取已知漏洞
分析每个漏洞：
- 严重程度
- 受影响版本
- 修复方案（升级/替代方案）
- 是否在当前项目中实际被使用
检查 package.json 中是否有长期未更新的依赖

输出修复建议表：

依赖	漏洞	严重程度	当前版本	安全版本	修复建议


---

### 配方 38：数据库迁移脚本

**适用场景：** 修改数据库 Schema

基于以下 Schema 变更需求，生成数据库迁移脚本：

变更内容：

users 表新增 avatar_url 字段（VARCHAR(255), nullable）
users 表的 email 字段改为唯一约束
posts 表新增 status 字段（ENUM: 'draft', 'published', 'archived'）
删除 deprecated_table 表

要求：

生成 up 和 down 迁移脚本
包含数据迁移逻辑（如果需要）
添加适当的注释
使用项目现有的迁移框架（参考 @prisma/migrations/ 或 @migrations/）

先输出迁移计划，确认后再创建文件。


---

### 配方 39：代码异味检测

**适用场景：** 快速扫描代码质量问题

扫描 @src/ 目录，检测以下代码异味（Code Smells）：

上帝类（God Object）：一个类/文件做了太多事情
长函数（Long Method）：超过 50 行的函数
深层嵌套：超过 4 层嵌套的条件判断
重复代码：多处相似的逻辑
过长的参数列表：超过 5 个参数的函数
魔法数字：没有命名常量的硬编码数字/字符串

对每个问题给出：

文件路径和行号
问题描述
建议的重构方向


---

### 配方 40：Prompt 自优化

**适用场景：** 让 Claude 帮你优化 prompt

我写了以下 prompt 来让 Claude 帮我 [任务描述]：

""" [你的 prompt] """

请评估这个 prompt 的质量并给出改进建议。评估维度：

具体性：是否足够明确？
完整性：是否缺少关键信息？
约束性：是否有足够的约束？
结构性：格式是否清晰？
可执行性：Claude 能否准确理解并执行？

给出改进后的 prompt 版本。


**为什么有效：** 用 AI 优化 AI 的 prompt，形成正向循环。Claude 很擅长识别 prompt 中的模糊之处并给出改进建议。

---

## Prompt 模板速查

以下是常见场景的一句话 prompt 模板：

| 场景 | Prompt 模板 |
|------|-----------|
| 解释代码 | "逐行解释 @[文件] 的逻辑，假设我是项目新人" |
| 找 bug | "分析 @[文件] 中潜在的 bug 和边界条件问题" |
| 优化性能 | "找出 @[文件] 中的性能瓶颈并给出优化建议" |
| 重构建议 | "评估重构 @[函数] 的风险，列出影响范围和方案" |
| 写文档 | "为 @[文件] 生成 JSDoc 格式的完整注释" |
| 写测试 | "为 @[函数] 补写单元测试，覆盖正常和边界场景" |
| 代码翻译 | "将 @[文件] 从 [语言A] 翻译为 [语言B]，保持逻辑一致" |
| 安全审计 | "对 @[目录] 做安全审查，检查注入/泄露/未授权风险" |
| 生成配置 | "基于项目结构生成 [Dockerfile/CI配置/.env模板]" |
| 生成文档 | "基于 @package.json 和 @src/ 生成 README.md" |

## 如何选择 Prompt

**按任务复杂度选择：**

- **简单任务（< 5 分钟）：** 用一句话模板，直接描述需求
- **中等任务（5-30 分钟）：** 用上面的配方模板，包含约束和验证
- **复杂任务（30 分钟+）：** 先用 Plan Mode 分析，再用配方模板分步执行

**按风险等级选择：**

- **低风险（个人项目/实验代码）：** 直接描述，Auto-Accept 模式
- **中风险（团队项目/非核心模块）：** 用配方模板，Normal 模式
- **高风险（生产代码/核心模块）：** Plan Mode + 配方模板 + 人工审查

Prompt 配方库 ​

项目搭建类 ​

配方 1：从零搭建项目 ​

配方 2：搭建项目骨架 + spec ​

配方 3：添加新模块到现有项目 ​

调试排障类 ​

配方 4：分析 bug 根因 ​

配方 5：修复 bug + 验证 ​

配方 6：添加调试日志 ​

配方 7：写回归测试 ​

重构迁移类 ​

配方 8：评估重构影响 ​

配方 9：执行重构批次 ​

配方 10：升级依赖 ​

配方 11：消除重复代码 ​

审查发布类 ​

配方 12：PR 审查 ​

配方 13：安全专项审查 ​

配方 14：发布前检查 ​

文档类 ​

配方 15：生成 API 文档 ​

配方 16：更新 CLAUDE.md ​

测试类 ​

配方 17：补写测试 ​

配方 18：写 TDD 测试先于实现 ​

安全类 ​

配方 19：添加输入验证 ​

配方 20：安全加固 checklist ​

使用配方的高级技巧 ​

社区精选 Prompt ​

配方 21：代码解释（学习用） ​

配方 22：生成 Commit Message ​

配方 23：架构设计评审 ​

配方 24：性能分析与优化建议 ​

配方 25：生成 README 文档 ​

配方 26：代码翻译成另一种语言 ​

配方 27：错误日志分析 ​

配方 28：生成单元测试模板 ​

配方 29：正则表达式生成器 ​

配方 30：SQL 查询优化 ​

[版本号] - 日期 ​

Added ​

Fixed ​

Changed ​