研发人员如何写好 AI 提示词：从“问问题”到“驱动研发闭环”

AI 编程工具越来越强之后，很多研发人员会遇到一个相同的问题：明明模型能力很强，为什么实际用起来还是不稳定？有时能写出不错的代码，有时又会误解需求、跳过测试、改动过大，甚至把一个小问题修成一个大重构。

问题往往不在于"提示词写得不够玄学"，而在于我们把提示词当成了一句话指令，而不是研发过程的一部分。

这篇文章想讨论一套更适合研发人员的 AI 提示词方法：不要追求万能 Prompt，而要围绕研发闭环组织提示词。

复制代码

需求 → 设计 → 编码 → 测试 → Review → 发布 → 复盘

提示词的目标不是让 AI "更会聊天"，而是让 AI 更稳定地参与软件工程。

本文默认的主要落地工具是 Codex。也就是说，文章里的提示词不是只面向聊天窗口，而是面向一个能读文件、改代码、运行命令、调用 skill、维护计划并执行验证的编码 Agent。

因此，研发提示词的重点不应该是"让模型一次性吐出答案"，而应该是"驱动 Agent 完成一个可验证的工程任务"。

一、外部经验：主流 AI 编程工具都在强调什么

我先看了 OpenAI、GitHub Copilot、Anthropic Claude Code 等官方资料，以及一些 Agentic Software Engineering 的实践总结。虽然不同工具叫法不同，但经验高度一致。

1. 提供上下文，而不是只给任务

OpenAI 的提示工程建议强调：指令要清晰，任务要具体，并且要提供必要上下文。GitHub Copilot 也建议开发者在提问时说明目标、约束、相关文件、期望输出和验证方式。

研发场景里，坏提示词通常是：

复制代码

帮我写个订单取消接口。

更好的提示词是：

复制代码

我要新增订单取消接口。
业务规则：只有未支付订单可以取消；已支付订单不能取消。
请先阅读现有订单模块代码，说明 Controller、Service、Repository 应该如何分层，再给出实现计划。
实现后请补充对应测试，并说明如何验证。

差异不在文字长短，而在于后者给了：

复制代码

目标
业务规则
代码上下文要求
设计要求
测试要求
验证要求

2. 让 AI 先计划，再编码

Claude Code、Codex、Copilot Agent Mode 这类工具都越来越强调 Agent 工作流。它们不只是代码补全，而是可以读文件、改文件、运行命令、执行测试。

这意味着提示词也要从：

复制代码

你帮我写代码

升级为：

复制代码

你先理解需求和代码，再提出计划，经确认后小步实现，最后验证。

对于复杂任务，先计划比直接写代码更重要。

3. 明确验证标准

AI 编程最常见的问题之一，是"看起来完成了"，但没有证据。

好的提示词应该明确要求：

复制代码

修改完成后，请运行最小相关测试。
如果无法运行测试，请说明原因，并给出我应该运行的命令。

这会把 AI 从"生成答案"拉回到"交付结果"。

4. 使用项目级规则文件

现在越来越多工具都支持项目级规则：

Codex 使用 AGENTS.md
GitHub Copilot 支持 repository instructions
Cursor 有 rules
Claude Code 有 memory / project instructions
Windsurf、Cline 也有 rules、workflows、memory 等机制

这说明一个趋势：

复制代码

不要把所有规则都写进每次提示词。
稳定规则应该沉淀到项目文件里。

例如 Java 项目的分层规范、测试命令、日志规范、事务规则，不应该每次都重复说，而应该写进 AGENTS.md。

5. 把 Codex 当成研发工作台，而不是聊天框

如果主要使用 Codex，提示词要充分利用它的 Agent 能力。Codex 可以读取项目文件、修改代码、运行命令、维护计划、调用 skills，并在受控权限下执行验证。

所以，面向 Codex 的提示词应该更像任务说明书：

复制代码

请先阅读 AGENTS.md 和相关代码。
先输出你的理解和计划，不要直接修改。
修改时只处理本需求相关文件。
修改后运行最小相关测试。
如果需要执行破坏性命令或访问外部网络，先说明原因并等待确认。

