README 和脚本说法不一致时，先让 Codex 建一份事实清单

教程定位

这篇教程解决什么问题

多年项目里最麻烦的不是“没有文档”，而是“文档、脚本、CI、部署记录和人的记忆都各说各话”。README 说部署要跑 `npm run deploy:prod`，仓库里却只有 `pnpm release`；老同事说要先手工同步配置，CI 里又显示部署前会自动生成配置；最近一次上线记录写着“临时绕过 smoke test”，但没有说明这是例外还是新常态。

这种时候，不要马上让 Codex “帮我重写部署文档”。在事实没有厘清之前，重写只会把冲突包装成更漂亮的错。更稳的第一步，是让 Codex 对照 README、部署脚本、CI 配置、最近部署记录和团队聊天摘录，建立一份事实清单：哪些说法已经被代码或记录验证，哪些只是过期假设，哪些必须找人确认。

这篇文章的目标很窄：只解决上下文冲突，不进入文档重写阶段。你最终要拿到的是一份可讨论、可复核、可分派的清单，而不是一篇“新版部署指南”。清单里应该写清楚每个判断来自哪里，证据够不够，下一步由谁确认。等事实稳定后，再决定是否更新 README、修脚本、改 CI 或补部署流程。

对技术负责人来说，这个步骤的价值在于降低沟通成本。你不再问团队“到底听谁的”，而是把所有说法放到同一张桌面上：README 的说法是什么，脚本实际做了什么，CI 什么时候运行，最近一次部署到底执行了哪条命令，聊天里哪些是临时处理，哪些像稳定规则。Codex 负责快速翻材料、归类矛盾和生成表格，人负责验证关键事实和做责任判断。

使用场景

什么情况下最适合用这一套

你维护的是一个跑了很多年的内部系统。早期由一个小团队写出来，后来换过几任负责人，部署方式也从手工服务器切到 CI，再切到容器平台。项目还能运行，但很多知识散在不同地方。

某天你需要安排一次版本发布。新人照 README 操作，发现命令跑不通；运维同事说“现在早就不这么发了”；后端同事说“上次我就是按 README 发的，只是加了两个参数”；前端同事提醒“别忘了先生成静态配置”；聊天记录里有人提到“临时跳过健康检查”，但没有后续说明。

此时你面临的不是一个单纯的技术问题，而是一个事实对齐问题。你需要先回答这些问题：

如果你把这个问题直接丢给 Codex，让它“总结一下部署流程”，它很容易把 README 和脚本混在一起，写出一份看似完整但没有证据分层的说明。真正需要它做的是更机械、更克制的工作：逐条抽取说法，逐条找证据，逐条标状态。

这篇教程适合三类场景。第一类是部署、发布、回滚、迁移这类高风险流程，材料互相冲突，不能靠印象操作。第二类是团队准备清理老文档，但还没有足够把握判断哪些内容过期。第三类是新负责人接手项目，需要在不打扰所有人的前提下，先把疑点收拢成可开会讨论的材料。

它不适合直接生成最终操作手册。事实清单不是操作指南，而是操作指南之前的地基。把地基打准，比把文档写得顺更重要。

1. 当前仓库里真实存在的部署入口是什么？
2. README 里的流程哪些仍然有效，哪些已经找不到对应脚本？
3. CI 配置是否已经替代了手工步骤？
4. 最近几次部署实际执行了什么命令，结果如何？
5. 团队聊天里的说法是稳定规则、临时例外，还是个人经验？
6. 继续发布前，哪些问题必须人工确认？

材料准备

开始前先把材料和边界备齐

开始前先把材料按来源整理好。不要把所有内容一股脑贴给 Codex，然后期待它自动知道谁更可信。你要给每个材料标注来源、时间和可信边界。

建议准备五类输入。

第一类是 README 或内部部署文档。保留和部署相关的章节即可，不需要贴完整项目介绍。如果 README 很长，先截取“环境准备、构建、部署、回滚、常见问题”这些部分。

第二类是部署脚本和命令配置。常见位置包括 `package.json`、`Makefile`、`scripts/deploy.sh`、`deploy/`、`ops/`、`Dockerfile`、`compose.yaml`、Helm chart、Terraform、Ansible playbook。这里的重点是实际存在的命令和参数，而不是文档说应该存在什么。

