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