这和普通聊天式提示词有本质区别：聊天式提示词追求回答质量，Codex 提示词追求工程闭环质量。

6. 提示词需要安全边界

AI Agent 能执行命令、修改文件、调用工具之后，提示词不仅要表达目标，还要表达边界。

例如：

复制代码

不要执行破坏性命令。
不要操作生产数据库。
不要修改无关文件。
任何涉及删除、回滚、数据库迁移、云资源变更的操作都必须先说明风险并等待确认。

这不是啰嗦，而是工程安全。

二、内部分析：研发提示词不该是"万能咒语"

结合我们自己的 Java AI Agent 研发体系，我认为研发提示词应该分四层。

复制代码

项目规则层：AGENTS.md
任务提示层：当前需求的目标、边界、验收标准
流程提示层：让 AI 按研发闭环工作
工具控制层：告诉 Codex 如何读文件、改代码、运行验证和处理权限

1. 项目规则层：先项目立宪

研发团队最应该先做的，不是收集 100 个提示词，而是给项目立宪。

也就是在项目根目录写好 AGENTS.md：

markdown 复制代码

Java Project Agent Guide

[Tech Stack]

- Java: 17
- Spring Boot: 3.x
- Build: Maven
- Test: JUnit 5

[Commands]

- Build: `mvn clean package`
- Unit tests: `mvn test`
- Run app: `mvn spring-boot:run`

[Architecture Rules]

- Controller 只处理 HTTP 入参、出参和状态码。
- Service 处理业务流程和事务边界。
- Repository/Mapper 只处理数据访问。
- 不允许 Controller 直接访问 Mapper。

[Testing Rules]

- 改业务逻辑必须补测试。
- 修 bug 必须补回归测试，除非说明原因。
- 优先写小测试，再考虑完整 SpringBootTest。

[Safety Rules]

- 不允许操作生产数据库。
- 不允许执行破坏性命令，除非用户明确确认。
- 不允许输出密码、token、身份证、手机号等敏感信息。

这一步的意义是：

复制代码

把每次都要重复说的话，变成项目默认规则。

没有项目立宪，提示词越写越长；有了项目立宪，提示词只需要描述当前任务。

2. 任务提示层：说清楚"这次要什么"

一次好的研发提示词，至少应该包括 6 个要素：

复制代码

目标
背景
边界
约束
验收标准
验证方式

模板如下：

复制代码

目标：我要实现/修复 xxx。
背景：当前业务/代码现状是 xxx。
边界：只修改 xxx，不要改 xxx。
约束：遵守 AGENTS.md；不要引入新依赖；保持兼容。
验收标准：满足 xxx 行为。
验证方式：运行 xxx 测试；如果无法运行，请说明原因。

如果任务偏业务沟通，也可以使用更容易上手的 STAR 表达：

arduino 复制代码

Situation：当前场景是什么？
Task：这次要完成什么任务？
Action：希望 AI 怎么处理？
Result：最终要交付什么结果？

例如：

arduino 复制代码

Situation：订单取消逻辑目前散落在 Controller 和 Service 中，测试覆盖不足。
Task：新增一个统一的订单取消接口，并保证只有未支付订单可以取消。
Action：请先分析现有代码，再给出分层设计和小步实现计划，最后补测试。
Result：交付代码改动、测试用例和验证结果。

这比"帮我写代码"稳定得多。

3. 流程提示层：让 AI 按研发闭环工作

研发不是一次生成，而是一个闭环：

复制代码

需求 → 设计 → 编码 → 测试 → Review → 发布 → 复盘

所以提示词也应该按场景组织，而不是所有任务都用同一句话。

4. 工具控制层：让 Codex 按正确方式行动

使用 Codex 时，提示词还要告诉 Agent 如何行动，而不只是要什么结果。

可以补充这些控制语句：

复制代码

先读 AGENTS.md 和相关代码，再制定计划。
不要修改无关文件。
每次改动保持小步、可 review。
优先运行最小相关测试，再考虑全量测试。
如果测试无法运行，请说明原因和建议命令。
涉及删除、重置、数据库、生产环境、外部网络或云资源操作时，必须先请求确认。

这层提示能显著降低 Agent 的随意性。

三、研发场景下的提示词模板

