NOTE: 建议结合 AI(Cursor 或 Codex)与 Git 来管理和维护代码。
- 重要任务先规划,再修改代码。
- Git 是长期维护的安全底座。
GPT生成的完整文档:从零建立 AI 项目的协作与规范
引言
很多人习惯这样使用 Vibe Coding(以一个 SLAM 工程为例):
上午让它修改 IMU 预积分,中午修改视觉残差,下午优化 Local Mapping,晚上接着修改时间同步。
第二天继续打开同一个对话,发现它越来越容易出现重复分析、遗漏约束、修改无关模块等情况。
这不一定是模型本身能力下降,也可能是长期对话累积了大量旧日志、失败尝试及过期信息,导致上下文管理变得困难。
因此,我的建议是:一个独立开发任务对应一个 Codex 对话,跨对话依靠项目文件交接。
首次初始化项目
首先让 AI 认识你的项目,并建立长期维护机制。我建议将初始对话命名为 00 - 项目初始化与长期开发规范。
这个对话需要完成三个任务:
- 分析项目现有代码和文档,建立
AGENTS.md。 - 基于实际代码建立
PROJECT_CONTEXT.md。 - 建立每次任务结束时的交接机制。
- 提示词 A:项目首次初始化(适用于第一次打开已有代码仓库,或接手长期研发项目)
你将作为当前代码仓库的长期研发助手。
请首先分析仓库结构、Git 状态、核心模块、
构建与测试方式,并建立长期维护机制。
创建或完善:
1. AGENTS.md:长期开发规范
2. PROJECT_CONTEXT.md:项目真实架构和状态
3. docs/TASK_HANDOFF.md:任务交接记录
要求:
- 基于实际源码,不能猜测实现状态。
- 优先复用现有文档,避免重复。
- 将项目事实与未来研发计划分开。
- 在 AGENTS.md 中明确任务开始、结束和交接规则。
- 不修改算法代码,不自动提交或推送 Git。
请完成初始化并汇报。
初始化后,建议你的仓库先保持这种简单结构:
Work_Space/
├── AGENTS.md
├── PROJECT_CONTEXT.md
├── ROADMAP.md
├── README.md
├── docs/
│ └── TASK_HANDOFF.md
├── src/
├── include/
├── config/
└── ...
| 文件 | 主要用途 | 主要区别 |
|---|---|---|
AGENTS.md |
Codex 的长期开发规范 | Codex 开发时必须遵守的规则 |
PROJECT_CONTEXT.md |
项目背景与技术架构 | 记录已核实的实现状态 |
ROADMAP.md |
未来计划与开发任务 | 未来准备实现的功能 |
docs/TASK_HANDOFF.md |
最近一次任务的开发交接 | 已完成事项、遗留问题与下一步 |
其中,ROADMAP.md 可以在初始化后按需建立,用于记录未来计划,与已实现功能分开。
如果你之后手动修改了这些文档,可以用下面的提示词让 AI 重新读取:
我已手动更新项目维护文档。
请重新读取 AGENTS.md,并按需核对 PROJECT_CONTEXT.md、ROADMAP.md 和 docs/TASK_HANDOFF.md。
如新文档与当前源码或旧对话结论冲突,请指出差异,
本轮暂时不要修改代码和文档。
开始新任务
在同一个代码仓库中,新建一个 Codex 对话(无需新建代码仓库),并为对话命名,方便后续查找。
- 提示词 B:新任务开始(商量方案)
开始新任务:***
请遵循 AGENTS.md,按任务需要读取 PROJECT_CONTEXT.md、ROADMAP.md 和 docs/TASK_HANDOFF.md,并检查当前 Git 与源码状态。
本轮先只读分析:
1. ***
2. 分析现有假设、边界情况、潜在问题及影响范围。
3. 提出分步骤的修改方案,并说明需要我验证哪些行为。
先输出技术分析与开发计划。
未经我确认,不要修改任何源码。
对于这种可能涉及多个文件的复杂任务,可以在支持该功能的 Codex 界面中使用 /plan 进入 Plan Mode,让 AI 先提出计划,再进入实现。
- 确定方案后,在同一个对话中继续
- 提示词 C:任务执行(开始写代码)
我同意上述开发方案,请开始实施。
要求:
1. 以本轮确认的技术方案为准,修改相关源码。
2. 普通修复尽量保持改动局部;如本轮明确授权架构重构,则可以进行必要的跨模块调整。
3. 修改时关注接口兼容性、时间戳、坐标系、数值稳定性及线程安全。
4. 如发现必须改变核心算法或技术路线,先说明原因。
5. 完成后进行静态自查,汇报修改文件、核心逻辑、潜在风险,并列出建议我编译和验证的事项。
编译、ROS 运行、rosbag 回放及实验评测由我负责。
本轮不要执行上述命令,也不要自动提交或推送 Git。
接下来可以在这个对话内持续交流,包括询问某个函数的作用、纠正 Codex 的实现、反馈自己编译时遇到的报错,以及要求它进一步优化。
只要仍在解决同一个任务,就可以继续使用当前对话。
- 问题解决后,结束当前的对话
当代码修改完成,自己完成必要的编译与验证,准备开展下一个模块时,不建议直接结束对话。即使还存在待验证事项,也应如实记录。
- 提示词 D:任务结束与交接
本轮任务准备收尾,请执行开发交接。
1. 对照最初目标,区分已完成、未完成和待用户验证的内容。
2. 总结实际修改的文件、关键逻辑和技术决策。
3. 根据当前 Git Diff 检查是否混入无关修改。
4. 更新 docs/TASK_HANDOFF.md,记录当前状态、改动范围、遗留问题、验证建议以及下一步接手入口。
5. 仅当实际架构或实现状态发生重要变化时,更新 PROJECT_CONTEXT.md。
6. 非必要不修改 AGENTS.md;ROADMAP.md 的优先级或技术路线不得未经我确认自行调整。
7. 对我尚未实际执行的编译和实验,明确标注“未验证”。
本轮不要再修改无关算法代码,不自动提交或推送 Git。
这里的关键不是让 AI 写一大篇总结,而是让它保存下一轮开发仍然需要知道的信息。
- 下一轮任务的开启
- 提示词 E:下一个任务启动
现在开始新的独立开发任务: ****
请遵循 AGENTS.md,按需阅读 PROJECT_CONTEXT.md、ROADMAP.md 和 docs/TASK_HANDOFF.md,并以当前实际源码及 Git 状态为准。
上一轮任务已经收尾,只继承对本轮有影响的技术约束和遗留依赖。
请先定位相关实现,分析当前残差构建与优化过程,提出分阶段修改方案及建议我验证的内容。
第一阶段只分析,不修改代码,不编译运行。
这样一来,新的 AI 对话不需要重新看几百轮旧消息,也能理解必要的项目背景。
什么时候开新对话,什么时候继续旧对话?
| 情况 | 建议 |
|---|---|
| 继续调试当前时间同步 Bug | 留在原对话 |
| 当前方案修改后出现编译错误 | 留在原对话 |
| 当前任务尚未通过测试 | 留在原对话 |
| 时间同步完成,开始开发回环检测 | 新建对话 |
| 新增一个与当前任务无关的功能 | 新建对话 |
| 长对话仍在解决同一复杂任务 | 可以压缩上下文后继续 |
| 需要同时修改两个独立模块 | 分别建立对话,最好隔离工作目录 |
定期整理
使用 Vibe Coding 开展长期开发时,迟早会遇到的一个问题:项目文档会随着开发不断膨胀。 建议在当前阶段结束,或者发现两个文件明显膨胀时,开启一个专门的文档维护对话。
请对当前项目的长期研发文档进行一次整理,重点关注:
- `docs/TASK_HANDOFF.md`
- `ROADMAP.md`
- 如有需要,整理 `docs/task_history/` 和 `docs/IDEA_BACKLOG.md`
**1. 任务交接整理**
保留当前任务、最近的重要任务及仍然有效的遗留问题。
将较早的已完成任务整理归档,保留关键技术决策、修改文件、Git 提交信息以及必要的历史依据。
确保 `TASK_HANDOFF.md` 可以独立支持下一轮开发,不需要每次阅读完整历史记录。
**2. 研发规划整理**
检查 `ROADMAP.md`,区分:
- 正在实施的任务
- 已确认的后续计划
- 中长期研发目标
- 尚未确认的 AI 建议
对重复、过时或存在依赖关系的任务进行梳理。
对于尚未决定是否实施的建议,可以整理至 `docs/IDEA_BACKLOG.md`,但不得擅自删除重要研究思路,也不得改变我确认的研发优先级。
**3. 文档一致性**
结合实际源码和 Git 状态进行静态核实。
确保项目事实、未来计划和历史交接之间不存在明显矛盾。
**4. 修改原则**
- 优先保留原有文档的内容和结构。
- 仅进行必要的整理、去重、归档和交叉引用调整。
- 不擅自修改已经确定的技术路线。
- 不丢失有价值的历史决策与研发建议。
- 不修改算法源码,不编译、不运行、不提交 Git。
完成后,请汇报整理前后的文档结构、归档内容以及仍需我确认的事项。
最终的项目结构可能如下:
Work_Space/
│
├── AGENTS.md
├── PROJECT_CONTEXT.md
├── ROADMAP.md
├── README.md
│
├── docs/
│ ├── TASK_HANDOFF.md
│ ├── IDEA_BACKLOG.md # 可选:候选建议较多时创建
│ │
│ ├── task_history/ # 可选:历史交接归档
│ │ ├── 2026-10.md
│ │ └── 2026-11.md
│ │
│ └── ...其他已有技术文档
│
├── src/
└── script/
几个常用的补充提示词
日常开发时,我还会使用一些更简短的指令。
• 你对于我的这个需求还有没有什么不明白的,有的话你就提出来。如果没有的话,你先给我列一下实现这个需求的任务列表
• 你对于我的这个需求还有没有什么不明白的,有的话你就提出来。如果没有的话,你开始执行吧(请注意,修改了代码后,不需要编译和运行,请先进行静态检查,我来编译验证)
• 你对于我的这个需求还有没有什么不明白的,有的话你就提出来。如果没有的话,你开始执行吧(请注意,先分析,先不改代码)
结束语
这套规范是适用于大多数的agent的,比如Codex、Cursor,下面总结下完成了开发架构设计后,常用的提示词模板:
我们开始一个新的开发任务: 【任务名称】
请遵循项目根目录的 AGENTS.md,根据需要读取 PROJECT_CONTEXT.md、ROADMAP.md、docs/TASK_HANDOFF.md 等相关项目文档,并结合当前实际源码开展工作。
本轮任务:【填写具体开发需求】
# 如果是分析
如果需求中存在影响分析准确性或技术判断的关键歧义,请先向我确认;否则请自行做出合理判断,直接开展深入分析,无需等待我进一步确认。
请结合实际源码给出分析结果、存在的问题及合理的改进建议,必要时说明关键实现位置、技术依据与潜在风险。
本轮仅进行分析,不修改代码或项目文档。
# 如果是直接执行
如果需求中存在影响正确实现的关键歧义,请先向我确认;否则请自行做出合理判断,直接分析并修改代码,无需先提交方案或等待确认。
实施过程中可以自主处理本轮任务范围内的相关问题;如果涉及重大技术路线调整、核心架构变更或明显超出本轮需求的修改,请先向我确认。
完成后进行静态自查,简要汇报修改内容、涉及文件及注意事项,并按规范更新任务交接记录。
- 补充:
对于因额度耗尽的终止,等额度恢复后,可用如下提示词
继续上一轮因额度不足而中断的任务。基于当前对话上下文和工作树,检查已完成的修改及尚未完成的工作,从中断处继续执行。不要重复已完成的工作。