程序员小枫同学

Appearance

用 Codex 更新文档并准备发布 ​

嘿，朋友！今天聊聊用 Codex 搞文档更新和发布这件事。

我写了好几年技术文档，踩过的坑比写过的 commit 还多。最让我记忆犹新的一次：README 里的启动命令写的是 npm run dev，但 package.json 里早就改成了 npm run start:dev。结果新同事 clone 下来折腾了半小时，最后在群里弱弱地问了一句"是我环境有问题吗"。从那以后我就认准一个道理——文档的质量，取决于它跟真实代码之间的一致性，文笔反而是次要的。

这一章，咱们就来搭一套"代码事实 → 文档修改 → 渲染验证 → 发布检查"的闭环，让每次文档更新都靠谱。

第一步：定义读者要完成的任务 ​

模糊的目标比如"完善 README"，Codex 拿到这种提示词也只能瞎猜。

给它一个可执行的目标：

text
更新 README 的本地启动章节，让第一次克隆仓库的开发者能在 macOS 和 Linux 完成安装、配置、启动和健康检查。

必须使用仓库当前 package.json、环境变量示例和启动脚本。保留现有标题锚点和链接。不要写生产密钥，不要修改代码。

说白了就是交代清楚：谁在看、从哪开始、做到哪算完成、哪些公开 URL 不能动。

第二步：让 Codex 先核对事实 ​

我以前有个坏习惯：上来就让 AI 改文档。结果它经常"脑补"出看起来很对、其实跟代码对不上的命令和参数。后来我学乖了——先核对，再动手。

text
先不要编辑。把目标文档中的命令、路径、环境变量、版本和 URL 与当前代码、配置、CI 和部署文件逐项核对。

输出表格：文档原文、代码证据、是否一致、建议修改。无法运行验证的内容单独标记。

对于外部产品的行为、版本、价格或者参数，一定要用最新的官方文档或发布说明做依据。社区文章适合帮你发现话题，但别拿它当事实来源——我就因为参考一篇过时的第三方教程，把 API 端点写错了，读者照着调了半天都是 404。

第三步：按用户流程重写 ​

实操类文档，我现在的习惯是按这个顺序来：

  1. 适用人群和完成结果；
  2. 前置条件；
  3. 可复制步骤；
  4. 每一步预期现象；
  5. 验证方法；
  6. 常见错误；
  7. 下一步和相关链接；
  8. 版本或核验日期。

关键原则：把命令放在前面，把背景故事往后放。 读者是来解决问题的，开头三大段项目介绍只会让他们先去找别的教程。我刚开始写博客的时候就犯过这个毛病，花五百字解释为什么要用某个工具，真正的 npm install 藏在文章后半段——后来自己回头看都嫌啰嗦。

第四步：保护精确内容 ​

文档里有好多东西是不能被 AI "润色"的。你让它把 docker-compose up -d 改得更"顺口"，它可能给你写成 启动 Docker 容器——然后读者就不知道到底该敲什么了。

任务里要明确声明：

text
以下内容必须保持精确，不做语言润色：
- 命令和参数；
- 文件路径和环境变量名；
- API 路由、Header 和配置字段；
- 错误文本；
- 已批准业务术语和品牌名称。

Codex 可以帮你重写解释部分，但不能为了读起来顺嘴去改动那些可搜索的技术关键词。读者复制粘贴跑不通，比一段生硬的英文难受多了。

第五步：运行文档验证 ​

写完文档不验证就发布，跟写完代码不跑测试就上线差不多。根据你的项目，至少跑一下：

bash
npm run docs:build
git diff --check

另外这几个点我也习惯逐项过一遍：

  • 页面能不能正常渲染；
  • 内部链接、外部链接和锚点有没有断的；
  • 代码块的语言标注对不对，复制出来能不能直接跑；
  • 导航、侧边栏、搜索和 sitemap 有没有漏；
  • canonical、Base 和静态资源路径配对了没；
  • 移动端表格和长代码有没有溢出；
  • 新页面能不能从相关入口找得到。

有个心理准备：构建成功只代表语法和打包基本正常，链接指向对不对、内容事实准不准，构建工具不管这些。 我有一回 npm run docs:build 绿得发亮，上线才发现三个内部链接全是 404——构建日志里一个字都没提。

第六步：做敏感信息检查 ​

这是血的教训换来的。有一次我写教程截图时忘了打码，把 .env 里的数据库连接串暴露了，还好读者私信提醒我才紧急处理。从那以后，每次发布前我至少搜这几类东西：

  • sk-、token、password、cookie、authorization；
  • 真实邮箱、手机号、账号和内部域名；
  • .env、认证文件和本机绝对私有路径；
  • 用户数据、订单、日志和截图元信息。

用明显一看就是占位符的东西代替：

text
YOUR_API_KEY
https://api.example.com/v1
user@example.com

千万别用那种看起来很像真实凭证的随机长字符串当示例——读者会当真，搜索引擎也会把它当真实密钥标记。

第七步：写发布说明 ​

发布说明的核心是回答用户真正关心的问题：

  • 新增或修复了什么；
  • 谁会受影响；
  • 是否需要迁移或重新配置；
  • 兼容性和已知限制；
  • 怎样验证升级成功；
  • 出现问题怎样回退。

Git 提交列表照抄过来那不叫发布说明，那是偷懒。用户想知道的是"这个版本对我有什么影响"，不是"开发者这周 commit 了哪些东西"。

第八步：发布动作和内容修改分开 ​

文档改好了、验证过了，不代表它已经发出去。按下发布按钮之前，我习惯再确认一轮：

  • 正确仓库、分支和远程；
  • staged diff 范围；
  • CI 和部署工作流；
  • 域名、Base 和环境变量；
  • 是否需要人工审批；
  • 线上验证 URL。

只有用户明确让你提交、推送或部署的时候才动手。部署完了也别急着关页面——去线上点开实际 URL 看看渲染效果、资源哈希对不对、Pages 或平台状态正不正常。本地构建没问题、线上挂了的情况，我也遇到过。

常见失败 ​

文档比代码更"理想" ​

命令和行为必须来自当前实现，不能来自你的美好愿望。计划中的功能要明确标出来，别把"将来会支持"写成"已支持"——读者会当真。

改路径毁了搜索流量 ​

已经存在一段时间的公开 URL，尽量保留。如果确实需要重命名，记得同步更新导航、内链、sitemap、llms.txt，有条件的话做个兼容跳转或重定向。

只做语法检查就收工 ​

构建通过只是第一步。打开渲染页面、复制命令实际跑一遍、在手机上看看排版、检查线上地址能不能访问——这些才是真正防翻车的环节。

把内部笔记直接当教程发 ​

公开教程需要事实核验、示例验证、敏感信息清理，还要站在读者视角重新组织内容。内部笔记是写给自己和同事看的，省掉的上下文太多，直接发出去读者会一头雾水。

完成报告模板 ​

text
更新页面：[列表]
事实依据：[代码/运行结果/官方来源]
验证：[构建、链接、页面、命令]
敏感信息检查：[范围与结果]
未验证项：[列表]
发布状态：[未提交/已提交/已推送/已上线]

下一步 ​

基础和项目工作流你已经搞定了。接下来从 AGENTS.md 实战 开始，把这些规则固化到每次任务里，让好习惯自动运转起来。

参考 ​