如何给 AI 一个高质量的新功能开发 Prompt：用 Superpower Skill 驱动完整开发流程

文章目录

[如何给 AI 一个高质量的新功能开发 Prompt：用 Superpower Skill 驱动完整开发流程](#如何给 AI 一个高质量的新功能开发 Prompt：用 Superpower Skill 驱动完整开发流程)
- [一、核心思路：Prompt 只是入口，流程才是关键](#一、核心思路：Prompt 只是入口，流程才是关键)
- 二、适用场景
- 三、为什么要区分"目标模块"和"参考模块"
- [四、通用新功能开发 Prompt 模板](#四、通用新功能开发 Prompt 模板)
- 五、占位符怎么填
- - [1. 已知道接口或 method](#1. 已知道接口或 method)
  - [2. 只知道文档章节](#2. 只知道文档章节)
  - [3. 只知道业务目标](#3. 只知道业务目标)
  - [4. 暂时不确定](#4. 暂时不确定)
- 六、一个通用填写示例
- [七、这个 Prompt 背后的几个关键原则](#七、这个 Prompt 背后的几个关键原则)
- - [1. 先恢复上下文，再谈实现](#1. 先恢复上下文，再谈实现)
  - [2. 搜索关键词要少而准](#2. 搜索关键词要少而准)
  - [3. 参考模块不是依赖模块](#3. 参考模块不是依赖模块)
  - [4. 第一阶段输出必须结构化](#4. 第一阶段输出必须结构化)
  - [5. 实现前必须有人确认](#5. 实现前必须有人确认)
- 八、推荐的完整工作流
- 九、可以直接复用的检查清单
- 十、总结

在复杂代码库里让 AI 接手新功能，最怕的不是 AI 不会写代码，而是它太快开始写代码。

很多团队第一次用 AI 做开发时，会把需求直接丢给它：

帮我实现某某功能。

结果常见问题是：

AI 没搞清楚当前分支和未提交改动，就开始改文件。
AI 搜了太多无关关键词，把上下文带偏。
AI 把"参考模块"误解成"可以直接调用的依赖模块"。
AI 没读设计文档、接口文档、历史实现，直接造了一套新风格。
AI 改完了，但团队很难判断它是否真的理解业务边界。

更稳的方式是：不要只写一个"让 AI 编码"的 Prompt，而是把 AI 纳入一套完整的新功能开发流程。

本文整理一套通用模板，适合协议适配、老系统新增模块、复杂业务链路接入、第三方 API 对接等场景。任何团队都可以把路径、模块名和业务说明替换成自己的项目。

一、核心思路：Prompt 只是入口，流程才是关键

推荐采用"Superpower Skill + 混合型接手 Prompt"的方式。

这里的 Superpower Skill 指的是一组固定开发技能或工作流约束，例如：

brainstorming：先澄清需求、理解边界、提出方案，禁止一上来写代码。
writing-plans：在需求确认后生成可执行的开发计划。
executing-plans：按计划分步骤实现。
test-driven-development：高风险逻辑先想测试，再写实现。
verification-before-completion：完成前必须跑验证命令，用证据确认结果。

整个流程可以拆成四段：

上下文恢复：读仓库状态、设计文档、接口文档、历史实现。
需求与边界澄清：确认目标能力、模块边界、依赖关系、不能做什么。
Spec 与计划：输出设计说明、实现路径、风险问题，用户确认后生成计划。
实现与验证：按计划改代码、补测试、跑验证，最后总结结果。

也就是说，Prompt 不应该只告诉 AI"做什么"，还要告诉 AI"按什么流程做""什么时候不能做""做到什么程度才能继续"。

二、适用场景

这套 Prompt 尤其适合下面几类任务：

新模块适配第三方 API 或协议。
在旧系统旁边新增一套相似能力，但不能直接依赖旧模块。
需要参考历史实现的调用方式、DTO、状态机、错误码、生命周期。
多个文档、多个仓库、多个模块共同决定实现方案。
新开 AI session，需要快速恢复之前讨论过的上下文。

不适合的场景也很明确：

一行配置修改。
已经有明确 diff，只需要机械替换。
完全独立的小脚本，没有复杂上下文。

三、为什么要区分"目标模块"和"参考模块"

在真实项目里，经常会遇到这样的情况：

A 模块是本次要开发的模块。
B 模块是历史业务模块，里面有成熟实现。
A 模块不能调用 B 模块，但可以参考 B 模块如何调用内部服务、如何组织 DTO、如何处理错误码。

如果 Prompt 只写"参考 B 模块"，AI 很容易误解成：

那我直接在 A 里调用 B 的 service 或接口吧。

这通常是错的。

更安全的表述应该是：

B 模块只作为实现方式参考。A 模块禁止直接调用、依赖或反向耦合 B 模块。请参考 B 模块的调用链路、DTO 组织、状态生命周期和错误语义，在 A 模块内重新实现。

这句话非常重要。它能避免 AI 把模块边界写坏。

四、通用新功能开发 Prompt 模板

下面是一份可以直接复制的通用模板。

把尖括号里的内容替换成自己的项目内容即可。

text 复制代码

你现在接手一个复杂代码库中的新功能开发任务。

任务模式是"混合型"：

第一阶段：只恢复上下文、阅读资料、总结现状、提出问题和方案。
第二阶段：只有当我明确说"开始实现""继续开发"或"按方案改代码"后，才允许修改代码、补测试、运行验证命令。

请优先使用 Superpower Skill 驱动整个开发流程：

1. 使用 brainstorming 思路先澄清需求、边界、风险和方案，不要直接实现。
2. 第一阶段输出接手总结和建议方案，等待我确认。
3. 需求和方案确认后，再进入 spec / plan 阶段，生成可执行开发计划。
4. 实现阶段按计划小步修改，并在完成前运行必要验证。

项目路径：
<项目根路径>

目标模块：
<本次要开发的模块路径或模块名>

设计讨论文档目录：
<设计文档目录，没有则写"无">

外部 API / 协议文档：
<第三方 API、协议文档、产品文档或接口说明地址>

官方 Demo / 示例项目：
<官方 Demo 或示例代码路径，没有则写"无">

参考业务 API 文档：
<历史业务 API 文档目录，没有则写"无">

参考源码模块：
<历史实现模块路径，没有则写"无">

开发分支：
<开发分支名>

本次功能类型：
<例如：指令控制 / 状态上报 / 属性设置 / 文件上传 / 消息推送 / 第三方协议适配 / 其他>

本次目标能力：
<本次要开发或分析的能力。可以是 method、接口名、文档章节名、业务动作，或者"待 AI 根据文档判断">

补充说明：
<额外边界、限制、偏好或不确定点，没有则写"无">

模块边界声明：

1. 目标模块是本次唯一允许实现新逻辑的主要模块。
2. 参考源码模块只用于理解历史业务如何调用内部模块、如何组织 DTO、如何处理生命周期和错误语义。
3. 目标模块禁止直接调用、依赖或反向耦合参考源码模块。
4. 如果需要参考历史实现，请在目标模块内重新实现适配逻辑。
5. 如果发现目标模块必须和参考模块交互才能完成任务，先停止并提出风险，不要擅自实现。

请先完成第一阶段上下文恢复：

1. 确认当前目录是否为项目根路径。
2. 检查当前 git 分支是否为指定开发分支。
3. 查看工作区状态，识别已有未提交改动。不要回滚用户或其他 session 的改动。
4. 阅读设计讨论文档。
5. 阅读外部 API / 协议文档。
6. 阅读目标模块中已有同类实现。
7. 阅读参考业务 API 文档和参考源码模块，理解历史实现方式。注意：参考模块不能作为依赖或调用目标。
8. 判断本次目标能力的数据方向、同步/异步语义、生命周期、缓存、超时、回调、错误码和状态影响。
9. 判断外部 API 字段与目标模块内部实现模型之间的映射关系。
10. 不要修改代码。先输出接手总结。

搜索策略：

不要一次性搜索所有关键词。先根据本次功能类型选择最小关键词组。

推荐方式：

- 已知 method / 接口名：先搜精确 method / 接口名。
- 只知道文档章节：先搜章节关键词，再根据命中的 DTO、handler、service 继续追踪。
- 只知道业务动作：先读 API 文档，再按业务动作名、Controller、Service、DTO、Enum 逐层定位。
- 参考模块：只追同类业务链路，不泛搜全仓库。
- 上下文不足时，再扩大关键词范围。

第一阶段输出格式：

## 接手总结

### 当前仓库状态

- 当前目录：
- 当前分支：
- 工作区状态：
- 相关最近提交：

### 已读资料

- 设计文档：
- 外部 API / 协议文档：
- 官方 Demo / 示例代码：
- 参考业务 API 文档：
- 目标模块关键代码：
- 参考源码模块关键代码：

### 目标模块现有相似能力链路

用简短步骤说明目标模块中已有相似能力的数据流。

### 参考模块同类能力链路

用简短步骤说明参考模块中同类能力如何调用内部模块。

注意：这里是参考链路，不代表目标模块可以调用参考模块。

### 本次能力到目标模块独立实现的参考映射

- 外部 API method / topic / endpoint：
- 外部 API 入参字段：
- 可参考的历史 API / service：
- 可参考的 DTO / enum / 状态模型：
- 目标模块内拟重新实现的 service / DTO / 状态模型：
- 字段转换：
- 错误码 / 返回值映射：
- 不能直接映射的差异：

### 本次目标能力初步归类

- 功能类型：
- 协议入口 / API 入口：
- 数据方向：
- 同步 / 异步：
- 是否需要 reply / response：
- 是否需要生命周期：
- 是否需要缓存：
- 是否需要超时补偿：
- 是否影响状态：
- 推荐参考的已有代码模式：

### 疑问和风险

列出需要我确认的问题。问题要少而关键。

### 建议下一步

给出 2-3 个实现路径，并推荐其中一个。

在我确认之前，不要修改文件，不要生成实现代码，不要提交。

开发约束：

- 优先沿用目标模块已有架构、命名、分层、DTO、mapper、enum、状态管理和错误处理风格。
- 参考模块只能作为实现方式参考，不能作为依赖或调用目标。
- 不要把某一个功能模块的设计机械套用到另一个模块；只能复用相同协议形态或数据流形态的模式。
- 不要改动无关模块。
- 不要回滚、覆盖或清理其他 session / 用户留下的未提交改动。
- 修改文件时注意编码和换行风格，不要引入项目不接受的格式变化。
- 实现前先给出简短设计和计划，等我确认后再改代码。

五、占位符怎么填

很多人第一次写这种 Prompt，会卡在"本次目标能力"上。

其实它不一定要非常精确。你可以按自己当前掌握的信息来填。

1. 已知道接口或 method

text 复制代码

本次目标能力：
实现 xxx_start、xxx_stop 两个 method 的协议适配

2. 只知道文档章节

text 复制代码

本次目标能力：
梳理第三方文档中"设备远程控制"章节的功能边界，判断需要在目标模块中适配哪些能力

3. 只知道业务目标

text 复制代码

本次目标能力：
实现第三方平台下发控制指令后，本系统能够按现有设备控制链路完成动作并返回结果

4. 暂时不确定

text 复制代码

本次目标能力：
待 AI 根据外部 API 文档、设计文档和现有代码归类

补充说明：
我暂时不确定具体接口和内部实现链路，请先判断功能边界与参考映射关系，不要直接实现。

六、一个通用填写示例

下面用"第三方设备控制协议适配"为例。

text 复制代码

你现在接手一个复杂代码库中的新功能开发任务。

任务模式是"混合型"：

第一阶段：只恢复上下文、阅读资料、总结现状、提出问题和方案。
第二阶段：只有当我明确说"开始实现""继续开发"或"按方案改代码"后，才允许修改代码、补测试、运行验证命令。

请优先使用 Superpower Skill 驱动整个开发流程：

1. 使用 brainstorming 思路先澄清需求、边界、风险和方案，不要直接实现。
2. 第一阶段输出接手总结和建议方案，等待我确认。
3. 需求和方案确认后，再进入 spec / plan 阶段，生成可执行开发计划。
4. 实现阶段按计划小步修改，并在完成前运行必要验证。

项目路径：
D:\workspace\example\device-platform

目标模块：
third-party-device-adapter

设计讨论文档目录：
D:\workspace\example\device-platform\docs\adapter-design

外部 API / 协议文档：
https://example.com/docs/device-control-api

官方 Demo / 示例项目：
D:\workspace\example\official-demo

参考业务 API 文档：
D:\workspace\example\device-platform\api-docs\v1

参考源码模块：
D:\workspace\example\device-platform\device-api

开发分支：
feature/third-party-control-adapter

本次功能类型：
第三方协议适配中的设备控制

本次目标能力：
梳理第三方文档中"设备控制"章节的功能边界，对照参考业务 API 文档和 device-api 实现，判断第三方控制能力应参照原业务哪条调用内部模块的链路，并设计 adapter 内需要重新实现的 service、DTO、状态模型和后续实现批次。

补充说明：
我暂时不确定具体 method，也不确定应参照原业务侧哪条实现链路。请先根据第三方文档、参考业务 API 文档和 device-api 实现判断功能边界与参考映射关系，不要直接实现。注意：adapter 与 device-api 禁止任何直接交互，device-api 只能作为实现方式参考。

七、这个 Prompt 背后的几个关键原则

1. 先恢复上下文，再谈实现

复杂项目里的"正确代码"不是凭空写出来的。

AI 至少要先知道：

当前在哪个分支。
工作区有没有别人留下的改动。
目标模块已有代码风格是什么。
设计文档里已经讨论过什么。
参考模块里哪些只是参考，哪些可以真正依赖。

这一步看似慢，其实能减少大量返工。

2. 搜索关键词要少而准

不要让 AI 一上来全仓库搜索几十个关键词。

更好的方式是：

先按功能类型选最小关键词。
找到入口文件。
顺着 DTO、handler、service、enum、mapper 往下追。
上下文不足时再扩大范围。

搜索越克制，越不容易被无关上下文污染。

3. 参考模块不是依赖模块

这是最容易踩坑的点。

如果本次是新模块开发，而旧模块只能作为参考，一定要写清楚：

text 复制代码

参考模块只用于理解历史实现方式。目标模块禁止直接调用、依赖或反向耦合参考模块。

最好再列出禁止项：

禁止新增 Java / Maven / Gradle 依赖。
禁止跨模块 service 注入。
禁止 Feign / HTTP 反向调用参考模块。
禁止共享内部 DTO 形成强耦合。
禁止为了省事把旧模块代码路径串进新模块。

4. 第一阶段输出必须结构化

不要只让 AI 回答"我看完了"。

应该要求它输出：

仓库状态。
已读资料。
关键代码入口。
目标模块数据流。
参考模块数据流。
外部 API 到目标模块实现的参考映射。
疑问和风险。
下一步方案。

这样你才能判断 AI 是真的理解了，还是只是读了一堆文件。

5. 实现前必须有人确认

新功能开发里，很多错误不是语法错误，而是方向错误。

所以第一阶段之后，AI 只能给方案，不能动代码。

等人确认后，再进入 spec、plan、implementation、verification。

八、推荐的完整工作流

可以把团队使用 AI 开发新功能的流程固定成这样：

text 复制代码

1. 新 session 粘贴接手 Prompt
2. AI 使用 brainstorming 思路恢复上下文并输出接手总结
3. 人确认问题、边界和推荐方案
4. AI 生成 spec 或设计说明
5. 人审核 spec
6. AI 生成 implementation plan
7. 人确认计划
8. AI 按计划实现
9. AI 运行测试和验证命令
10. AI 输出变更总结、验证结果、遗留风险

这套流程的重点不是"让 AI 慢一点"，而是让 AI 在正确的轨道上快起来。

九、可以直接复用的检查清单

新功能开发第一阶段，建议要求 AI 至少完成下面这些检查：

十、总结

一个高质量的新功能开发 Prompt，不应该只是"请帮我实现某功能"。

它至少要包含：

项目和分支信息。
目标模块和参考模块。
文档入口和代码入口。
模块边界声明。
搜索策略。
第一阶段禁止改代码。
结构化接手总结。
spec / plan / implementation / verification 的完整流程。

当团队把这些内容固定下来后，新开 AI session 的成本会低很多。AI 不再像一个刚入职就直接改代码的新人，而是像一个先读文档、先问边界、先写方案、再动手的工程协作者。

真正提升效率的，不是一个神奇 Prompt，而是一套能持续复用的开发流程。