1. 项目收尾最烦的不是写代码，是写文档
代码提交完那一刻，很多人的第一反应是“终于结束了”，结果打开项目根目录一看，README 还是三个月前初始化时自动生成的那几行，API 文档停留在“待补充”，CHANGELOG 干脆没有。新人拉下代码第一句问的就是“这个项目怎么跑”，你只能口头讲一遍，讲完发现对方还是没记住。
ClaudeCode 在文档生成这件事上有一个天然优势：它能直接读取你项目里的真实代码，而不是靠你口述去猜。你让它生成 README，它会去扫 package.json、目录结构、路由文件、环境变量示例；你让它生成 API 文档，它会去读后端路由和控制器；你让它补 JSDoc，它会逐个函数看参数和返回值。生成出来的内容和你代码是对得上的，不是那种“看起来很像但字段名全错”的模板货。
这篇聚焦四类产物：README、API 文档、JSDoc 注释、CHANGELOG。适合已经装好 ClaudeCode、但还没把文档流程跑通的新手。我会先给一份可复制的 settings.json 配置骨架，把请求通道统一走 TaoToken，然后带你完整跑一次“从代码到文档”的验证动作，最后把常见的报错和坑列出来。你跟着做，本地就能闭环。
2. 前置准备：用 TaoToken 统一 Key 与 API 通道
ClaudeCode 默认会去读环境变量里的 API Key 和 Base URL。如果你之前用过别的通道，配置散落在 shell 的 export 里，换项目就乱。我的做法是把它收进 ClaudeCode 的 settings.json，让 Key 和地址都从一处来。
TaoToken 在这里的角色是统一入口：一个 Key 同时给模型对话、Coding Plan、API 调用用，地址固定，不用每个工具单独配一遍。官网在 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 根地址是 https://taotoken.net/api ，注意 API 地址后面不加 UTM 参数，直接写就行。
你需要先拿到 Key。进控制台创建：https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，然后在 API Keys 页面生成一个：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。生成后复制那串 sk- 开头的字符串，只显示一次，先存到密码管理器里。
如果你还没装 ClaudeCode，官方文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，里面有各平台的安装命令。装完之后先别急着生成文档，把配置写对，否则后面每一步都会卡在鉴权上。
3. 可复制配置：settings.json 骨架与目录约定
ClaudeCode 的配置文件放在用户目录下的 .claude/settings.json，Windows 是 C:\Users\你的用户名.claude\settings.json，macOS 和 Linux 是 ~/.claude/settings.json。如果目录不存在就手动建一个。
下面这份骨架可以直接抄，把 sk-你的Key 替换成上一步拿到的真实 Key：
{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_AUTH_TOKEN": "sk-你的Key", "ANTHROPIC_MODEL": "claude-sonnet-4-20250514" }, "permissions": { "allow": [ "Read", "Write", "Edit", "Bash(git log:*)", "Bash(git diff:*)" ], "deny": [] }, "includeCoAuthoredBy": false }几个点解释一下。ANTHROPIC_BASE_URL 指向 TaoToken 的 API 根地址，不要带结尾斜杠，也不要加任何查询参数。ANTHROPIC_AUTH_TOKEN 就是你的 Key。ANTHROPIC_MODEL 按你实际能用的模型名填，如果控制台里模型列表和这里不一致，以控制台为准。
permissions.allow 里我放开了 Read、Write、Edit 和两条 git 只读命令。生成文档需要读代码、写文件，CHANGELOG 需要读 git log，所以这几条是必须的。deny 留空，但建议你不要在生产仓库里放开 Bash 的写操作，文档生成阶段用不到。
配置写完后，在项目根目录建一个 CLAUDE.md，把文档规范写进去，这样每次生成都会遵守同一套约定：
## 文档规范 - README 使用中文，包含项目简介、功能特性、技术栈、快速开始、目录结构、环境变量、部署、协议 - API 文档输出到 docs/API.md，RESTful 风格，含路径、方法、参数、响应示例、错误码 - 所有 src 下的工具函数必须有中文 JSDoc，含 @param、@returns、@example - CHANGELOG 遵循 Keep a Changelog，分类为新增、修复、变更、移除 - 每次新增功能后同步更新 README 功能列表CLAUDE.md 放在项目根目录，ClaudeCode 启动时会自动读取。这一步做完，后面你甚至不用每次把要求打全，它会按约定来。
4. 四类文档的生成动作与验证结果
配置就绪后，进入项目根目录，执行 claude 启动。下面按四类产物分别给提示词和预期结果。
4.1 生成 README
在对话里输入：
扫描整个项目，生成专业的 README.md，包含：项目简介、功能特性、技术栈、快速开始（安装、配置、运行）、项目结构说明、环境变量说明、部署指南、开源协议。技术栈用表格呈现。它会先读 package.json、目录树、.env.example，然后写文件。生成完你打开 README.md 检查三处：技术栈表格里的版本号是否和 package.json 一致；快速开始里的命令是否和你实际脚本一致；环境变量表是否覆盖了 .env.example 里的所有键。这三处对上了，说明它是真读了代码，不是套模板。
4.2 生成 API 文档
为项目中所有后端接口生成 API 文档，RESTful 风格，包含接口路径、请求方法、请求参数、响应示例、错误码说明，输出为 docs/API.md。如果你的路由分散在多个文件，它会逐个读。生成后重点核对请求参数的字段名和类型，这是最容易出错的地方。你可以随手挑一个接口，对照控制器里的校验逻辑看字段是否一致。
4.3 补 JSDoc 注释
给 src/utils/ 目录下所有文件添加中文 JSDoc 注释，包括文件顶部功能说明、每个函数的 @param 和 @returns、关键逻辑行内注释。不要改动函数逻辑。最后一句“不要改动函数逻辑”很重要，不加的话它有时会顺手重构。生成后跑一次 git diff，确认只有注释新增，没有逻辑变更。这一步是安全底线。
4.4 生成 CHANGELOG
根据最近 10 次 Git 提交记录，生成 CHANGELOG.md，遵循 Keep a Changelog 格式，分类为新增、修复、变更、移除。它需要读 git log，所以 permissions 里那两条 git 只读命令要放开。生成后检查分类是否合理，有些提交信息写得含糊，它可能归错类，手动挪一下就行。
四类都跑完后，你的项目根目录应该多出 README.md、CHANGELOG.md，docs 目录下多出 API.md，src/utils 下的文件多了注释块。这就是一次完整的文档闭环。
5. 本篇常见错排查
报 401 或鉴权失败：九成是 Key 写错或过期。回 API Keys 页面重新生成一个，注意复制时不要带空格。另外确认 settings.json 里字段名是 ANTHROPIC_AUTH_TOKEN，不是 ANTHROPIC_API_KEY，这两个不一样。
报连接超时或地址错误：检查 ANTHROPIC_BASE_URL 是不是写成了 https://taotoken.net/api/ ，结尾斜杠要去掉。也不要在这条地址后面拼任何查询参数。
生成的内容和代码对不上：通常是它没读到关键文件。确认你在项目根目录启动的 claude，而不是在某个子目录。如果项目很大，可以在提示词里指明入口文件，比如“先读 src/router/index.ts 再生成 API 文档”。
JSDoc 生成时改动了逻辑：提示词里必须加“不要改动函数逻辑”，生成后养成 git diff 的习惯。发现逻辑被改就 git checkout 回滚，重新生成并强调只加注释。
CHANGELOG 读不到 git 记录：确认 permissions.allow 里有 Bash(git log:) 和 Bash(git diff:)，并且当前目录是 git 仓库。如果提交信息是英文，生成的中文 CHANGELOG 可能分类不准，可以在 CLAUDE.md 里约定提交信息格式。
文档生成到一半中断：长文档生成时如果网络抖动会断。可以拆成多次，先生成 README，再单独生成 API 文档，不要一次让它写四份。另外确认你的 Coding Plan 或 API 额度还够，额度不足也会中断。
6. 把文档流程固定下来
文档这件事，靠自觉是坚持不下去的，得把它变成流程的一部分。我的做法是在 CLAUDE.md 里写死规范，每次功能合并前跑一次“对比当前代码和 README.md，列出不一致的地方”，让它先检查再更新。这样文档不会和代码脱节太久。
如果你只是偶尔生成文档，用模型对话就够了：https://taotoken.net/model-chat?utm_source=taotoken_aicg_blog_end&utm_content=model-chat&utm_campaign=rewrite 。如果你打算把文档生成接进日常开发，甚至让 Agent 在提交前自动补注释和 CHANGELOG，那 Coding Plan 更合适：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 。接入过程中遇到鉴权或配置问题，直接翻接入文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，里面把 Base URL 和 Key 的用法写得很清楚。
下一篇讲 Git 提交记录，到时候你会发现，提交信息写得好，CHANGELOG 生成的质量直接上一个台阶。
