註冊
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 條評論

登入 後參與評論

還沒有評論，來搶沙發～