注册
ChatGPTCodex

用 Codex 写文档和注释：给它改动的来源、只改需要改的页面、跑文档检查，附 4 段提示词

代码改了，README 和文档没人更新？官方用例的做法是：把变更的代码、PR、发布说明交给 Codex，让它先找出受影响的文档，只改需要改的部分，保持原有结构和术语，再跑文档检查。本文给 4 段提示词和核对清单。

NNathaniel bigo··原创首发·AI 辅助撰写
6 分钟读完
资料核对于 2026-11-05 · 依据官方文档与公开资料整理 Plus 账号
本文根据 Codex 官方用例《Keep documentation up-to-date》和《Prompting》整理，资料核对于 2026-11-05。配图为本站整理的示意图，不是软件截图。本站（bigolab.com）不是 OpenAI 官方网站。安装与配置见 /guides/codex-getting-started，本文只讲怎么让它写文档。

适用于谁

  • 项目的 README、使用说明、迁移说明长期落后于代码的人；
  • 接手别人的项目，想补一份能让新人看懂的文档的人；
  • 以前让 AI 写文档，结果整篇重写、术语全变、还编出了不存在的功能的人。

结论先说

  1. 从变更出发写文档。 官方用例说，文档最容易跟上代码的时候，是和源码改动同时更新，而不是几周以后。把改动的文件、PR、提交或 issue 交给它。
  2. 让它先找受影响的文档：搜功能名、配置项、命令和示例，再动笔。
  3. 只改最小的范围。 保持现有的页面结构、术语、交叉链接，能用一个小节解决的，不要整篇重写。
  4. 每条面向用户的说法都要有依据。 官方建议让它在最后总结“改了什么、验证了什么、哪些说法没法从可信来源证明”。
  5. 公开文档要划边界：未发布的计划、客户私有信息、内部信息不能写进去，要在提示词里明说。

用 Codex 更新文档的四步：交代变更来源、找出受影响文档、只改最小范围、跑检查并说明依据

图：本站根据 官方用例《Keep documentation up-to-date》 整理的示意图

一、给它什么材料

官方列出了几种来源以及它们的作用：

  • 变更的代码和测试：让它根据真实行为写，而不是凭印象；
  • 公开的发布说明或产品文档：帮它对齐对外的术语、功能是否已经上线；
  • PR 或 issue 的上下文：解释为什么改，以及哪些行为用户能感觉到；
  • 本地的文档检查命令：给它一个“做完”的标准，比如格式检查、链接检查、文档构建。

在命令行里，可以用 @ 引用要改的文档文件，也可以直接说明分支或提交。官方《Prompting》的示例也是先指定文档文件，再要求验证所有链接有效。

二、4 段可以直接复制的提示词

方括号里是要你自己填的内容。

1. 根据代码改动更新文档

请根据下面的来源更新 [功能名称] 的文档：
- 这次改动涉及的源码：[分支 / 提交 / 文件]
- 现有文档里提到相关行为的页面
- 我提供的 issue / PR / 发布说明：[链接或粘贴内容]
然后：
1. 先判断哪些改动是用户能感觉到的；
2. 只更新需要改的文档，保持现有的结构、术语和交叉链接；
3. 不要写未发布的计划和内部信息；
4. 运行适合这次改动的文档检查。
最后总结：改了什么、验证了什么、哪些说法你没法从可信来源证明。

2. 为没有文档的项目写 README

请为这个项目写一份 README，读者是第一次打开这个仓库的开发者。
先阅读代码和配置，不要凭空猜测。内容包括：这个项目做什么、环境要求、安装、运行、测试、目录结构、常见问题。
所有命令都要来自项目里的 package.json / Makefile / 脚本等真实文件，并在可能的情况下亲自运行确认能用。
没有把握的地方写“待确认”，列在最后给我。

3. 补代码注释（不改逻辑）

请给 @[文件路径] 补充注释，要求：
- 只加注释，不改任何代码逻辑，改完让我能用 diff 确认没有代码变化；
- 注释说明“为什么这样做”，不要把代码逐行翻译成文字；
- 公开的函数写清参数、返回值和可能的异常；
- 已有的注释不要无故删除或改写；
- 看不懂的地方不要猜，列出来问我。

