AI 写代码不缺速度，缺的是「写对」。常见翻车：让 AI「写个解析函数」，它塞给你一个不存在的 API；让它「重构一下」，它重写整段还改了行为；让它「设计个模块」，它画了个空架子没法落地。问题不在模型能力，在 prompt 没把约束说死。
站内已有《代码审查与 Debug Prompt 包》，专治「代码写完了要查问题」——bug 定位、提交前 review、审查时顺带给重构方向。本篇是它的姊妹篇，管代码「还没写、或写完了要动刀」的四个场景：按需求生成函数、重构与优化、系统设计脚手架、速读陌生代码。两者不重叠：那篇是审查与调试，本篇是生成与改造。那篇的重构是「review 时挑出可维护性问题、给方向」；本篇的重构是「拿能跑的代码，逼出坏味道、复杂度和性能问题，产出有依赖顺序、保行为的执行方案」，偏动手而非诊断。
四个 Prompt 分三级递进，外加一个速查 cheatsheet。每个都带角色、任务、约束、输出格式，变量用 {{}} 标注，复制改用即可。
一、入门级：按需求生成函数
写代码最贵的错误是「需求还没对齐就开写」。AI 默认会把一个模糊需求直接 dump 成完整实现，顺手替你决定了参数类型、错误处理方式、返回结构——等你发现不对，已经要推倒重来。这步的核心是「先要签名再要实现」，把一次性的代码生成变成两段式对话：先对齐契约，再写实现。
你是资深 {{语言}} 工程师。请按以下需求实现一个函数，分两步输出，不要一步写完。
需求：{{需求描述 + 语言}}
第一步——函数签名与契约（只写这些，等我确认后再实现）
- 函数名、参数（含类型）、返回值类型
- 列出每个输入的合法范围与边界值（空值 / 空串 / 0 / 负数 / 超长 / 超大）
- 列出所有需要处理的异常或错误情况，标明是抛异常还是返回错误码
- 不要写实现逻辑
第二步——实现（在我确认签名后给出）
- 按确认的签名实现，包含全部边界处理
- 只使用 {{语言}} 标准库或我明确点名的第三方库，不要臆造任何不存在的 API；若不确定某个 API 是否存在，标注「待确认」
- 不写空泛注释（如「这里是处理逻辑」「// 循环处理」），只在非显而易见处解释 why
- 末尾附 3 个调用示例：1 个正常输入、1 个边界输入、1 个异常输入，写出预期返回值
约束：需求有歧义时先列歧义点问我，不要自行假设；代码必须可直接运行，不留 TODO 占位。要点：两段式是这个 Prompt 的灵魂。最常踩的坑是——让 AI 一步出实现，它默认把「找不到记录」处理成返回 null，但调用方期望抛异常。先锁签名和错误约定再写实现，这种返工就消掉了。「3 个调用示例」也关键：AI 嘴上说处理了边界，逼它写出边界输入的预期返回，才发现其实没处理。
二、进阶级：重构与优化
代码能跑，但慢、但绕、但难维护。直接让 AI「帮我重构」是最危险的指令——它会重写一通，悄悄改了行为（错误处理变了、边界差一位、副作用没了），上线才爆。这步把重构拆成「诊断 → 方案 → 关键片段」三段，且强制「保留行为 + 标依赖顺序 + 不确定的标待确认」。
你是重构专家。请分析以下代码，识别问题并给出可执行的重构方案。
代码：
{{代码}}
按以下结构输出：
1. 问题诊断（按严重度从高到低排序）
- 坏味道：长函数 / 重复代码 / 过深嵌套 / 巨大类 / 发散式变化等，每条指出具体行号或片段
- 复杂度：圈复杂度过高的函数，给出粗略估算值和超标理由
- 性能：N+1 查询、不必要的重复计算、可降阶的循环（如 O(n²) → O(n)）、同步阻塞可改异步的点
2. 重构方案
- 每个问题对应一个独立重构动作（提取函数 / 内联 / 引入参数对象 / 拆分条件表达式 / 替换算法等）
- 每个动作写：改什么、为什么、预期收益（可读性 / 性能 / 可测性的具体提升）
- 标注动作之间的依赖顺序（哪些必须先做，否则后续动作无法进行）
3. 重构后关键片段
- 只展示改动部分，用注释标出前后差异（如 `// 旧：... 新：...`）
- 公共接口签名保持不变；若有必要变更，单独列出并说明理由
约束：不重写未涉及的部分；不确定是否为问题的点标「待确认」，不要直接改；重构后行为必须与原代码等价，附 2-3 条验证思路（如「原 [空输入] 返回 X，重构后应同返回 X」）。要点：和审查向重构不同，这个 Prompt 要的是「能照着一步步提交的执行方案」，所以「依赖顺序」和「行为等价验证」是硬约束。AI 最爱犯的错是「自信地改了它不该改的」——比如把「找不到返回 -1」悄悄改成「抛 ValueError」——所以「待确认」标记比直接改更安全。性能那一栏是和审查包的差异化重点：审查包盯可维护性，这里额外逼出复杂度数字和性能降阶机会。
三、专家级：系统设计与多文件脚手架
单个函数好写，一个模块难搭。AI 设计模块的通病是「过度分层」——不管需求大小，先给你来一套 repository / service / factory / facade / DTO，当前用不到的层也照堆。这步强制「最小化目录结构」和「接口具体到类型」，产出一个能直接照着建文件的脚手架。
你是系统架构师。请根据以下模块需求，产出可直接落地的脚手架设计。
模块需求：
{{模块需求}}
请输出：
1. 目录结构
- 用树状列出文件与目录，每个文件后用一句话标注职责
- 分清入口 / 核心逻辑 / 数据层 / 工具层 / 测试 五类
- 只建当前需求真正用到的层；用不到的层不要预建，并在末尾说明「为什么不建 X 层」
2. 接口定义
- 列出模块对外暴露的接口（函数 / 类 / API 端点）
- 每个接口写：签名、入参类型、返回类型、可能抛出的错误
- 类型必须具体，不写「相关数据」「配置对象」这种模糊词，用具体结构或类型名
3. 关键实现要点
- 选 2-3 个最核心的函数，给出实现骨架（目标语言片段或结构化伪代码）
- 每个选型决策用一句话说明理由（为什么用 X 不用 Y）
4. 测试策略
- 单元测试：列出核心函数的用例清单，每个函数至少 1 正向 + 2 反向（错误输入 / 边界）
- 集成测试：列出模块间交互的验证点
- 标注哪些测试应优先实现（先写哪些能最快锁死行为）
约束：目录结构最小化，不引入需求未提及的抽象层；接口定义必须具体到类型；不臆造第三方库 API，用到第三方时写出库名和版本范围。要点：「为什么不建 X 层」是我加的刹车。AI 给脚手架默认全须全尾，逼它解释「为什么这里不需要 repository 层」，它才承认当前规模用不上。接口「具体到类型」同理——AI 爱写 config: object 这种废类型，逼成 config: { retries: number; timeout: number }，照着就能建文件。「先写哪些测试能锁死行为」把测试策略从清单变成有优先级的执行计划。
四、速查：5 分钟读懂陌生代码
不是所有场景都要写新代码。接手老项目、读开源源码、review 别人 PR，核心诉求是「快速搞懂这段在干嘛」。直接让 AI「解释这段代码」会得到逐行翻译，废话一堆没干货。这个 cheatsheet 逼它输出结构化的「功能 → 入口 → 数据流 → 难点 → 副作用」五段式，每段不超过 3 行。
你是技术导师。请帮我在 5 分钟内读懂以下陌生代码的核心逻辑。
代码：
{{代码}}
按以下结构输出，每节不超过 3 行：
1. 这段代码做什么：一句话概括整体功能，不提实现细节
2. 入口在哪：标出执行起点或主函数（行号或函数名）
3. 数据怎么流：输入 → 关键变换 → 输出，用箭头串起主干，跳过枝节
4. 最绕的部分：指出 1-2 处最难懂的地方，用大白话解释，不复制代码
5. 依赖与副作用：依赖哪些外部状态 / 模块 / 全局变量，修改了哪些外部状态
约束：不逐行翻译代码；不评判代码好坏，只讲「它在干嘛」；看不懂的部分如实写「需要更多上下文」，不要硬编解释。要点：「数据怎么流」是读懂代码最快的抓手——比逐行读快十倍。AI 默认逐行翻译（「第 10 行声明 x，第 11 行判断 x」），等于没说。「如实写需要更多上下文」是关键刹车：AI 会对追不上的代码硬编合理解释，逼它承认看不懂，你才知道哪里要自己查。这 Prompt 我日常用来读 npm 依赖源码，五分钟决定「能不能用」。
四条通用约束
上面四个 Prompt 共享四条硬约束，是「AI 写的代码能不能用」的底线：
- 可运行 + 边界处理：产出的代码必须能直接跑，不留
// TODO占位；边界（空值、空数组、超大输入、并发）必须显式处理，不能只在注释里写「假设输入合法」。 - 不臆造 API：AI 编码翻车的头号原因。它会自信写出
lodash.deepMerge()、axios.retry()这种看似合理但根本不存在的调用。只许用标准库或点名库，拿不准的标「待确认」。 - 区分 AI 草稿与人审：每个 Prompt 产出都是草稿，不是成品。无论模型多强，代码进生产前必须经人工审查与测试。Prompt 要求附「验证思路」和「调用示例」是给人审抓手，不是让 AI 自证清白。
- 去 AI 味：禁空泛注释（「这里是处理逻辑」），要具体到 why；禁废话（「众所周知」）；用具体类型名替代「object」「相关数据」。AI 味重的代码看着整齐，实则没传递信息。
怎么用
四个 Prompt 不是线性跑完，是按场景取用：
- 写新函数：用入门级。先出签名和契约，你确认边界和错误约定，再让它写实现。
- 改老代码：用进阶级。先跑诊断，按依赖顺序逐个动作提交，每提交跑一次行为等价验证。
- 搭新模块：用专家级。先出目录和接口，照着建文件骨架，再逐个填实现。
- 读陌生代码：用速查 cheatsheet。五分钟出主干，决定要不要深读。
模型选择上，入门级生成函数主流模型都能胜任，DeepSeek 性价比高、适合批量生成；进阶级重构和专家级系统设计偏推理，Claude Opus / GPT-5 / Codex 这类编码向模型更稳，Claude 长上下文还适合把整模块代码一次喂进去做重构；速查 cheatsheet 要求不高，Claude 和 DeepSeek 都行。一句话：日常生成选 DeepSeek，动刀和设计选 Claude / GPT-5。
踩坑
- 一步到位要完整实现：让 AI 一次出完整函数，它会替你锁死参数类型和错误处理方式，发现不对就推倒重来。解法：入门级 Prompt 强制两段式，先签名后实现。
- AI 臆造 API：它写
someLib.doTheThing()一脸自信，实际这方法不存在。解法：只许标准库或点名库，不确定的标「待确认」，你跑一遍才知道。 - 重构悄悄改行为：AI 重构时把「返回 -1」改成「抛异常」，把「同步」改成「异步」，行为就变了。解法：强制「行为等价 + 附验证思路」，每个动作独立提交后跑测试。
- 脚手架过度分层：AI 给你堆 repository / service / factory 一整套，当前需求只用得上两层。解法：强制「最小化目录」+「解释为什么不建 X 层」。
- 让 AI 硬编看不懂的代码：追不上的代码它也编个解释，你信了就踩坑。解法：速查 Prompt 里逼它「看不懂如实说需要更多上下文」。
参考来源
- Anthropic《Prompt engineering》：docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/overview
- OpenAI《Prompt engineering guide》：platform.openai.com/docs/guides/prompt-engineering
- Martin Fowler《Refactoring catalog》：refactoring.com/catalog/
- Martin Fowler《Clean Code / Refactoring 坏味道》：https://martinfowler.com/bliki/CodeSmell.html