多端项目如何使用 Codex：从需求讨论到 Git 交付的一套协作方法论

适用场景：一个业务项目同时包含 APP、PC 管理后台、后端服务、接口文档、SQL、设计稿和发布包；希望在不同 Codex 会话之间仍能持续推进项目。

很多人刚开始使用 Codex 时，会把它当成"能写代码的聊天工具"：开一个会话，描述需求，写完代码就结束。项目小的时候没有问题；一旦进入真实研发阶段，需求会反复调整，APP、PC 和后端需要联调，接口与表结构持续变化，还要提交、发布和复盘，这种方式很快会失控。

更合适的定位是：把 Codex 接入项目的协作体系，而不是把项目上下文留在某一段聊天记录里。

本文以一个包含 APP、管理后台和后端的项目为例，整理一套可复用的方法。

一、先接受一个事实：新会话不会自动记住项目

新会话不会完整继承上一个会话的讨论和判断，但它可以通过项目资料和 Git 记录迅速恢复上下文。

因此，项目的"记忆"不应只放在聊天中，而要沉淀到下面三类载体：

载体	解决的问题
`AGENTS.md`	Codex 在这个目录中应该遵守什么规则、先看什么资料、能做和不能做什么
需求、接口、SQL、变更与发布文档	产品与技术事实：为什么做、怎么做、当前规则是什么
Git 分支、提交和差异	代码实际上改了什么、哪些已提交、哪些尚未合并

这样，无论换人、换会话还是隔几天再继续，都有可追溯的入口。

二、建立"资料中枢 + 三个代码仓库"的结构

我的项目采用如下结构：

text 复制代码

D:\videCodeing\aaaaa\                 # 项目资料与协作中枢
  AGENTS.md
  项目需求文档.md
  接口版本变更记录.md
  表结构创建规范.md
  开发变更记录.md
 版本发布功能说明.md

D:\b\                                   # APP 代码仓库
  AGENTS.md

D:\node\aaaaa-webui\                  # PC 管理后台代码仓库
  AGENTS.md

D:\IDEA\aaaaa-webapi\                 # 后端代码仓库
  AGENTS.md
  docs\api\README.md

这里最容易犯的错误，是把所有规则都塞进一份文档，或者把需求、接口、进度和代码规范混在一起。正确做法是分层。

1. 资料中枢的 `AGENTS.md`：负责"项目协作"

资料中枢的 AGENTS.md 不写某个前端框架的具体命令，而应写项目级规则：

三端代码分别在哪里；
哪些文件是需求、接口、SQL、设计稿、发布说明的事实来源；
跨端需求必须确认哪些接口契约；
需求、接口、数据库、发布变更分别同步到哪里；
什么情况下可以提交代码，什么情况下必须停下来确认。

例如，跨端规则可以这样写：

md 复制代码

当需求影响 APP、管理后台、后端中的两个或以上端时：

1. 明确各端的改动清单；
2. 确认接口路径、请求参数、返回字段、错误码与兼容策略；
3. 接口变更同步更新接口文档和接口版本变更记录；
4. SQL 变更保存在实际 SQL 文件中，并记录执行顺序、兼容性和回滚方式；
5. 不得仅修改一个端而假定其他端自然兼容。

2. 每个代码仓库的 `AGENTS.md`：负责"怎样改这端的代码"

APP、管理后台和后端不在同一个目录时，各自需要一份 AGENTS.md。它们不应复制项目总规则，而应记录本仓库的真实执行信息：

技术栈与版本；
启动、构建、检查命令；
路由、接口封装、状态管理、公共组件或后端分层的位置；
代码风格和测试规则；
对项目资料中枢的引用路径。

例如，APP 端可以规定：

md 复制代码

开始涉及业务功能的任务前，按需阅读：

- D:\videCodeing\aaaaa\AGENTS.md
- 对应需求与接口文档
- 本项目 README、架构说明和目标模块现有代码

