Claude Code 寫文檔、README 和代碼註釋：先讓它讀代碼再動筆，指定風格，寫完逐條核對命令能不能跑

本文根據 Claude Code 官方文檔《Common workflows》《Best practices for Claude Code》《How Claude remembers your project》整理，資料核對於 2026-11-05。配圖為本站整理的示意圖，不是介面截圖。本站（bigolab.com）不是 Anthropic 官方網站。

適用於誰

• 項目寫完了，卻沒有 README 或接口文檔，想讓 Claude Code 補上的人；
• 想給老代碼加註釋、加函數說明（JSDoc、Python 的 docstring 之類）的人；
• 擔心 AI 寫出來的文檔裏有「看起來對、其實跑不通」的命令的人。

結論先說

1. 官方有現成的文檔工作流：先讓 Claude 找出缺文檔的代碼，再生成，再補充上下文和示例，最後檢查是否符合項目規範。四步對應官方「Handle documentation」。
2. 告訴它文檔風格。官方的小技巧第一條就是指定風格（JSDoc、docstring 等），其餘兩條是讓它給示例、為公開接口和複雜邏輯寫文檔。
3. 文檔裏最容易出錯的是命令和參數。 官方在最佳實踐裏強調要給 Claude 一個「能判斷對錯」的檢查；寫文檔時，這個檢查就是把文檔裏的命令真的跑一遍。
4. 面向讀者的文檔，和麵向 Claude 的 CLAUDE.md，是兩回事。 README 寫給人，CLAUDE.md 寫 Claude 讀代碼看不出來的東西，別混在一起。
5. 文檔類任務多半是讀多寫少，會話不長，但讀大項目也會佔上下文，按需要分會話。

圖：本站根據 Claude Code 官方文檔：Common workflows 整理的示意圖

第一步：先找出缺文檔的地方

官方的第一步提示詞是這樣寫的：find functions without proper JSDoc comments in the auth module，意思是找出認證模組裏沒有合格 JSDoc 註釋的函數。注意它限定了「某個模組」，而不是整個項目。範圍越小，輸出越好審。

提示詞 1：盤點缺文檔的代碼，先不動手

text
請閱讀 src/auth/ 目錄，列出沒有說明註釋的導出函數和類：
1）按「對外公開 / 內部使用」分成兩組；
2）每項寫出文件名、函數名、你判斷它缺什麼（參數說明、返回值、拋出的錯誤、使用示例）；
3）只做盤點，不要修改任何文件。
最後告訴我，如果只補一部分，你建議先補哪五個，為什麼。

先盤點再寫，是為了讓你決定範圍。一次讓它給整個倉庫補註釋，改動會又多又雜，不好審。

第二步：指定風格，再讓它寫

官方第二步是 add JSDoc comments to the undocumented functions in auth.js。這裏的風格是 JSDoc；換成 Python 就說 docstring，並說明用哪種格式。你的團隊有約定的話，直接告訴它。

提示詞 2：按指定風格補註釋

text
請給 src/auth/ 裏公開的函數補註釋，要求：
1）風格：【JSDoc / Python docstring（Google 風格）/ 其他】，與項目裏已有的註釋保持一致，可參考 @src/auth/login.ts；
2）只寫「為什麼這樣做、參數的含義、會拋什麼錯」，不要複述代碼本身在做什麼；
3）每個公開函數給一個簡短的使用示例；
4）不要改動任何代碼邏輯，只改註釋，改完用 git diff 給我看改動範圍。

第 2 條是經驗之談：好的註釋寫「為什麼」。機械地把代碼翻譯成中文，只會讓文件變長，沒有資訊量。這是本站的建議，不是官方原話。

第三步：寫 README，讓它依據代碼，不要憑印象

README 的風險在於：Claude 可能把常見項目的寫法搬過來，寫出你的項目里根本沒有的命令。官方對「提示詞要具體」的建議是點名文件、說明期望結果，你可以用 @ 引用文件，讓它依據真實的配置來寫。