第三类是 CI 配置。比如 `.github/workflows/*.yml`、`.gitlab-ci.yml`、Jenkinsfile、Buildkite pipeline、Drone 配置。CI 经常包含真正的构建、测试、镜像发布、环境选择和审批条件。很多团队口头说“手工部署”，实际生产已经由 CI 控制。

第四类是最近部署记录。可以是发布单、CI run 摘要、部署平台记录、变更日志、终端记录或复盘纪要。不要粘贴真实 token、完整域名、客户信息、内部 IP 或人员隐私。保留时间、环境、命令、结果、失败原因、回滚动作即可。

第五类是团队聊天摘录。聊天只作为线索，不直接当事实。你可以摘出几段关键说法，例如“上次发布要先跑配置生成”“这个 smoke test 先跳过”“生产现在走灰度脚本”。每段都要标注大概时间和角色，但可以使用虚构姓名或角色称呼，例如“后端负责人 A”“运维同事 B”。

准备材料时要做三件事。

第一，脱敏。不要把真实邮箱、手机号、密钥、cookie、Authorization header、生产数据库地址、客户名称写进去。示例里可以用 `deploy_key_example_redacted`、`console.example.test`、`svc_demo_user` 这类占位值。

第二，标时间。README 可能三年前写的，脚本可能上周改过，CI 可能每天运行。Codex 判断冲突时需要时间线，否则容易把旧材料和新材料放在同一层级。

第三，定边界。明确告诉 Codex：这次只做事实清单，不修改仓库，不重写文档，不推送，不执行生产命令。可以读取文件，可以做只读搜索，可以建议本地安全验证，但高风险命令必须先列出来等待人确认。

你可以先建一个临时材料块，结构像这样：

这一步看起来琐碎，但它会直接决定输出质量。材料没有来源，清单就没有证据；材料没有时间，冲突就没有优先级；材料没有边界，Codex 就可能过早给出“应该怎么做”的建议。

材料包：
1. README 部署章节，来源：README.md，最近提交时间未知。
2. 部署脚本摘要，来源：package.json、scripts/deploy.sh，来自当前分支。
3. CI 配置摘要，来源：.github/workflows/release.yml，最近一次修改为 2026-06-18。
4. 最近部署记录，来源：发布单 DEPLOY-2026-06-25，结果为成功。
5. 团队聊天摘录，来源：发布群，2026-06-20 到 2026-06-25。

目标：
只建立事实清单和待确认问题，不重写 README，不执行部署。

实操流程

按这套步骤把工作跑起来

第一步，让 Codex 建立材料索引，不要急着判断对错。

你可以先要求它把输入拆成“来源、时间、主张、涉及对象、证据片段”。例如 README 的主张可能是“生产部署使用 `npm run deploy:prod`”，脚本的主张可能是“当前只有 `pnpm release` 和 `pnpm rollback`”，CI 的主张可能是“推送 tag 后自动构建镜像并部署到 staging”。这些都先记下来，不急着合并。

材料索引的好处是让冲突显形。团队争论时经常把不同层级混在一起：有人说的是本地构建，有人说的是 staging，有人说的是生产，有人说的是回滚。索引阶段先把环境、命令、触发条件拆开，后面的判断才不会串线。

第二步，让 Codex 区分“主张”和“证据”。

README 里的句子是主张，不是证据本身。聊天里的“我上次就是这么发的”也是主张。脚本里实际存在的命令、CI 里实际配置的 job、部署记录里实际出现的命令和结果，才更接近证据。但即使是代码和记录，也要看时间、分支和环境。

你可以要求 Codex 用三个状态分类：

不要让它使用“正确”“错误”这种太硬的词，除非证据非常明确。维护多年项目时，很多“错误文档”其实是曾经正确、后来过期。用“过期假设”比用“错误”更利于团队沟通。

第三步，按部署链路拆事实。

不要把所有事实放进一个大表。部署流程通常至少包含这些环节：环境准备、依赖安装、构建、测试、制品生成、配置注入、发布触发、健康检查、回滚、权限和审批。让 Codex 按环节整理，每个环节都列出文档说法、脚本证据、CI 证据、最近记录和聊天线索。

例如“构建”环节可能是：

这样整理后，结论就比较清楚：当前构建更可能以 `pnpm build` 为准，README 的 `npm run build` 是过期假设。但如果生产部署还保留手工补救路径，就要单独标“待确认”。