下面给出几类最常见研发场景的可直接使用模板。

0. Codex 通用启动模板

如果你不确定该怎么开始，可以先用这个模板：

markdown 复制代码

请在 Codex 中按工程任务处理，而不是只回答问题。

要求：
1. 先阅读 AGENTS.md 和相关代码。
2. 先输出你对需求、边界和风险的理解。
3. 给出小步实施计划。
4. 未确认前不要做大范围重构。
5. 修改后运行最小相关验证。
6. 如果需要执行破坏性命令、访问生产环境、访问外部网络或修改无关文件，先说明原因并等待确认。

任务：xxx
背景：xxx
验收标准：xxx

这个模板适合大多数不确定从哪里开始的研发任务。

1. 新需求开发

markdown 复制代码

先别急着写代码。请按以下流程处理这个 Java 后端需求：

1. 阅读相关代码和 AGENTS.md。
2. 澄清需求目标、业务规则和边界。
3. 给出 Controller、Service、Repository 的分层设计。
4. 说明需要新增或修改哪些文件。
5. 小步实现，不做无关重构。
6. 补充或更新测试。
7. 运行最小相关验证，并说明结果。

需求：xxx
业务规则：xxx
验收标准：xxx

适合：新接口、新业务流程、新模块、小型功能改造。

2. Bug 修复

markdown 复制代码

请按系统化 Debug 的方式处理这个问题，不要直接猜测修复。

要求：
1. 先复述你理解的故障现象。
2. 找到相关代码路径和可能影响因素。
3. 给出可验证的根因假设。
4. 尽量用测试、日志或代码证据验证假设。
5. 只做最小修复。
6. 补充回归测试，或说明为什么无法补测试。
7. 运行相关验证。

问题现象：xxx
错误日志：xxx
复现步骤：xxx

适合：线上异常、测试失败、偶现 bug、数据不一致。

3. SQL / 事务 / 持久化修改

markdown 复制代码

请重点从 Java 持久化风险角度检查这个变更。

请关注：
1. SQL 是否可能全表扫描或误更新。
2. WHERE 条件是否可能为空。
3. 分页排序是否稳定。
4. 是否需要索引或执行计划检查。
5. 事务边界、传播行为和回滚规则是否正确。
6. 是否存在锁范围过大、批处理内存过高或 N+1 问题。
7. 是否需要补充数据库相关测试。

需求：xxx
相关表：xxx
相关 Mapper/Repository：xxx

适合：MyBatis、JPA、Repository、SQL、事务、批处理、迁移。

4. 写测试

markdown 复制代码

请先为这个改动选择测试策略，不要默认使用 SpringBootTest。

请判断应该使用：
- unit test
- slice test
- integration test
- Testcontainers

要求：
1. 说明为什么选择该测试层级。
2. 测试应覆盖正常路径和关键异常路径。
3. Mock 只用于稳定边界，不要 mock 被测对象本身。
4. 测试名要描述业务行为。
5. 运行相关测试并说明结果。

目标代码：xxx
需要验证的行为：xxx

适合：补单测、补回归测试、测试重构、老项目加保护网。

5. 代码 Review

markdown 复制代码

请按 Java 后端生产级标准 review 这次改动。

重点检查：
1. 是否满足需求和验收标准。
2. Controller、Service、Repository 分层是否清晰。
3. 事务、SQL、锁、分页、批处理是否安全。
4. 是否存在权限、越权、敏感信息或注入风险。
5. 测试是否覆盖关键行为和回归场景。
6. 日志、traceId、metrics 是否支持线上定位。
7. 是否存在发布、回滚或兼容性风险。

请按严重程度输出：Blocking / Important / Suggestion。

适合：PR Review、AI 生成代码审查、上线前自查。

6. 上线前检查

markdown 复制代码

请做一次 Java 后端上线前检查。

重点检查：
1. 是否有数据库变更，是否兼容，是否可回滚。
2. 是否有配置变更，不同环境是否一致。
3. 是否影响老接口、老客户端、老消息消费者。
4. 是否有 feature flag、灰度或回滚方案。
5. 是否有 smoke test。
6. 是否有日志、metrics、告警和排障路径。
7. 失败后如何止损和恢复。