提示詞 3：依據真實文件寫 README

text
請為這個項目寫 README.md（簡體中文）。只能依據下面這些文件裏真實存在的內容來寫：
@package.json @.env.example @docker-compose.yml @src/index.ts
結構：1）一句話說明項目做什麼；2）環境要求（版本號以配置文件為準）；3）安裝與啟動的命令；4）環境變量表（只列變量名和用途，不要寫任何真實的值）；5）如何運行測試；6）目錄結構簡介。
規則：配置文件裏查不到的資訊，不要猜，在 README 裏用「待補充」標出，並在最後單獨列給我。

「查不到就標待補充」這一條很關鍵，它把「編造」變成了「留白」，你一眼就能看到哪些要自己補。環境變量一律只寫名字，真實的密鑰不要出現在任何文檔裏，涉及密鑰的整體原則見 /guides/ai-coding-security-secrets-permissions。

第四步：核對，這是文檔能不能用的關鍵

官方在最佳實踐裏說，Claude 看起來做完了，不等於做對了；給它一個會返回通過或失敗的檢查，它才能自己閉環。文檔的檢查是：按文檔從頭做一遍。

提示詞 4：照着 README 實際走一遍

text
請嚴格按 README.md 的步驟，在一個乾淨的臨時目錄裏複製項目，並逐條執行裏面的安裝、啟動、測試命令。
對每一條命令記錄：命令原文、是否成功、失敗時的報錯原文。
不要為了讓它成功而偷偷改命令；發現文檔與實際不符，先列出差異，等我確認後再修改 README。
注意：不要執行任何會刪除文件、推送代碼或連接線上服務的命令。

官方的權限和沙箱機制也適合這種場景，見 /guides/claude-code-permission-modes。如果核對時發現 README 和實際不符，再回到第三步改，不要讓它「順手」把代碼改成和文檔一樣。

圖：本站根據官方文檔整理的示意圖

和 CLAUDE.md 的分工

官方說明，運行 /init 會讓 Claude 分析代碼庫，生成一份包含構建命令、測試說明和項目約定的 CLAUDE.md；已經有的話它會提出改進建議而不是直接覆蓋。這份文件是給 Claude 在以後每個會話裏讀的，寫「讀代碼看不出來」的資訊。README 則是給新同事或使用者看的。兩份可以引用同一批命令，但別互相複製粘貼，否則會過期不一致。CLAUDE.md 的寫法見 /guides/claude-md-agents-md，老項目接手見 /guides/claude-code-takeover-old-project-claude-md。

常見問題

Q：文檔風格不統一怎麼辦？

把一篇你滿意的文檔作為樣例，用 @ 引用，要求「照這個風格寫」。官方的提示詞建議就是給它參照物。

Q：不是代碼的筆記、說明文件夾也能用嗎？

可以。官方說 Claude Code 在任何目錄裏都能工作，包括放筆記或 Markdown 文檔的文件夾，可以搜尋、編輯和重新整理內容。

Q：它改了不該改的代碼怎麼辦？

先在提示詞裏寫「只改註釋」，再用 git diff 看改動；真出了問題，可以用官方的回退功能，見 /guides/claude-code-rewind-checkpoints-undo。

訂閱和額度

補文檔需要讀很多文件，在大倉庫裏會用掉不少額度，建議按模組分開做。訂閱選擇見 /chongzhi/claude-code，價格和額度以官方頁面當前顯示為準。

相關教學

• /guides/claude-code-getting-started：Claude Code 入門
• /guides/claude-code-best-practices：最佳實踐
• /guides/claude-code-python-automation-script-beginner：寫自動化腳本

參考資料

• Claude Code 文檔：Common workflows — https://code.claude.com/docs/en/common-workflows
• Claude Code 文檔：Best practices for Claude Code — https://code.claude.com/docs/en/best-practices
• Claude Code 文檔：How Claude remembers your project — https://code.claude.com/docs/en/memory