AI 编程常用 Prompt 模板：读项目 / 修 bug / 加功能 / 重构

guohuang

310人浏览 · 2026-05-22 07:30:00

guohuang · 2026-05-22 07:30:00 发布

AI 编程常用 Prompt 模板：读项目 / 修 bug / 加功能 / 重构

第 3 篇 · 4 个 Prompt 模板合集

1. 一个普通的早上

上周一早上，我给 Claude Code 提了 4 次需求：让它读懂一段隔了两周没碰的模块代码、修一个偶发的 JSON 解析 bug、给一张用户表加联系方式字段、重构一个写到几百行的拼接函数。

4 次需求，4 个 Prompt，全是临场打字。质量参差不齐——第二个没写约束，AI 顺手重构了一堆无关代码；第三个忘了说 migration 要单独提交，改动塞进了同一个 commit。

那天傍晚我才意识到：我每天用 AI 处理的需求其实就那几类，但我每次都在从零打字——想结构、写约束、列验收。

2. 写代码会抽象，写 Prompt 却不会

写代码的时候，同样的逻辑出现第二次，我们就有"该抽个函数了"的冲动。

但写 Prompt，几乎从来没这个习惯。Prompt 像一次性消耗品——用完就丢，下次同样任务再从零打。质量全靠当时状态：精神好的时候三要素齐全，累的时候只剩一句"帮我加个字段"，然后 AI 给你 5 分钟省下的代码，你花 20 分钟回滚。

真正的转变是把 Prompt 当成可复用的代码资产：同一类任务用同一个骨架，每次只填变量。

我后来梳理过，我日常用 AI 协作的任务其实只有 4 类：读项目、修 bug、加功能、重构。这 4 类覆盖了我 80% 以上的 AI 协作场景。把这 4 类各沉淀一个模板，就够用了。

3. 4 个模板的共同骨架

贴模板之前先说 3 个共同设计原则——4 个模板都是这 3 个钉子的具体化。

原则 1：方案先行。 4 个模板的第一步都不是动手——是让 AI 先输出方案：读项目先出结构、修 bug 先出根因、加功能先列文件、重构先列问题。反例：直接说"把 X 改成 Y"，错了你都不知道为什么。

原则 2：验收明确。 沿用第 1 篇的"验收"概念——必须可机械判断。模板里把通用验收预填好（“测试通过 / migration 单独提交”），不用每次临场想。

原则 3：改动可逆。 默认"分步提交 + diff 可审"，不让 AI 一次性改 10 个文件。反例：让 AI"一口气做完"——回滚成本指数级上升。

照模板用，原则自动跟上。先打个预防针：模板是脚手架，不是答案——具体项目要微调，不要照搬。

4. 4 个模板拆解

模板 A：读项目

使用场景：第一次接手一个仓库 / 时隔半个月回来 / 接手别人写了一半的模块。让 AI 给你一份"3 分钟版本"的项目认知。

模板原文：

目标：帮我快速理解 [项目/模块名] 的结构和关键逻辑。

请按以下顺序输出：
1. 项目的核心目的（1-2 句）
2. 目录结构和每个目录的职责（不超过 10 行）
3. 数据流：从用户请求到响应的完整路径
4. 关键数据模型（最多 5 个）+ 它们之间的关系
5. 当前你看到的潜在风险或不清晰的地方（不超过 3 条）

约束：
- 只读不改任何文件
- 不猜测，看不懂的地方直接说"不清楚"
- 不输出你的优化建议（这一步只做理解）

验收：
- 我读完你的输出，能在 3 分钟内向同事讲清这个项目在干什么

真实使用案例：前阵子我重启 ScoreMe billing 模块——隔了 10 天没碰，UserQuota 和 ManualOrder 的关系我已经忘了。我没硬看代码，先丢这个模板给 Claude Code。

AI 给我列了：数据流（用户调评分 → billing 检查 quota → 不足返回 402 → 管理员手动加 paid_count）、关键模型（UserQuota / ManualOrder）。最后第 5 条风险列了一句：“last_reset_date 的过零点重置目前是被动触发，没主动 cron。”

这条"没主动 cron"是我真没注意到的——这个 bug 我记下来，恰好成了下面模板 B 的例子。

常见踩坑：

不加"只读不改"会出事：AI 会顺手"优化"代码，文件被改了你都不知道。
不要让 AI 边读边给建议：理解会被"我觉得应该这样"污染。理解和建议必须分两步。

模板 B：修 bug

使用场景：复现了一个 bug，想让 AI 帮你定位 + 修。注意是"定位 + 修"，不是"直接修"——这个区分是核心。

模板原文：

目标：定位并修复以下 bug。

bug 描述：[完整复现路径 + 期望行为 + 实际行为]
报错信息 / 日志：[贴原始错误，不要总结]

请按以下顺序回答：
1. 这个 bug 的根因在哪一行 / 哪个函数？（先定位，不要先修）
2. 至少给出 2 个可能的 fix 方案，标注每个方案的副作用
3. 等我选定方案后，再给出最小改动的 diff

约束：
- 不修改未涉及的代码（不顺手重构）
- 不引入新依赖
- 单元测试 / 现有测试必须仍能通过

验收：
- 给出 diff 前，必须先获得我对方案的确认
- diff 范围只覆盖这个 bug 相关的文件