第四步，让 Codex 找“冲突点”，不要泛泛总结。

你要的不是“README 与脚本存在不一致”，而是具体冲突：

每个冲突点都要对应一个后续动作：本地查文件、看 CI run、问负责人、查部署平台、补发布单、安排演练。没有后续动作的冲突点，只会增加噪音。

第五步，把“已验证事实”写得可执行但不过界。

已验证事实可以写成这样的粒度：

注意最后一行“限制”。这能防止团队把一个局部事实误用成完整结论。脚本存在，不代表生产就一定使用；CI 配置存在，不代表最近一次发布没有人工绕过；聊天说可以跳过，不代表制度允许跳过。

第六步，把“过期假设”写得温和且可追溯。

过期假设不是为了追责，而是为了减少误用。推荐写法是：

这样的写法既指出 README 不能直接照做，又保留了例外可能。对老项目来说，这种克制非常重要。很多流程不是“新流程完全替代旧流程”，而是“常规发布走新流程，事故处理还保留旧脚本”。事实清单要把这两件事分开。

第七步，把“待确认问题”变成可分派问题。

不要写“部署流程待确认”这种大问题。要写到能分派给具体角色：

每个问题最好附上为什么要问。如果一个问题不影响下一次发布，可以放到后续文档清理；如果影响发布安全，就标高优先级。

第八步，要求 Codex 输出“下一步建议”，但限制在事实确认层面。

这里很容易跑偏。Codex 可能会建议“更新 README”“统一脚本命名”“重构部署流程”。这些建议可能有道理，但不是本篇的目标。你要让它只输出三类下一步：

例如“查最近三次 production release 的 CI run 是否都经过 smoke test”是合格建议；“把 README 改成 CI 流程”还太早。先把事实确认完，再写文档。

第九步，人工复核高风险事实。

事实清单不是让你把判断权交给 Codex。尤其是生产部署、权限、回滚、数据库迁移、客户影响这类事项，必须由人复核。你可以把 Codex 输出当成会议材料：哪些事实已经有证据，哪些冲突需要负责人拍板，哪些过期内容暂时不要传播给新人。

如果要做最小验证，优先选择安全动作：读取配置、查看脚本、检查 CI 历史、看发布单、运行不触发外部变更的 help 或 dry-run 命令。不要为了验证文档直接执行真实部署命令。

第十步，归档清单，但暂不改文档。

完成这一步后，你可以把事实清单发给相关负责人确认，或者带到发布准备会里讨论。确认完成之前，不建议直接替换 README。否则你可能只是把“一个人的旧说法”换成“AI 整理过但没人确认的新说法”。

1. 需要人工确认的问题。
2. 可以安全做的只读验证。
3. 进入文档重写前必须补齐的证据。

• 已验证事实：有至少一个当前文件、配置或记录支持，并且没有明显反证。
• 过期假设：材料里出现过，但当前脚本、CI 或最近记录不支持，或者时间明显早于现行流程。
• 待确认问题：存在冲突、证据不足，或者需要人工权限才能验证。
• README：`npm install && npm run build`
• package.json：只有 `pnpm build`，没有 `npm run build` 特有逻辑
• CI：使用 `pnpm install --frozen-lockfile` 和 `pnpm build`
• 最近部署记录：CI run 成功，未出现本地构建命令
• 聊天：新人提到 README 的 `npm` 命令失败
• README 写 `npm run deploy:prod`，当前 `package.json` 不存在该脚本。
• README 写部署前必须手工上传 `.env.production`，CI 配置显示通过平台变量注入，但无法确认生产变量是否完整。
• 聊天记录说可以跳过 smoke test，CI 配置里 smoke test 是生产部署必需 job，最近一次记录显示跳过发生在 staging。
• 部署记录显示发布使用 tag `v2.8.4`，README 写从 `main` 分支直接发布。
• 请 CI 负责人确认：生产发布是否只能通过 release workflow 触发？
• 请运维确认：平台变量 `APP_CONFIG_SOURCE` 是否已经替代手工上传配置？
• 请后端负责人确认：跳过 smoke test 是否只允许 staging，生产是否禁止？
• 请发布负责人确认：紧急回滚目前使用 `pnpm rollback:prod` 还是平台回滚按钮？

