Codex 應用案例
讓文件保持最新
根據程式碼和其他來源,自動更新文件。
使用 Codex 比對原始碼變更、公開文件、版本說明和 Pull Request 的背景資訊,再針對需要修改的部分草擬文件更新內容,並列出發布前的驗證步驟。
最適合的對象
- 需要隨產品行為頻繁更新的開發者文件、README、操作手冊、範例和遷移說明。
- 負責維護技術產品文件的團隊。
目錄
讓文件保持最新
根據程式碼和其他來源,自動更新文件。
使用 Codex 比對原始碼變更、公開文件、版本說明和 Pull Request 的背景資訊,再針對需要修改的部分草擬文件更新內容,並列出發布前的驗證步驟。
最適合的對象
- 需要隨產品行為頻繁更新的開發者文件、README、操作手冊、範例和遷移說明。
- 負責維護技術產品文件的團隊。
技能與外掛程式
- 如果團隊透過 GitHub 接收錯誤回報,可以查閱議題、Pull Request、留言、審查討論串和未通過的檢查。
| 技能 | 使用理由 |
|---|---|
| GitHub | 如果團隊透過 GitHub 接收錯誤回報,可以查閱議題、Pull Request、留言、審查討論串和未通過的檢查。 |
入門提示詞
簡介
變更原始碼時就一併更新文件,比等幾週後再補寫更容易讓文件反映最新狀況。Codex 可以檢視變更後的程式碼、測試、版本說明、連結的議題,以及 pull request 的上下文,再沿用既有文件結構,針對受影響的內容擬定更新草稿。
這套工作流程適用於撰寫開發者文件、更新 README、草擬變更記錄、撰寫遷移說明或維運手冊,也適用於其他需要隨軟體行為頻繁更新的文件。
使用方式
-
從需要記錄的變更著手。
提供相關分支、pull request、提交、議題或檔案。如果文件會對外公開,請明確告知 Codex,文件中不得包含尚未公開的產品規劃、客戶的非公開資訊,以及僅供內部參考的背景資訊。
-
請 Codex 找出受影響的文件。
請 Codex 先在現有文件中搜尋功能名稱、設定鍵、指令、範例及相關詞彙,再開始撰寫草稿。
-
只更新足以說明變更的部分。
Codex 應保留現有的頁面結構、術語、交叉連結及 frontmatter。如果補上一則明確的說明、一個範例,或更新某個章節就足以說明變更,便應避免大幅改寫。
-
驗證變更。
請 Codex 執行適用於該程式碼庫的格式化與文件檢查,再逐項說明文件中與使用者相關的敘述有何依據。
可提供給 Codex 的資料
| 資料來源 | 用途 |
|---|---|
| 變更後的程式碼與測試 | 讓 Codex 分析程式的實際行為,針對需要更新的文件內容撰寫草稿。 |
| 公開的版本說明或產品文件 | 協助 Codex 沿用對外公布的術語,並準確說明功能的可用範圍與目前狀態。 |
| Pull request 或議題的上下文 | 說明變更的原因,以及哪些行為變化對使用者重要。 |
| 本機文件檢查 | 讓 Codex 在文件發布前有明確的標準可判斷更新是否完成。 |
提供公開版本說明等更多背景資料,可協助 Codex 避免在文件中寫入非公開資訊或尚未公布的更新。
重複使用這套工作流程
若要讓整個程式碼庫遵循同一套規範,可將文件撰寫要求加入 AGENTS.md。例如:
## 文件
- 使用者可見的行為有變更時,請檢查是否需要更新文件、範例或變更記錄。
- 公開文件的內容僅限於已公開的資訊或可從此程式碼庫觀察到的行為。
- 保留既有術語及 frontmatter。
- 最終交付前,請執行文件的格式檢查與建置檢查。如果流程包含更多步驟,可以將它做成一項技能,讓 Codex 日後執行任務時,也能依循相同步驟核對來源、撰寫草稿並驗證內容。詳情請參閱將工作流程儲存為技能。
你也可以在目前的對話中為這套工作流程建立排程任務。例如,請 Codex 每週擷取近期的 GitHub pull requests,並據此更新文件:
相關應用案例
執行程式碼遷移
使用 Codex 釐清舊系統與新技術堆疊的對應關係,分階段完成遷移,並在每次切換前確認新舊系統的行為一致。
建立 Codex 可使用的 CLI
請 Codex 建立一套 CLI,讓它能在任何資料夾中執行 CLI 指令、搭配程式碼庫中的指令碼使用,也能下載檔案。再請它建立配套技能,讓 Codex 日後記得如何使用這套 CLI。
從議題到經過測試的 pull request
將範圍明確的議題交給 Codex,準備好雲端環境,並列出必要的檢查項目。Codex 會交付可供審查的程式碼變更,附上測試、文件,以及每項驗收條件的驗證依據。