4. 把文档要求写进 AGENTS.md

请把下面几条文档约定整理后加到项目的 AGENTS.md：
- 用户可见行为变化时，检查文档、示例和变更日志是否需要更新；
- 公开文档只写公开信息，或者在本仓库里能看到的行为；
- 保持现有术语和 frontmatter；
- 最终交付前运行文档格式和构建检查。
先给我看拟加入的内容，确认后再写入。

第 4 段对应官方用例里“让流程可重复”的建议：把仓库范围的约定写进 AGENTS.md，它每次工作都会读，见 /guides/codex-agents-md-how-it-reads。如果步骤更复杂，官方建议做成技能，见 /guides/codex-skills-how-to-use-install。

三、写完之后怎么核对

Codex 写完文档后怎么核对：命令跑不通、描述了不存在的功能、整页被重写、泄露内部信息、注释改了代码

图：本站根据 官方用例《Keep documentation up-to-date》 整理的示意图

  • 命令逐条自己跑一遍：文档里的安装、运行命令是最容易出错的地方；
  • 看 diff 范围：只该改的页面被改了吗？整页被重写、术语被换掉，要求撤销；
  • 功能是否真实存在：对不上代码或发布说明的描述，要求它说明依据，说不出来就删；
  • 有没有内部信息：内部地址、客户名、未发布计划、密钥，一律不能进公开文档；
  • 加注释的任务，用 diff 确认没有代码变化；
  • 读渲染后的页面：官方《Prompting》的做法是改完自己读一遍实际显示的页面。

四、想让它定期更新

官方用例提到，可以把这个流程做成定时任务，例如每周让 Codex 拉取最近合并的 PR，并据此更新文档。是否可用、怎么配置取决于你的 Codex 版本，以官方当前文档为准。定时自动更新的内容，仍然建议你在合并之前看一遍。

写 README 和技术文档的通用提示词思路，也可以参考 ChatGPT 版的 /guides/chatgpt-write-readme-technical-docs；那篇是在聊天里写，本文是在代码仓库里让 Codex 直接改文件。

常见问题

Q：它写的文档风格和我们原来的不一样？

在提示词里指定一篇现有文档作为风格参照，并要求“保持现有结构和术语”；常用约定写进 AGENTS.md。

Q：文档里的链接是它编的怎么办？

明确要求“只使用我提供的链接或仓库里真实存在的路径”，并让它运行链接检查；检查不了的，你手动点开。

Q：用得多会不会很费额度？

文档类任务一般不重，但整个仓库扫描会消耗更多。Codex 随 ChatGPT 套餐提供，额度以官方页面为准，需要更多额度可以看看 /chongzhi/chatgpt-plus 里的说明。

参考资料

  • Codex 官方用例：Keep documentation up-to-date — https://learn.chatgpt.com/use-cases/update-documentation
  • Codex 官方文档：Prompting — https://learn.chatgpt.com/docs/prompting

