换一个对话继续写项目，往往得先补一遍背景：哪些功能已经完成，哪些设计不能改，上次为什么没有继续发布。

这些信息散在聊天记录里，接手的人或 AI 就得重新翻找。项目开始持续迭代后，我建议把它们整理进仓库。下次继续时，先读相关文件，再核对代码，不必只靠聊天记录接续工作。

但指导文件也需要取舍。OpenAI 在 《Rethinking skills and prompts for GPT-6 Astra》 中建议重新检查技能和项目指令，减少无关阅读、过度测试，以及不必要的停工确认。

下面介绍一种具体做法：文件怎么分工，第一次怎么建立，之后怎么更新。这是项目维护建议，不是官方规定的文件清单，也不要求凑齐每一份。

每份文件解决什么问题

项目介绍、开发规则和当前进度各有用途，分开放更容易查。

持续开发的小项目可以先从前三份开始。需要跨对话交接时加上 HANDOFF.md，有版本发布时再维护 CHANGELOG.md。如果只是一次性脚本，把简短的开发说明留在 README 里也够用。

架构复杂了，可以用 docs/architecture.md 解释模块边界；有固定发布流程，就单独写发布指南。SECURITY.md 和 PRIVACY.md 则分别说明安全反馈渠道、实际的数据处理方式，按项目需要建立。

文件放进仓库，不代表工具就一定会读取。比如 HANDOFF.md 只是这里采用的交接文件名，接续任务时应明确让助手查看它。其他文件的自动加载规则，也要以所用工具为准。

AGENTS.md 里留什么

AGENTS.md 适合写那些长期有效、做错了容易出问题的要求：不能绕过事务修改数据，不能提交密钥，改动某类代码后要做哪些检查。

较长的操作步骤放到对应文档，注明什么时候读。例如，“调整数据库结构时查看迁移指南”，就比“每次修改前读完全部文档”更合适。

测试流程如果已经写在 CONTRIBUTING，其他地方链接过去即可。复制三份，修改时就得记住改三处，很容易漏。

文档也会让助手多做事

小改动，全套验证

修正 README 的一个错字，却要启动多个代理、创建隔离工作目录、跑全部测试，再构建安装包。流程看起来很认真，只是大部分与这次修改无关。

文档修改检查内容、链接和格式；功能修改运行相关测试。涉及公共逻辑、数据迁移或正式发布时，再扩大验证范围。该保留的数据安全和回归检查不能省，但也不必让所有任务走同一套流程。

旧计划没有注明适用范围

一份旧计划要求“必须使用多个代理”，另一份要求“禁止创建代理”；上次验收前写下的“不要推送”，又被带进已经批准发布的新任务。

这些要求在当时可能都合理。旧计划应注明对应阶段，不能继续当作当前待办。反过来也一样：这次允许发布，不等于以后每次修改都能自行发布。

已经确认的事，反复询问

已经确认实施的方案，不必每完成一步都再问一次是否继续。没有连接测试设备时，反复查询设备列表也不会自动解决问题。

可以把边界写明：在当前授权范围内继续；遇到会改变任务范围或产生重要后果的未决选择，再询问。环境受阻就说明缺什么，先完成其余工作。没能验证的部分如实留下，不能写成“已经通过”。

第一次建立，用这段提示词

“生成一套最完善的指导文件”太宽泛。助手需要先看项目，才能知道测试怎么跑、哪些数据不能动，以及已有文档能否复用。

把下面这段发给能访问项目文件的编程助手，可用于新建，也可用于整理已有文档。

请检查本项目的代码结构、构建配置、测试和现有文档，建立或优化项目指导文件。已有同类文件优先复用，不创建没有用途的文件。

先阅读这篇参考文章：
https://developers.openai.com/blog/rethinking-skills-and-prompts-for-gpt-6-astra
参考其中精简指令、按需读取和明确执行边界的建议，不照搬模型专属要求。文章无法访问时如实说明，继续依据项目实际情况工作。

文件分工：
- README.md：项目用途、功能、安装运行方法和文档入口。
- AGENTS.md：供编程代理读取的长期约束、验证原则和交付边界；细节链接到对应文档。
- CONTRIBUTING.md：开发环境、命令、代码规范、测试选择及贡献流程。
- HANDOFF.md：需要交接时建立，注明日期及适用提交，记录完成状态、剩余事项、阻碍和重要经验。
- CHANGELOG.md：有版本交付时记录用户可感知的变化。
- 架构、发布、安全、隐私文档：仅在项目实际需要时建立。

重点检查：
1. 过度干活：按改动风险选择阅读、测试、构建和协作范围，不为小改强制全套流程。
2. 指令冲突：区分长期规则、历史计划和状态记录；旧任务的授权、禁令和待办不自动延续。
3. 无意义等待：沿用当前任务已有授权，只在真实依赖或重大未决选择处暂停，不重复无变化的检查。

保留数据安全、隐私、架构边界、兼容性和关键回归验证。同一信息只在一处维护，其他文件链接引用；历史方案注明适用范围。

命令和状态必须有实际依据，不虚构版本、测试结果或安全承诺。本轮只更新文档，不修改业务代码，也不自行提交、推送或发布。纯文档修改只做相关内容、链接和差异检查。

完成后简要说明各文件的作用、主要修改、仍需确认的问题和实际检查结果。

生成后，人工核对一下命令和约束，尤其留意完成声明。文档写着“测试通过”，不等于测试真的跑过。

一轮工作结束后，更新哪些文件

新增功能可能需要更新 README 和 CHANGELOG；测试命令变了，改 CONTRIBUTING；准备换对话继续，整理 HANDOFF。只有长期协作规则变化，才需要动 AGENTS。没有变化的文件就保持原样。

交接记录尽量写具体。下面是虚构示例：

截至提交 abc1234：导出功能已完成，相关单元测试通过。
未验证：Android 分享操作；当前没有可用测试设备。
下一步：连接测试设备后验证分享流程。

读这几行就知道下一步做什么，也知道哪些检查没做。提交号说明结果属于哪个版本，不能因为旧版本通过了测试，就认定后面的修改也通过了。

每轮功能完成、准备交接或发布前，可以发这段提示词：

请核对本次任务的代码差异、配置、提交和已有验证记录，只同步受影响的项目文档，不重写整套文件，不覆盖无关修改。

按职责检查：
- README.md：功能、使用方法、运行命令和界面展示是否仍准确。
- AGENTS.md：仅更新有变化的长期约束，不写入一次性任务过程。
- CONTRIBUTING.md：同步环境、命令、测试策略和贡献流程的变化。
- HANDOFF.md：有交接需要时，更新状态、剩余事项、阻碍和重要经验，注明日期及适用提交。
- CHANGELOG.md：记录用户可感知的变化；未发布内容放入待发布区，不虚构发布日期。
- 架构、发布、安全和隐私文档：仅在对应行为或流程变化时更新。

顺便检查是否新增了过度干活、指令冲突或无意义等待的要求。同一信息只在一处维护，历史计划不作为当前待办。不改没有变化的内容，也不为普通经验新增整份指南。

完成声明和测试结果必须有依据，注明本次验证、仍适用的历史结果和未验证事项。纯文档更新只做内容、链接和差异检查，不运行无关测试或构建。

最后简要报告修改的文件及原因、剩余问题和实际检查结果。提交、合并、推送或发布只按当前任务已有授权执行。

日常更新不必每次重读参考文章。发现助手总在同一处误解、重复干活或停下来时，再检查相关规则。维护文档也应有个结束点：改完受影响的内容，核对无误，就回到项目本身。