事实 F-01：当前仓库的生产发布脚本名不是 README 中的 deploy:prod。
证据：package.json scripts 中没有 deploy:prod；存在 release:prod，命令调用 scripts/release.mjs --env production。
限制：尚未确认 release:prod 是否仍由生产 CI 使用。

过期假设 A-02：生产部署前需要人工执行 npm run build。
来源：README 部署章节。
判断依据：CI release job 已包含 pnpm build；最近两次部署记录均由 CI 触发，未出现人工 build 记录。
仍需确认：是否存在紧急手工发布路径仍使用 README 流程。

输入示例

可以直接参考的输入材料

下面是一个安全虚构样例。它模拟的是一个内部管理系统 `example-admin`，没有真实公司、邮箱、手机号、密钥或生产地址。

这个样例有意保留冲突：README 仍写 `npm` 和 `deploy:prod`，脚本改成了 `pnpm release:prod`，CI 使用 tag 触发，聊天里出现过“跳过 smoke”的说法。一个好的输出不应该直接宣布“README 全错”，而是逐条标明哪些内容当前没有证据支持，哪些需要确认是否存在例外路径。

目标：
请只建立事实清单和待确认问题列表，不要修改 README，不要改脚本，不要执行部署。

项目背景：
仓库名：example-admin
系统类型：内部管理后台
当前问题：README 的部署流程和现有脚本、CI 配置不一致，团队成员说法不一致。

材料 1：README 部署章节，来源 README.md，最后更新时间未知
生产部署：
1. npm install
2. npm run build
3. npm run deploy:prod
4. 部署后手工打开 /health 页面检查

回滚：
如发布失败，运行 npm run rollback:prod。

材料 2：package.json scripts，来源当前分支 main
{
  "scripts": {
    "build": "pnpm -r build",
    "release:staging": "node scripts/release.mjs --env staging",
    "release:prod": "node scripts/release.mjs --env production",
    "rollback:prod": "node scripts/rollback.mjs --env production",
    "smoke:prod": "node scripts/smoke-check.mjs --env production"
  }
}

材料 3：CI 配置摘要，来源 .github/workflows/release.yml，最近修改 2026-06-18
on:
  push:
    tags:
      - "v*"
jobs:
  release-production:
    if: github.ref_type == 'tag'
    steps:
      - run: corepack enable
      - run: pnpm install --frozen-lockfile
      - run: pnpm build
      - run: pnpm smoke:prod
      - run: pnpm release:prod

材料 4：最近部署记录，来源发布单 DEPLOY-2026-06-25
环境：production
触发方式：推送 tag v2.8.4
结果：成功
记录摘要：
- release workflow 运行成功
- smoke:prod 运行成功
- 未记录人工执行 npm run deploy:prod
- 发布后 10 分钟内错误率无明显上升

材料 5：团队聊天摘录，来源发布群，已脱敏
2026-06-20 运维同事 B：现在生产尽量走 tag，不要本地跑 deploy。
2026-06-22 后端负责人 A：上次 staging 临时跳过了 smoke，因为测试环境依赖挂了，生产不要跳。
2026-06-25 前端同事 C：README 里的 npm deploy 应该是老流程，新人别照那个跑。
2026-06-25 新同事 D：我按 README 找不到 deploy:prod。

请输出：
1. 已验证事实清单
2. 过期假设清单
3. 待确认问题列表
4. 冲突点摘要
5. 进入重写 README 前还缺哪些证据

提示词

可复制使用的提示词

你可以把下面这段直接复制给 Codex，再把方括号替换成自己的材料。

如果 Codex 可以直接读取本地仓库，你可以再补充一段：

这段提示词的关键不在“语气”，而在边界。它把 Codex 限制在事实核对工作里，避免它过早进入建议、重构或发布操作。

你是一个只读事实核对助手。现在项目里的部署文档、脚本、CI 配置、最近部署记录和团队聊天说法不一致。请你不要修改文件，不要重写 README，不要执行部署命令，不要推送，不要安装依赖。你的任务只是建立“事实清单”和“待确认问题列表”。

项目和边界：
- 项目名称：[项目名，可脱敏]
- 仓库路径或材料来源：[本地路径或材料说明]
- 当前要解决的问题：[例如 README 的部署流程和实际脚本不一致]
- 本次输出只用于事实对齐，不进入文档重写阶段。