真实使用案例：接着上面那个例子。free_count_today 的过零点重置只在用户当天首次访问时被动触发，没有定时任务。我把它填进模板。

AI 先回 2 个根因假设：(1) 当初只设计了 lazy reset；(2) last_reset_date 语义是"上次被动重置时间"，不是"主动重置时间"。

然后给 3 个 fix 方案：A management command + crontab；B Celery beat（要 Redis）；C 保留 lazy 但把逻辑写得更显式。B 要新依赖、违反约束直接 pass；C 最快但字段语义别扭。

我选 A。AI 才给 diff，只动了 billing 里两个文件 + 一个 management command。

常见踩坑：

不让 AI 先定位会被反噬：bug 过两周换个形式再回来，你不知道之前修了啥。
不显式说"先给方案、等确认再 diff"，AI 会一步到底：方案讨论环节就没了。

模板 C：加功能

使用场景：在现有代码里加一个新功能 / 新字段 / 新接口。重点是"不打扰现有逻辑"。

模板原文：

目标：在 [模块/文件] 中新增 [功能描述]。

需求细节：
- 输入：[什么形式的输入]
- 输出：[期望的输出]
- 业务规则：[关键规则 1-3 条]

请按以下顺序产出：
1. 现有代码里哪些地方需要改动？（列文件 + 行数范围）
2. 改动方案：新增文件还是改现有文件？为什么？
3. 等我确认方案后，再给出代码

约束：
- 不修改与本功能无关的代码
- 不改公开 API 的签名（除非显式要求）
- 数据模型变更必须配 migration，且 migration 单独提交
- 不引入新依赖

验收：
- 给出代码前先得到方案确认
- 代码 + 测试 + migration（如有）分文件给出，方便我分 commit

真实使用案例：还是同一个项目。Visitor 表只有 visitor_id 和 ip/ua，没联系方式——我决定加一个 contact 字段，给用户留入口加微信。

模板填了：目标加字段、输入微信号或手机号、规则非必填。

AI 第一步列了要改的文件：models.py、serializers.py、views.py、admin.py。因为模板里有"数据模型变更必须配 migration"这条，AI 顺势问了 backfill 策略——我说不需要，默认空字符串。

方案过了我才放行——它给了 4 个文件 diff + 1 个 migration，建议"分 2 个 commit：先 migration，再业务代码"——帮我省了一次潜在的 review 噩梦。

常见踩坑：

不写"先列文件、等确认"，AI 会偷偷塞改动：默认 AI "顺手"动它觉得该重构的地方。
不显式说"migration 单独提交"，AI 会塞一个 commit：早期翻过的坑——回滚业务代码就把 migration 也回滚了。

模板 D：重构

使用场景：现有代码逻辑没坏，但读起来乱 / 难扩展 / 重复多。想让 AI 帮你重构，保证行为完全等价。

模板原文：

目标：重构 [文件/函数名]，目标是 [可读性 / 可扩展性 / 去重 / 性能]，行为必须完全等价。

请按以下顺序产出：
1. 先指出当前代码的 3 个最大问题
2. 给出重构方案：拆成几个函数 / 引入什么抽象 / 删除什么重复
3. 等我确认方案后，再给出 diff

约束：
- 对外接口 / 函数签名 / 返回值结构必须完全不变
- 不引入新依赖
- 不改测试（如果改了说明行为变了，必须停下来跟我确认）
- 一次只重构一个文件 / 一个函数

验收：
- 重构前后的现有测试全部通过
- diff 给出后，我能在 5 分钟内看完并理解每个改动
- 如果改动超过 100 行，主动拆成 2 次 PR

真实使用案例：copyright_agent 是我之前做的一个软著文档生成工具——把代码片段、模块说明、用户输入塞进模板，输出 60 页符合规范的文档。

早期那段拼接逻辑边写边加——加一个章节就多一个 if。3 个月后函数 280 行、14 个 if，可读性归零。

模板填上扔给 Claude，约束"对外接口不变、测试不改"。

AI 列了 3 个最大问题：章节顺序硬编码、拼接和格式化混在一起、占位符散落各处。给方案：抽出 SectionBuilder 类、拼接和格式化分两步、占位符走统一 render。

方案我没改动，让它直接做。diff 出来，280 行变成 3 个文件共 190 行。跑了 3 个软著样本，输出 diff 为空——行为完全等价。

常见踩坑：

不写"对外接口不变"会被静默改签名：AI 容易"顺手"把参数从 list 改成 set——调用方全炸。
不写"测试改了必须停下来"，AI 会自己调测试：测试改到通过为止，等于丢了行为等价的兜底。

5. 4 个模板的速查卡

把 4 个模板做成了一份在线速查卡，托管在 GitHub Gist：[Gist 链接 — 发布前补]

用法有 3 种，按你的工具栈挑：

复制粘贴到对话框：Claude / ChatGPT / Cursor / 通义灵码都吃，零成本上手
存成编辑器的斜杠命令：Cursor 写进 Rules、Claude Code 放进 .claude/commands/、Copilot 建 prompt 文件，下次直接打斜杠
塞进项目级协作规则文件：Cursor 的 .cursorrules、Claude Code 的 CLAUDE.md，让 AI 在这个项目里自动按结构工作

我自己用的时候会持续打磨，更新同步到 Gist。如果你跑出了新版本，欢迎在评论里贴——后面可能整理一个"社区版"。