附录 D：Prompt 模板速查
本附录整理自第 28 章，将常用 Prompt 模板按使用场景分类，方便日常快速查阅和复制使用。每个模板包含三个要素：模板名称、适用场景、可直接填空的模板文本。模板中的 {花括号} 部分需要替换为你的实际内容。
D.1 代码生成
组件 / 模块创建
适用场景：创建新的 UI 组件、服务模块、API 端点。
你是一个资深的 {技术栈} 开发者。
在 {目录路径} 下创建一个 {名称}，功能是 {功能描述}。
要求：
- 使用 {语言} + {框架}
- 遵循项目中现有的代码风格，参考 {已有文件路径}
- 导出完整的类型定义（interface/type）
- 包含以下状态处理：
- 加载中（loading）
- 错误（error，含用户友好的错误提示）
- 空数据（empty）
- 正常渲染
- 需要处理的边界情况：{列出边界情况}
- 包含基础的单元测试（{测试框架}）
约束：
- 不要修改已有文件
- 不要引入新的依赖
- 使用 {具体技术选择，如：CSS Modules / Tailwind / styled-components}
输出顺序：
1. 先列出 {关键接口/类型} 的类型定义
2. 再给出实现代码
3. 最后给出测试用例API 端点创建
适用场景：创建 REST API 端点、GraphQL resolver、gRPC 服务方法。
在 {文件路径} 中新增一个 API 端点。
功能：{端点功能描述}
技术栈：{框架} + {语言}
规格：
- 路径：{HTTP 方法} {URL 路径}
- 请求参数：{参数描述}
- 响应格式：{响应结构}
- 错误码：{自定义错误码}
约束：
- 遵循项目中现有的 API 风格（参考 {已有端点文件}）
- 复用已有的 {中间件/校验/工具函数}
- 不改变现有路由前缀
- 包含输入校验和错误处理
- 包含集成测试
输出：实现代码 + 测试用例 + curl 示例快捷生成
适用场景：简单、明确的创建任务，不需要详尽的约束。
在 {目标目录} 下创建一个 {组件/模块名}。
功能：{一句话描述}
要求：
- {语言/框架}
- 遵循 {参考文件} 的代码风格
- 包含基础的错误处理
约束：不要修改已有文件，不要引入新依赖。D.2 代码分析
全面代码审查
适用场景：对单个文件或模块进行系统性代码审查。
你是一个代码审查专家，擅长发现逻辑错误、性能瓶颈和安全隐患。
请分析 {文件路径} 中的 {函数/类/模块名}，从以下维度进行审查：
1. **逻辑正确性**：是否存在逻辑错误、边界情况遗漏、条件判断缺陷
2. **性能**：是否存在不必要的计算、内存泄漏、N+1 查询
3. **错误处理**：异常是否被正确处理、错误信息是否有用
4. **安全性**：是否存在注入风险、敏感信息泄露、权限校验缺失
5. **可维护性**：命名是否清晰、函数是否过长、职责是否单一
6. **类型安全**：是否存在 any 逃逸、类型断言是否安全
输出格式：
先给出总体评分（1-10 分），然后以表格列出所有问题，
表头为：编号 | 维度 | 严重程度（致命/严重/一般/建议） | 位置（行号） | 问题描述 | 修复建议
最后给出优先修复顺序建议。Bug 排查
适用场景：定位特定 bug 的根因。
分析 {文件路径} 中的 {函数名}，找出导致 {bug 现象} 的原因。
相关线索：
- 复现步骤：{操作步骤}
- 预期行为：{期望结果}
- 实际行为：{实际结果}
- 相关日志：{日志片段}
请：
1. 逐行分析可能导致该 bug 的逻辑路径
2. 标注最可能的根因（给出置信度）
3. 提出修复方案（含具体代码变更）
4. 说明如何验证修复有效性能分析
适用场景：分析代码性能瓶颈。
你是一个性能优化专家。
分析 {文件路径} 中 {函数/模块} 的性能特征，重点关注：
- 时间复杂度：是否存在 O(n²) 或更差的算法
- 空间复杂度：是否存在不必要的内存分配
- I/O 模式：是否存在阻塞调用、重复读取
- 渲染性能：是否存在不必要的重渲染（前端）
对每个发现的性能问题，给出：
- 问题位置（行号）
- 当前复杂度 / 预期复杂度
- 可量化的优化方案
- 预估的优化收益（百分比或倍数）快速分析
适用场景：快速概览，不需要全面审查。
分析 {文件路径} 的 {函数/模块名}。
请关注：
1. 逻辑是否正确
2. 性能是否有优化空间
3. 错误处理是否完整
4. 是否有安全隐患
用表格形式输出问题清单，按严重程度排序。D.3 重构
大规模重构（分阶段）
适用场景：涉及多文件的重构，如回调改 async/await、迁移状态管理方案。
你是一个重构专家，擅长在不改变外部行为的前提下优化代码结构。
重构目标：{文件路径或模块名}
当前痛点：{描述为什么要重构}
约束：
- 不改变外部行为（所有现有测试必须通过）
- 保持 API 接口兼容（调用方不需要修改）
- 使用 {目标模式，如：策略模式 / async/await / 依赖注入}
- 不要一次修改超过 {N} 个文件
执行流程：
1. **分析阶段**：先读取目标文件，理解当前结构，列出所有需要修改的地方
2. **计划阶段**：给出分步重构计划（每步可独立验证），等待我确认
3. **执行阶段**：逐步执行，每完成一步后运行相关测试
4. **总结阶段**：输出变更摘要
确认后再开始执行。提取函数 / 组件
适用场景：将过长函数或过大组件拆分为更小的可复用单元。
重构 {文件路径} 中的 {函数名/组件名}。
当前问题：{函数过长 / 职责混杂 / 重复逻辑}
目标：
- 将 {目标函数} 拆分为 {N} 个职责单一的小函数
- 提取可复用的 {工具函数 / 自定义 Hook / 子组件} 到 {目标文件路径}
- 保持对外接口不变
约束：
- 不改变调用方的使用方式
- 已有测试全部通过
- 遵循单一职责原则
先列出拆分方案让我确认，再执行。迁移技术方案
适用场景：从一个库/框架迁移到另一个，如 Vue 2 → Vue 3、Webpack → Vite。
将 {源文件/模块} 从 {旧技术} 迁移到 {新技术}。
迁移范围：{文件列表或目录}
关键差异需要处理：
- {差异点 1：如 API 名称变化}
- {差异点 2：如配置格式变化}
- {差异点 3：如生命周期变化}
约束：
- 功能和行为保持不变
- 迁移后所有测试通过
- 每迁移一个文件就验证一次
参考：官方迁移指南 {URL}，项目中已完成迁移的文件 {已有迁移文件路径}。快捷重构
适用场景：简单、明确的重构，如重命名、调整目录结构。
重构 {文件路径}，把 {当前实现方式} 改为 {目标实现方式}。
约束：不改变外部行为，保持接口兼容。D.4 调试
错误诊断
适用场景：根据错误堆栈或异常现象排查问题。
我遇到了以下问题：
错误信息：
{粘贴完整的错误堆栈或现象描述}
环境信息：
- 运行环境：{Node 版本 / 浏览器 / OS}
- 相关依赖版本：{列出关键依赖}
- 最近改动：{简要描述最近的代码变更}
相关文件：
- {文件路径 1}
- {文件路径 2}
请帮我：
1. 分析可能的根因（按可能性排序）
2. 为每个可能的原因给出验证方法（怎么确认或排除）
3. 对确认的原因给出修复方案
4. 如果以上都无法解决，告诉我还需要哪些额外信息日志分析
适用场景：从大量日志中定位问题。
分析以下日志，找出 {异常现象} 的原因。
日志内容：
{粘贴日志片段，至少包含异常前后的上下文}
关注点：
- 时间线是否异常（如请求耗时突增）
- 错误模式和频率
- 关联的请求 ID 或用户 ID
请：
1. 标注日志中的关键异常行
2. 推断异常发生的时间线和因果链
3. 指出需要进一步排查的代码位置
4. 给出临时缓解方案和根本修复方案竞态条件排查
适用场景：排查异步操作导致的竞态条件问题。
排查 {文件路径} 中 {异步操作} 可能存在的竞态条件。
现象：{偶发 bug 描述，如：有时数据更新丢失}
相关异步操作：
- {操作 1}
- {操作 2}
请：
1. 画时序图展示可能发生竞态的执行顺序
2. 标注竞态窗口（race window）
3. 给出消除竞态的方案（如加锁、队列化、取消过期请求）
4. 说明如何复现和验证修复快速调试
适用场景：快速定位，不需要完整分析。
{错误信息}
帮我分析原因并给出修复方案。相关文件：{文件路径}。D.5 文档
API 文档生成
适用场景：为模块或 API 生成完整的使用文档。
你是一个技术文档撰写者。
为 {模块名/API名} 生成使用文档。
需要覆盖的内容：
- 功能说明（1-2 句话）
- 安装或引入方式
- API 参考（每个公开方法的参数、返回值、异常）
- 使用示例（至少 2 个典型场景的完整代码）
- 注意事项和常见陷阱
格式：Markdown
参考风格：{项目中已有的文档文件路径}
约束：
- 使用中文
- 代码示例需要是可运行的
- 不要重复源代码中已有的实现细节
- 面向的读者是 {初学者 / 有经验的开发者 / API 使用者}README 生成
适用场景：为项目或子模块生成 README。
为 {项目名/模块名} 生成 README.md。
项目简介：{一句话描述}
需要包含的章节：
- 项目名称和简介
- 快速开始（安装、配置、运行）
- 主要功能
- 项目结构
- 技术栈
- 开发指南（本地开发、构建、测试）
- 贡献指南
- License
约束：
- 使用中文
- 命令示例确保可运行
- 参考当前项目的实际结构和配置代码注释补全
适用场景：为缺少注释的代码补充 JSDoc / docstring。
为 {文件路径} 中的所有公开函数和类型补充 JSDoc 注释。
要求：
- 每个函数：描述、@param、@returns、@throws（如有）
- 每个类型/接口：描述、每个字段的含义
- 不修改任何实现代码，只添加注释
- 注释使用中文快捷文档
适用场景：快速生成简单文档。
为 {函数名/组件名} 写使用文档。包含：功能说明、参数列表、返回值、1 个使用示例。用 Markdown 格式。D.6 项目理解
新项目探索
适用场景：刚接手一个项目，需要快速理解整体架构。
你是一个系统架构师，擅长快速理解陌生项目的结构和设计。
请帮我理解这个项目：
1. 先读取顶层目录结构和 package.json（或等效的构建配置文件）
2. 读取 README.md 和 CLAUDE.md（如果存在）
3. 分析 src/（或主代码目录）的目录结构
4. 识别主要的模块和它们的职责
5. 梳理模块间的依赖关系
输出格式：
- 项目概述（3-5 句话）
- 技术栈清单（框架、主要依赖）
- 目录结构图（Mermaid 或树形）
- 核心模块说明（表格：模块名 | 路径 | 职责 | 依赖的其他模块）
- 关键入口文件标注
- 上手建议（按什么顺序阅读代码最有效率）模块深入理解
适用场景：需要深入理解某个特定模块的设计和实现。
深入分析 {模块路径}。
请：
1. 列出该模块所有公开的函数/类及其职责
2. 梳理内部调用链（用 Mermaid 流程图）
3. 标注关键设计模式（如单例、工厂、观察者）
4. 指出该模块对外部模块的依赖点
5. 如果有测试文件，分析测试覆盖了哪些场景
6. 指出可能的改进点
输出按上述六个部分组织，先总览后细节。调用链追踪
适用场景：追踪一个功能或 API 调用的完整执行路径。
从 {入口函数/API 端点} 开始，追踪完整的调用链。
追踪范围：{限定目录，如 src/api/}
输出：
1. Mermaid 时序图展示完整调用链（包含跨文件跳转）
2. 每个节点的职责说明（文件:行号）
3. 关键数据流转标注（什么数据在哪里被转换）
4. 错误处理路径（异常在哪一层被捕获和处理）
只追踪 {入口} 直接触发或间接调用的代码路径，不要展开无关分支。技术债评估
适用场景：评估项目的技术债和代码质量。
评估 {目录路径} 的代码质量和技术债。
请从以下维度评估：
- 代码重复：是否存在复制粘贴的代码块
- 命名一致性：同一概念是否使用了不同的命名
- 文件组织：文件大小是否合理，目录结构是否清晰
- 依赖方向：是否存在循环依赖或依赖方向混乱
- 类型安全：TypeScript any 使用率、类型断言的安全性
- 测试覆盖：关键路径是否有测试保护
输出：按以上维度分别给出评估（优良中差）+ 代表性示例 + 改进优先级建议。D.7 Git 操作
Commit Message 生成
适用场景：根据当前变更自动生成符合规范的 commit message。
查看当前的 git diff，为这次变更生成一个 commit message。
要求：
- 使用中文
- 格式：{类型}: {简要描述}
- 变更内容和原因（2-3 句）
- 类型从以下选择：feat / fix / refactor / docs / style / test / chore / perf
- 描述变更时说明"做了什么"和"为什么做"
- 不要超过 72 个字符的标题行PR 描述生成
适用场景：对比当前分支和目标分支，生成 Pull Request 描述。
对比当前分支和 {目标分支，如 main} 的差异，
生成一份 Pull Request 描述，包含以下章节：
## 变更概述
（1-2 句话说明这个 PR 做了什么）
## 主要改动
（按文件或模块列出关键改动，每条 1-2 句话）
## 影响范围
（哪些模块/功能可能受影响）
## 测试说明
（如何验证这个 PR 的改动是否正确）
## 截图/录屏（如有 UI 变更）
（留空，由提交者手动补充）
约束：
- 使用中文
- 技术术语保持英文
- 如果变更涉及 breaking change，必须在开头显式标注变更总结
适用场景：快速总结当前工作区的所有未提交变更。
查看当前工作区的所有变更（git diff + git diff --cached），
简要总结：哪些文件被修改、每个文件的变更目的是什么。
用表格输出：文件路径 | 变更类型（新增/修改/删除） | 变更目的 | 行数变化。Release Notes 生成
适用场景：根据一段时间内的 commit 历史生成 Release Notes。
查看从 {起始 tag/commit} 到 {结束 tag/commit} 的所有 commit，
生成 Release Notes。
分类汇总：
- 🚀 新功能（feat）
- 🐛 Bug 修复（fix）
- 🔧 改进（refactor, perf）
- 📝 文档（docs）
- 🧪 测试（test）
- 🏗️ 杂项（chore, style, build）
每类下列出对应的变更（从 commit message 中提取关键信息），
每项一行，格式：- {变更描述} ({commit 短 hash})D.8 测试
单元测试生成
适用场景：为函数或组件生成单元测试。
你是一个测试工程师，擅长编写全面的单元测试。
为 {文件路径} 中的 {函数名/组件名} 编写单元测试。
测试框架：{vitest / jest / pytest / 其他}
需要覆盖的场景：
- 正常输入 → 期望输出
- 边界值：{列举边界值，如空数组、null、极大值}
- 错误输入 → 期望行为（抛出异常 / 返回错误）
- 异步场景（如适用）
约束：
- 每个测试用例有清晰的描述（中文）
- 遵循 AAA 模式（Arrange, Act, Assert）
- 测试文件放在 {测试文件路径}
- 不修改被测代码集成测试生成
适用场景：为 API 端点或模块间交互编写集成测试。
为 {API 端点 / 功能模块} 编写集成测试。
测试范围：
- {端点 1}：正常请求 → 期望状态码和响应体
- {端点 1}：异常请求（缺少参数、无效参数）→ 期望错误响应
- {端点 1} + {端点 2} 的联动场景
- 数据库状态验证（如适用）
环境要求：
- 使用 {测试数据库 / mock / 内存数据库}
- 每次测试前重置状态
- 测试之间不共享状态
约束：
- 测试框架：{框架名}
- 测试文件放在 {路径}边界情况测试
适用场景：专注于边界情况和异常路径的测试。
为 {文件路径} 中的 {函数名} 生成边界情况和异常路径的测试。
请系统性地覆盖以下边界：
- 空值：null / undefined / 空字符串 / 空数组 / 空对象
- 极值：最大整数 / 最小整数 / 超长字符串 / 深度嵌套
- 类型边界：类型转换边缘、浮点精度
- 并发边界：同时多次调用（如适用）
- 资源边界：文件不存在、网络超时、权限不足
对每个边界情况：
- 描述场景
- 给出测试代码
- 说明期望行为快捷测试
适用场景：快速生成基本测试。
为 {函数名} 写单元测试。覆盖：正常输入、空值输入、错误输入。使用 {测试框架}。D.9 配置
CLAUDE.md 创建 / 更新
适用场景：为项目创建或更新 CLAUDE.md 项目说明书。
分析当前项目的结构、技术栈和开发约定，生成/更新 CLAUDE.md。
需要包含：
- 项目简介（1-2 句话）
- 常用命令（dev / build / test / deploy）
- 架构概览（目录结构和各目录的职责）
- 编码规范（命名、格式化、导入顺序等）
- 关键约定（如 Git 分支策略、commit 格式）
- 注意事项（容易踩的坑）
约束：
- 使用中文（技术术语可用英文）
- 命令示例确保可运行
- 基于项目的实际内容，不要编造不存在的东西
- 保持简洁，不要超过 {N} 行环境变量配置
适用场景：生成 .env 文件模板或环境变量说明。
为项目生成环境变量配置文档。
请：
1. 搜索项目中所有读取环境变量的地方（如 process.env / import.meta.env）
2. 列出每个变量的：变量名 | 用途 | 是否必填 | 默认值 | 示例值
3. 生成 .env.example 模板文件
只输出确实在代码中被使用的环境变量，不要猜测。项目配置生成
适用场景：生成 ESLint、Prettier、TypeScript 等工具配置。
为项目配置 {工具名，如 ESLint / Prettier / tsconfig}。
当前项目信息：
- 语言：{TypeScript / JavaScript}
- 框架：{React / Vue / Node / 其他}
- 现有配置（如有）：{读取已有配置文件}
请：
1. 先读取项目中可能影响配置的文件（如 package.json、现有配置文件）
2. 生成符合项目需求的 {工具名} 配置
3. 说明关键配置项的含义和选择理由
4. 列出可能需要安装的依赖
约束：
- 不要覆盖已有的规则（如果是更新）
- 遵循社区主流最佳实践快捷配置
适用场景：快速生成简单配置。
为当前项目生成 {工具名} 配置。技术栈：{语言 + 框架}。遵循主流最佳实践。D.10 使用建议
- 模板是起点，不是终点：根据实际情况增删约束、调整格式。模板的价值在于让你不用从零构思框架。
- 先模板，后渐进：用模板快速完成第一轮沟通，如果结果偏离预期，用渐进式细化技巧修正（见第 28 章 28.3 节）。
- 积累自己的变体：每次使用模板后，如果发现某个变体更适合你的项目，保存下来作为个人模板。
- 善用四要素：每个模板本质上都是 RCCF 四要素（角色、上下文、约束、输出格式）的实例化。理解了四个要素，你就能灵活改造任何模板。
- 保存到 CLAUDE.md：将你最常用的模板存入项目的 CLAUDE.md，这样 Claude Code 每次启动时就能自动加载，省去重复输入的功夫。