输入材料：
1. README 或部署文档摘录：
[粘贴相关章节，保留命令、环境、步骤。不要粘贴密钥、真实域名、客户隐私]

2. 当前脚本和配置：
[粘贴 package.json scripts、Makefile、deploy 脚本摘要、Docker/Helm/平台配置摘要]

3. CI/CD 配置：
[粘贴 workflow、pipeline、Jenkinsfile 等关键 job 和 step]

4. 最近部署记录：
[粘贴最近 1 到 3 次发布记录摘要，包括时间、环境、触发方式、命令、结果、失败或回滚信息]

5. 团队聊天摘录：
[粘贴脱敏后的关键说法，标注大概时间和角色。聊天只作为线索，不直接当事实]

请按下面步骤输出：

第一步：建立材料索引。
用表格列出来源、时间、材料类型、主要主张、涉及环节、可信边界。

第二步：抽取冲突点。
逐条列出 README、脚本、CI、部署记录、聊天之间的具体冲突。每个冲突点必须说明冲突发生在哪个环节，例如依赖安装、构建、部署触发、健康检查、回滚、权限审批。

第三步：生成事实清单。
把结论分成三组：
- 已验证事实：有当前文件、配置或最近记录支持，且没有明显反证。
- 过期假设：材料里出现过，但当前脚本、CI 或最近记录不支持，或者明显来自旧流程。
- 待确认问题：证据不足、存在例外路径、需要负责人或平台权限确认。

第四步：给每条结论补证据。
每条结论都要包含：
- 编号
- 结论
- 证据来源
- 反证或限制
- 影响范围
- 建议确认人或确认方式

第五步：限制下一步建议。
只给事实确认层面的下一步，不要开始重写 README，不要设计新流程，不要直接改脚本。可以建议查 CI 历史、查发布单、找负责人确认、运行安全的只读验证。

输出格式：
1. 一段 5 行以内的摘要
2. 材料索引表
3. 冲突点列表
4. 已验证事实表
5. 过期假设表
6. 待确认问题表
7. 进入文档重写前必须补齐的证据

重要要求：
- 不要把聊天记录当成最终事实。
- 不要因为 README 写得完整就默认它正确。
- 不要因为脚本存在就默认生产一定使用它。
- 如果证据只能支持 staging，不要外推到 production。
- 对高风险动作标注“需要人工确认”。
- 所有示例和输出不得包含真实密钥、手机号、邮箱、客户隐私或生产敏感地址。

如果需要读取仓库，请先只做只读检查：查看 README、package.json、部署脚本、CI 配置和最近提交摘要。不要修改任何文件。涉及真实部署、上传、删除、推送、改权限、改配置的命令，一律先列出来等待我确认。

输出样例

AI 应该输出到什么程度

下面是一份理想输出的缩写样例。真实项目中，你可以让 Codex 输出更完整的表格。

这个输出的重点不是格式漂亮，而是每条话都能被追问。比如 F-02 只说“CI 配置包含这些步骤”，没有说“生产一定这样发”；A-01 只说“README 的本地发布命令当前不受脚本支持”，没有说“README 全部无效”；Q-01 明确需要找 CI 负责人，而不是把问题留在空气里。

摘要：
当前材料显示，README 中的 npm 部署流程与当前脚本和 CI 不一致。最近 production 发布记录更支持“推送 tag 后由 release workflow 执行 pnpm build、smoke:prod、release:prod”的流程。聊天里“跳过 smoke”的说法只能确认发生在 staging，不能外推到 production。进入 README 重写前，还需要确认是否存在紧急手工发布路径。

一、材料索引

| 来源 | 时间 | 类型 | 主要主张 | 可信边界 |
| --- | --- | --- | --- | --- |
| README.md 部署章节 | 未知 | 文档 | npm install -> npm run build -> npm run deploy:prod | 时间未知，只能作为历史线索 |
| package.json scripts | 当前分支 | 代码配置 | 存在 release:prod、rollback:prod、smoke:prod，不存在 deploy:prod | 只能证明脚本存在，不证明生产一定使用 |
| release.yml | 2026-06-18 | CI 配置 | tag 触发 production release，执行 pnpm build、smoke:prod、release:prod | 需要结合 CI run 历史确认是否启用 |
| DEPLOY-2026-06-25 | 2026-06-25 | 部署记录 | v2.8.4 由 release workflow 发布成功 | 只能代表最近一次发布 |
| 发布群摘录 | 2026-06-20 到 2026-06-25 | 聊天线索 | 生产尽量走 tag，staging 曾跳过 smoke | 聊天不是最终制度 |