优先复用已有组件、请求封装和状态管理方案。
接口字段与文档不一致时，先记录差异并确认，不得自行假设。

后端的 AGENTS.md 还应额外明确数据库迁移、鉴权、数据隔离、API 文档与测试类的规则。

三、让新会话先"接手"，而不是马上写代码

每次新开会话，最重要的不是把所有资料和整个仓库扫一遍，而是按任务范围加载必要上下文。

本项目为此增加了 $aaaaa-project-context Skill。它的作用是：

先读取项目资料中枢的 AGENTS.md；
判断当前是需求讨论、方案跟进、状态查询、资料维护，还是代码实施；
只读取与当前任务直接相关的资料或代码；
避免递归扫描整个仓库、加载无关模块或构建产物。

新会话可以这样开始：

text 复制代码

$aaaaa-project-context

我要讨论 APP 菜单"我的"中新增"欢迎语管理"功能。
本次仅做需求讨论，不修改代码、数据库、配置或正式文档。
请先基于相关需求、接口和现有模块，说明现状、影响范围、风险和待确认项。

对于需求讨论，Codex 应优先读取相关需求、评审、接口或变更记录；只有问题依赖实现细节时，才进入目标代码仓库查找对应模块。这样既能保持上下文准确，也不会因为全文档、全仓库读取而浪费上下文。

四、把需求讨论、需求确认和开发实施分成三个阶段

需求变化频繁时，最危险的事情是把"讨论中的想法"直接写进正式需求，或者一边讨论一边改代码。

推荐把一个需求拆成三步。

阶段 1：讨论------只分析，不落代码

示例提示词：

text 复制代码

$aaaaa-project-context

讨论需求：APP"我的"新增欢迎语管理。
暂不修改代码、数据库、配置或正式需求文档。

请先输出：
1. 当前是否已有欢迎语相关能力、接口、数据表或半成品代码；
2. 该功能影响 APP、后端、数据库、管理后台的范围；
3. 页面流程、业务规则和边界情况；
4. 需要产品确认的问题。

这一步的产出应是方案选项、风险和待确认事项，而不是代码。

阶段 2：确认------更新正式需求基线

当产品方案确认后，再明确要求更新正式文档：

text 复制代码

欢迎语管理方案已确认。
请更新《项目需求文档.md》中的相关章节：

- 补充功能目标、入口、页面流程和业务规则；
- 写明是否影响接口、数据库和其他端；
- 补充验收标准；
- 在文档顶部的变更记录中新增一条记录；
- 不修改尚未确认的其他需求。

更新后仅汇报文档变更摘要，不开始开发。

正式需求文档应该记录"已经确认要做什么、如何验收"。讨论理由、备选方案和未决问题，则放在独立的评审或决策记录中。

阶段 3：实施------先拆端，再开发

确认需求后，先让 Codex 输出三端改动清单：

text 复制代码

请以已确认的欢迎语管理需求为准，拆分 APP、后端、数据库、管理后台的改动项。
明确接口契约、兼容策略、联调顺序、验收方式和风险；确认后再开始开发。

小功能通常可在同一会话内完成"后端接口 → 前端接入 → 联调"。复杂功能则可拆成后端、APP、PC 会话，但接口契约必须先冻结，并由一个集成会话负责联调与验收。

五、大量接口不要放在一份超长文档里

接口数量增长后，不要让每次联调都全文读取一份几百页的 Markdown。推荐使用"总索引 + 业务模块"的结构：

text 复制代码

docs/api/
  README.md                 # 鉴权、环境、分页、通用字段、模块索引
  common/
    errors.md               # 错误码
    models.md               # 通用对象和枚举
  app/
    welcome-messages.md     # 欢迎语管理
    customers.md            # 客户
    todos.md                # 待办
  admin/
    employees.md            # 员工与成员

做"欢迎语管理"时，只读取：