变更内容：xxx
计划上线范围：xxx

适合：发版前、数据库迁移、配置变更、核心链路改动。

7. 长任务与上下文管理

markdown 复制代码

这是一个长任务，请不要只依赖当前对话上下文。

要求：
1. 先建立任务计划、发现记录和进度记录。
2. 每完成一个阶段，更新当前进展和剩余风险。
3. 重要结论写入文档，不只留在聊天记录里。
4. 如果上下文过长，请先总结当前状态，再继续执行。
5. 每个阶段都要有明确验证方式。

任务目标：xxx
涉及模块：xxx
预期交付：xxx

适合：模块重构、跨服务排查、升级迁移、批量治理、长时间调研。

8. 解释代码 / 帮新人理解模块

markdown 复制代码

请帮助我理解这段 Java/Spring 代码。

要求：
1. 先用一句话说明它解决什么业务问题。
2. 再按调用链解释主要流程。
3. 标出关键类、关键方法和关键数据结构。
4. 说明可能的异常路径、事务边界和外部依赖。
5. 最后给出新手阅读这块代码的建议顺序。

代码/文件：xxx
我当前最困惑的是：xxx

适合：接手老项目、Code Review 前理解上下文、带新人熟悉模块。

9. 生成文档 / 接口说明

markdown 复制代码

请基于现有代码生成面向研发团队的说明文档。

要求：
1. 不要编造代码里不存在的行为。
2. 先说明模块职责和核心流程。
3. 列出主要接口、入参、出参、错误码和边界条件。
4. 标出依赖的数据库表、外部服务、配置项和消息主题。
5. 最后给出测试和排障建议。

目标模块/接口：xxx
文档读者：后端研发 / 测试 / 前端 / 运维

适合：接口文档、模块说明、交接文档、测试说明。

10. 学习新技术 / 做技术调研

markdown 复制代码

请帮我做一次面向 Java 后端研发的技术调研。

要求：
1. 先说明这个技术解决什么问题，不要直接堆概念。
2. 对比它和我当前技术栈的差异。
3. 给出适合使用和不适合使用的场景。
4. 给出一个最小可运行示例或接入步骤。
5. 列出生产落地风险、性能影响、监控和回滚方案。

技术主题：xxx
当前技术栈：xxx
目标场景：xxx

适合：技术选型、学习新框架、引入新组件前调研。

11. 复盘与知识沉淀

markdown 复制代码

请总结这次任务中是否有值得长期沉淀的经验。

请判断：
1. 是否应该写入 AGENTS.md，成为项目硬规则。
2. 是否应该写入 wiki，成为项目知识。
3. 是否应该提炼成 project skill，供以后自动触发。
4. 是否只是一次性上下文，不需要沉淀。

任务背景：xxx
最终修复/实现：xxx
踩坑或关键发现：xxx

适合：复杂 bug 修复后、事故复盘后、架构决策后、重复踩坑后。

四、提示词不是越长越好，而是越结构化越好

很多人会把提示词工程理解成写一段很长的"咒语"。研发场景里，这通常不是最佳做法。

好的研发提示词应该满足 5 个标准：

复制代码

明确目标
给足上下文
设定边界
要求验证
方便沉淀

坏例子

复制代码

帮我优化一下订单模块。

问题：

什么叫优化？
优化性能、结构、测试还是可读性？
能改哪些文件？
怎么验证？
是否允许重构？

好例子

markdown 复制代码

请分析订单模块中 OrderService 复杂度过高的问题。
先不要改代码。
请先输出：
1. 当前主要职责有哪些。
2. 哪些职责可以拆分。
3. 哪些测试需要先补。
4. 推荐的小步重构计划。

约束：
- 不改变现有接口行为。
- 不引入新框架。
- 优先保持数据库访问逻辑不变。
- 需要说明每一步如何验证。

这个提示词没有更"神秘"，只是更像工程任务。

五、从"模板提示词"到"工程提示词"

很多提示词文章会提供大量模板，例如解释代码、生成文档、写单测、做 Review、学习新技术。这些模板有价值，特别适合刚开始使用 AI 的研发人员。