二、冲突点

C-01 部署触发方式冲突：
README 写本地执行 npm run deploy:prod；CI 和最近部署记录显示 production 由 tag 触发 release workflow。

C-02 命令名称冲突：
README 写 deploy:prod；当前 package.json 中没有 deploy:prod，存在 release:prod。

C-03 健康检查冲突：
README 写发布后手工检查 /health；CI 中有 pnpm smoke:prod；聊天提到 staging 曾跳过 smoke，但后端负责人明确说 production 不要跳。

三、已验证事实

| 编号 | 事实 | 证据 | 限制 | 影响 |
| --- | --- | --- | --- | --- |
| F-01 | 当前 package.json 不存在 deploy:prod 脚本 | package.json scripts | 不能排除其他目录有同名脚本 | 新人照 README 会失败 |
| F-02 | 当前 release workflow 包含 pnpm build、pnpm smoke:prod、pnpm release:prod | .github/workflows/release.yml | 需要确认 workflow 是否仍启用 | README 的手工步骤至少不完整 |
| F-03 | 最近一次 production 发布由 tag v2.8.4 触发并成功 | DEPLOY-2026-06-25 | 只覆盖一次记录 | 支持 CI 发布是现行主路径 |

四、过期假设

| 编号 | 假设 | 来源 | 判断依据 | 仍需确认 |
| --- | --- | --- | --- | --- |
| A-01 | 生产部署应本地执行 npm run deploy:prod | README | 当前脚本无 deploy:prod，最近部署记录未出现该命令 | 是否存在紧急手工脚本 |
| A-02 | 发布后主要依赖人工打开 /health | README | CI 已包含 smoke:prod | smoke:prod 是否覆盖 /health |

五、待确认问题

| 编号 | 问题 | 为什么要问 | 建议确认人 | 优先级 |
| --- | --- | --- | --- | --- |
| Q-01 | production 是否只能通过 tag 触发 release workflow？ | 决定 README 是否应保留手工发布路径 | CI 负责人 | 高 |
| Q-02 | 紧急回滚当前使用 rollback:prod 还是平台回滚按钮？ | README 里回滚命令可能仍有效 | 运维负责人 | 高 |
| Q-03 | smoke:prod 是否等价于 README 的 /health 人工检查？ | 决定健康检查说明是否可替换 | 后端负责人 | 中 |

六、进入文档重写前缺少的证据
- 最近 3 次 production release 的 CI run 链接或摘要。
- 是否存在紧急手工发布流程的负责人确认。
- rollback:prod 最近一次成功使用记录或替代方案说明。
- smoke:prod 覆盖范围说明。

人工验收

人要怎么检查和改到可用

拿到 Codex 输出后，不要直接转发成结论。你需要做一次人工检查，把它从“AI 整理稿”变成“团队可讨论稿”。

第一项检查是证据是否足够具体。每个事实都应该能追到来源：文件路径、脚本名、CI job、发布单编号、聊天时间。只写“根据 CI 配置”不够，最好写到 `.github/workflows/release.yml 的 release-production job`。如果 Codex 给了没有来源的判断，要么让它补证据，要么删除。

第二项检查是环境是否混淆。老项目里 staging、preprod、production、灰度、灾备环境经常使用不同流程。聊天里说“可以跳过 smoke”可能只针对 staging；CI 里的 job 可能只在 tag 时运行；README 里的流程可能是本地演示环境。只要环境不清楚，就不能归为已验证事实。

第三项检查是时间线是否合理。最近部署记录通常比三年前 README 更能代表当前流程，但也可能是一次临时绕行。脚本上周新增，也不代表生产已经迁移。你需要看材料的时间关系，把“旧但可能仍有效”和“新但尚未启用”分开。

第四项检查是用词是否利于协作。把“README 是错的”改成“README 中的 deploy:prod 在当前 package.json 未找到对应脚本”。把“某同事说法不对”改成“该说法缺少当前 CI 或部署记录支持”。事实清单是为了对齐，不是为了制造防御情绪。