text 复制代码

README.md + common/errors.md + common/models.md + app/welcome-messages.md

不需要加载客户、合同、录音、团队等无关接口。若后端已有 Swagger/OpenAPI，建议以它作为接口字段的事实来源；Markdown 则用于沉淀业务规则、联调约定和变更说明。

六、需求文档持续更新，但必须有边界

需求文档是活文档，但不是聊天记录。建议在项目 AGENTS.md 里加入下面的规则：

md 复制代码

当用户明确表示"确认""按此方案执行""进入开发"或"更新需求文档"时：

1. 定位受影响的现有章节；
2. 只修改相关内容，不无关重写整份文档；
3. 同步更新功能说明、交互规则、接口影响、验收标准和待确认项；
4. 在文档顶部的变更记录中新增一条记录。

讨论中的猜测、方案和未确认事项，不得直接写入正式需求文档。

文档职责可简单划分为：

文档	记录什么
`项目需求文档.md`	已确认的需求范围、规则、流程与验收标准
后端接口文档	请求、返回、错误码、示例和兼容性
`接口版本变更记录.md`	接口新增、字段变更、废弃与兼容策略
SQL 文件与表结构规范	实际数据库变更与建表要求
`开发变更记录.md`	每次开发改动、验证、风险、提交与推送状态
发布说明	版本内容、发布步骤、已知问题与回滚方案

七、代码提交不是"顺手 git commit"，而是一次交付

本项目增加了 $aaaaa-git-delivery Skill，用于用户明确要求提交或主动调用 Git 交付流程时使用。

它应完成的不是全仓库审查，而是一次有边界的交付：

确认目标仓库、分支和本次任务范围；
查看 git status、任务相关 diff、diff 检查；
检查改动中明显的逻辑问题，例如空值、边界、分支、接口字段不一致和漏掉的错误路径；
不混入他人的改动或来源不明的文件；
先更新 开发变更记录.md；
只暂存本次任务文件，创建聚焦的提交；
普通推送成功后，把真实提交哈希、目标分支和推送状态补回变更记录。

调用示例：

text 复制代码

$aaaaa-git-delivery

请交付本次"欢迎语管理"后端改动。
目标仓库：D:\IDEA\aaaaa-webapi
目标分支：feature/welcome-message

请按 Git 交付流程检查本次任务相关 diff、更新开发变更记录，
仅提交本次任务文件并推送。遇到无关改动、冲突、敏感信息或权限问题时停止并说明。

需要特别强调：不要让 AI 自动提交所有未提交文件，也不要默认执行 force push、重写历史、删除分支或不可逆数据库操作。

八、一套可直接复用的日常工作流

最后，把日常使用压缩为下面这条链路：

text 复制代码

新会话
  ↓
调用 $aaaaa-project-context，按任务范围加载上下文
  ↓
需求讨论：输出方案、风险、待确认项
  ↓
需求确认：更新需求文档与变更记录
  ↓
开发实施：拆分 APP / PC / 后端 / 数据库改动
  ↓
联调验证：确认接口、环境、账号、版本与回滚方式
  ↓
调用 $aaaaa-git-delivery：检查、记录、提交、推送
  ↓
更新发布说明与项目进度

九、结语

Codex 真正能提升效率的地方，不只是"帮你写一段代码"，而是让它在每个新会话中，都能快速理解项目当前处于什么阶段、这次改动影响哪些端、哪些事情不能擅自决定，以及交付时应该留下哪些记录。

把规则固化到 AGENTS.md，把事实沉淀到需求、接口、SQL、变更与发布文档，把代码事实交给 Git；再用"项目上下文"和"Git 交付"两个 Skill 固化重复动作。这样，即使项目不断变化、会话不断切换，协作仍然可控、可追溯，也更适合长期演进。

多端项目如何使用 Codex：从需求讨论到 Git 交付的一套协作方法论