Nathaniel 的更多内容

  1. 01

    Claude Code 在 Windows 上的常见坑：Git Bash 还是 PowerShell、路径反斜杠、假报错、WSL 怎么选

    Windows 上用 Claude Code，装好之后最容易踩的是：用哪个 shell、路径写法不一致、grep 没匹配就报错、钩子没生效、WSL 和原生怎么选。本文逐条按官方文档整理原因和处理办法，附三段提示词和一张对照表。

    Claude0
  2. 02

    Claude Code Hooks 实战「提交前自动跑测试」：PreToolUse 拦住 git commit，测试不过就退出码 2，附 Windows 注意点

    只写一个完整例子：让 Claude Code 每次要执行 git commit 之前，先自动跑项目测试，没通过就拦下并把输出交给它修。本文按官方 Hooks 文档给出脚本、settings.json 配置、测试方法、排错和 Windows 的两处坑。

    Claude0
  3. 03

    Claude Code 自定义斜杠命令与 Skill 实战：从零写一个「生成更新日志」的 /release-notes，含传参、预执行命令和调试

    概念看过了，还是不知道从哪下手？本文按 Claude Code 官方「Extend Claude with skills」写一个完整可用的例子：用 /release-notes 根据 git 记录生成更新日志，覆盖目录、frontmatter、传参、预执行命令、预授权和调试。

    Claude0
  4. 04

    Claude Code 部署网站：先写 Dockerfile 和 compose 在本机跑通，再按清单上云服务器，别让它直接改线上

    想让 Claude Code 帮你把网站部署到云服务器。本文只写通用做法，按 Docker 官方文档讲：让它写 Dockerfile、.dockerignore 和 compose，在本机跑通，端口和数据卷怎么设，再给出上线清单，并说明为什么不要让它直接动线上机器。

    Claude0
  5. 05

    Claude Code 写爬虫与数据清洗：先查 robots.txt 和网站条款，控制频率，原始数据留一份再清洗

    想让 Claude Code 写爬虫抓数据再清洗。本文先讲合规：robots.txt 不是授权也不是安全措施、网站条款要自己读；再讲怎么用 Python 标准库检查规则、小样本先试、保存原始数据，以及用 pandas 清洗，附四段提示词。

    Claude0
  6. 06

    Claude Code 写 Chrome 扩展：按 Manifest V3 起步，加载未打包的扩展，改了哪些文件要重新加载

    想让 Claude Code 帮你写一个 Chrome 扩展。本文按 Chrome 官方扩展文档讲：manifest.json 的最小写法、在 chrome://extensions 加载未打包的扩展、哪些改动要刷新、怎么看控制台和报错，再给四段提示词，以及权限要尽量少。

    Claude0

同产品的其他教程

  1. 01

    OpenAI API 的 token 怎么算、怎么估算费用：input_tokens 计数接口、tiktoken 和隐藏的输出 token

    发请求前想知道会用多少 token？官方有 Responses 的 input_tokens 计数接口，能把文字、图片、文件、工具定义一起算准；本地 tiktoken 只适合纯文本。本文给 Python 和 Node 示例，讲输出 token 为什么可能比看到的多，以及怎么估算费用。

    ChatGPT0
  2. 02

    OpenAI API Node.js / TypeScript 快速上手：npm install openai、example.mjs 第一个请求，到流式、函数调用、联网搜索

    用 Node.js 调 OpenAI API：设置 OPENAI_API_KEY 环境变量，npm install openai，新建 example.mjs，用 client.responses.create 发出第一个请求。并列出图片、文件、流式、函数调用、联网搜索和错误捕获的 Node 写法。

    ChatGPT0
  3. 03

    OpenAI API 用量层级（usage tiers）与速率限制怎么提升：Free、Build、Launch、Grow 和后台 Limits 页

    OpenAI API 的限速不是固定的：官方按累计购买额度把组织分成 Free、Build、Launch、Grow 四个层级，达到门槛自动升级。本文讲 RPM、TPM 等指标、怎么在后台查自己的限额、响应头怎么读、花费上限和限速的区别，以及怎么让限额变得够用。

    ChatGPT0
  4. 04

    OpenAI API 报错 400、401、403、404、429、500、503 怎么排查：按官方错误码页逐个看原因和解决办法

    调用 OpenAI API 返回 400、401、403、404、429、500、503，各自什么意思？本文按官方 Error codes 页，每个状态码一节，写清官方给的原因和解决办法，并说明 404 在官方页面里的位置、429 的六种情形，附 Python 和 Node 的错误捕获写法。

    ChatGPT0
  5. 05

    OpenAI Realtime API 是什么：语音到语音会话、WebRTC 与 WebSocket、临时密钥和事件机制

    Realtime API 让模型直接处理音频，做可以随时打断的语音助手。本文按官方文档讲它是什么、什么时候用、浏览器接入的流程、session 与事件、可用声音、60 分钟会话上限、安全标识，以及它和转写、文字转语音的分工。

    ChatGPT0
  6. 06

    OpenAI 图像生成 API 怎么用：gpt-image 系列、images.generate 与 Responses 工具、尺寸质量和遮罩编辑

    用 OpenAI API 生成或编辑图片，有 Image API 和 Responses 里的 image_generation 工具两条路。本文按官方文档给 Python 和 Node 示例，讲 gpt-image 模型选择、尺寸质量格式参数、遮罩编辑、被拦截时的错误处理，以及需要组织验证的提醒。

    ChatGPT0

0 条评论

登录 后参与评论

还没有评论，来抢沙发～