第五项检查是高风险动作是否被错误下放给 AI。比如“执行一次 release:prod 验证流程”绝对不应该出现在自动执行建议里。更合适的是“查最近 CI run 记录”或“请负责人确认是否允许在 staging dry-run”。所有会改变外部环境、发布制品、修改权限、触发生产流程的动作，都必须人工批准。

第六项检查是待确认问题能否分派。问题要具体到角色和动作。如果清单里写“确认部署流程”，就太大了。改成“请 CI 负责人确认 production 发布是否只能通过 tag 触发 release workflow”，会议上才有人能回答。

第七项检查是是否过早进入文档重写。Codex 可能很积极地附上一版“建议 README”。这时可以先删掉，或放到“后续可做”。在事实尚未确认前，重写文档会让团队误以为结论已经成立。

你可以把最终清单压缩成三页以内：第一页摘要和冲突点，第二页事实与过期假设，第三页待确认问题和下一步。技术负责人要拿它推进沟通，不需要把所有原始材料都贴满。

失败反例

这些失败反例要提前避开

**反例 1：让 Codex 直接重写 README。**

输入是“README 和脚本不一致，帮我更新 README”。这会跳过事实核对。Codex 可能把当前脚本看成唯一真相，把聊天里的例外忽略掉，也可能把 CI 配置里的 staging 步骤误写成 production 流程。结果是文档更顺了，但风险更大。正确做法是先输出事实清单，等负责人确认后再进入文档重写。

**反例 2：把聊天记录当成最终事实。**

团队聊天很有价值，因为它能提示“为什么当时绕过了某个步骤”。但聊天天然有上下文缺口。有人说“先跳过 smoke”，可能是测试环境依赖挂了；有人说“不要本地发”，可能是建议而不是制度；有人说“我上次这么做没问题”，也可能只是一次紧急处理。正确做法是把聊天列为线索，并要求对应脚本、CI、部署记录或负责人确认。

**反例 3：只比较 README 和 package.json。**

很多人看到 README 写 `npm run deploy:prod`，package.json 没有这个脚本，就立刻判定 README 过期。这个判断可能大体正确，但仍然不完整。命令可能在子目录、Makefile、CI 容器镜像或部署平台里；生产也可能早已不从本地 package.json 发起。正确做法是把 CI 配置、部署记录和脚本目录一起纳入对照。

**反例 4：把脚本存在等同于现行流程。**

`release:prod` 存在，不代表生产发布一定走它；`rollback:prod` 存在，不代表事故时允许使用它；`smoke:prod` 存在，不代表它覆盖 README 里的全部人工检查。多年项目里有不少脚本是历史遗留、临时补救或只给特定环境使用。正确做法是给每条脚本结论加限制：它证明了什么，不能证明什么。

**反例 5：输出“建议统一流程”但没有可验证问题。**

“建议统一部署流程、完善文档、加强自动化”听起来正确，却不能推动下一步。技术负责人需要的是今天能问谁、查什么、确认什么。正确输出应该包含具体问题，例如“production 是否只能通过 tag 触发 release workflow”“紧急回滚是否仍使用 rollback:prod”“smoke:prod 是否覆盖 /health 检查”。

主题边界

它和相邻主题的区别

这篇和“接手陌生仓库，第一小时让 Codex 帮你找到路”的差异在于，陌生仓库第一小时关注的是建立入口地图：技术栈、目录、启动方式、测试入口、需求可能涉及的文件。它处理的是“我不知道从哪里开始”。本文处理的是“材料互相冲突，团队说法不一致”，重点不是找入口，而是把不同来源拆成事实、假设和问题。

这篇和“页面报错时，让 Codex 帮你画出路由、组件和接口对应表”的差异在于，页面报错那篇沿着一个 URL 追踪到组件、请求和后端 handler，目标是定位一条运行链路。本文沿着部署流程的多个材料源横向对照，目标是消除上下文冲突。它不要求追到某个 bug，也不进入修复阶段。

本文也不等同于“让 AI 写部署文档”。它刻意停在文档重写之前，只交付事实清单和待确认问题列表。真正的差异点是克制：当 README、脚本、CI 和人的记忆打架时，Codex 先做记录员和核对员，不做流程设计师，也不做最终裁判。这个边界能保护团队不被一份看似完整的新文档带偏。