但在真实研发中，模板只是起点。要让 AI 稳定产出，需要把模板升级成工程提示词。区别如下：

普通模板提示词	工程提示词
帮我解释这段代码	解释业务目的、调用链、异常路径、事务边界和阅读顺序
帮我写单测	先选择测试层级，再覆盖正常路径、异常路径和回归场景
帮我优化代码	先定义优化目标、边界、风险和验证方式
帮我写文档	基于真实代码生成，不编造行为，明确读者和交付格式
帮我学习技术	结合当前技术栈、目标场景、落地风险和最小示例

也就是说，模板解决"怎么开口"，工程提示词解决"怎么交付"。

六、哪些问题不应该继续靠提示词解决

提示词不是万能容器。一个团队真正成熟后，很多内容应该从 prompt 中迁移出去。

内容类型	不建议长期放在提示词里	应该放到哪里
每次都必须遵守的项目规则	Java 版本、测试命令、分层规范	`AGENTS.md`
高频重复流程	新需求、Bug 修复、上线检查	workflow / `docs/prompts/`
Java 专项判断	SQL 风险、事务边界、测试策略	`java-*` skill
项目独有经验	支付幂等、订单状态机、老数据兼容	wiki / project skill
临时任务状态	当前进度、发现、待办	planning files

判断标准很简单：

复制代码

一次性信息 → 写在当前提示词
反复使用的信息 → 沉淀成模板
必须遵守的规则 → 写进 AGENTS.md
专业判断清单 → 做成 skill
长期项目经验 → 写进 wiki 或 project skill

这能避免提示词越来越长，也能让团队共享同一套工程规则。

七、适合团队沉淀的提示词资产

真正有价值的提示词，不应该只存在个人聊天记录里，而应该沉淀成团队资产。

建议分四类沉淀：

1. 项目规则

放入：

复制代码

AGENTS.md

例如：

复制代码

Controller 不直接访问 Mapper。
生产问题修复必须补回归测试。
数据库迁移必须写回滚方案。

2. 场景模板

放入：

bash 复制代码

docs/prompts/

例如：

bash 复制代码

docs/prompts/new-feature.md
docs/prompts/bug-fix.md
docs/prompts/sql-review.md
docs/prompts/release-check.md

3. 专项 Skill

放入：

bash 复制代码

.agents/skills/

例如：

css 复制代码

java-persistence
java-observability
payment-callback-idempotency
order-state-machine-rules

4. 项目知识库

放入：

复制代码

wiki

例如：

复制代码

订单状态机说明
支付回调幂等规则
用户 ID 历史兼容规则
核心链路排障手册

八、研发提示词的最终心法

我认为研发人员写 AI 提示词，应该从"问答思维"升级成"工程协作思维"。

不要只问：

复制代码

AI 能不能帮我写代码？

而要问：

复制代码

我如何让 AI 稳定参与研发闭环？

最终可以记住这句话：

复制代码

提示词不是一句命令，而是一次工程任务的上下文、边界、流程和验收标准。

如果团队想真正用好 AI Agent，最重要的不是收集 100 个万能提示词，而是建立三件事：

复制代码

项目立宪：把稳定规则写进 AGENTS.md
流程模板：把高频任务做成提示词模板或 workflow
知识沉淀：把踩坑经验写进 wiki 或 project skill

当这三件事做好之后，AI 不再只是一个"会写代码的聊天框"，而会变成一个更可靠的研发协作者。

参考资料

以下资料用于校准本文中的外部经验和工具趋势。不同工具的具体能力会变化，团队落地时应优先以当前使用工具的官方文档为准。

OpenAI Prompt Engineering Guide: platform.openai.com/docs/guides...
OpenAI Codex Documentation: developers.openai.com/codex/
GitHub Copilot Custom Instructions: docs.github.com/en/copilot/...
GitHub Copilot Prompt Engineering: docs.github.com/en/copilot/...
Anthropic Prompt Engineering Overview: docs.anthropic.com/en/docs/bui...
Claude Code Best Practices: www.anthropic.com/engineering...
Claude Code Common Workflows: docs.anthropic.com/en/docs/cla...
AGENTS.md: agents.md/
掘金：AI提示词使用场景与模板文章: juejin.cn/post/763372...