*图1：Claude Code生成的项目文档结构示意图，展示代码与文档的映射关系*
先说我的踩坑经历
第一个项目，我直接丢给Claude Code一段代码让它生成文档。结果它给我生成了一份非常漂亮的文档，每个函数都有说明，参数也有注释，甚至还有使用示例。我美滋滋地提交了。第二天测试发现，有个关键函数的参数名我后来改过，但文档里还是旧版本。这不是Claude的问题，是我没
<
p>让它实时读取最新代码。
所以，核心原则：永远让Claude Code基于当前代码库的状态来生成文档。
正确的做法是在项目根目录运行：
“bash`
cd your-project
claude-code
然后对话里输入：
`
请扫描我项目中的所有Python文件，分析函数和类的结构，然后生成完整的API文档，格式为Markdown。
Claude Code会自动读取当前目录的所有文件，分析代码结构，然后输出文档。这样生成的文档不会出现代码和文档版本不一致的问题。
文档生成的三种模式
实际使用下来，我总结出三种文档生成模式，分别对应不同场景：
1. 内联注释模式
这个最简单，就是让Claude Code为已有代码添加注释。
为什么要这么写：很多老项目代码没有注释，新人接手一脸懵。让AI逐个文件加注释，比人工写快10倍。
我常用的提示词：
`
请为src/目录下的所有Python文件添加Google风格的文档字符串。
要求：
- 每个函数都要有Args和Returns
- 类要有Attributes和方法说明
- 不要改变任何代码逻辑
- 复杂的算法步骤要加行内注释
`
实测结果：一个5000行的项目，原本只有20%的代码有注释，用这个提示词处理完后，覆盖率达到95%。唯一的问题是某些AI生成的注释稍微啰嗦了点，但可以接受。
2. 项目级README模式
这个是我用得最多的场景。每个项目都得写README，但写README真的反人类——写简单了说你不专业，写详细了能写一天。
我现在的提示词：
`
基于项目根目录下的所有文件，生成一份完整的英文README.md。
项目类型：FastAPI微服务
包含以下章节：
>
注意：请只写实际存在的功能，不要编造。
`
*图2：Claude Code生成完整README的流程图，从代码分析到最终输出*
这个提示词的关键是最后那句"只写实际存在的功能"。不加这句，AI真的会给你编一个"用户登录功能"出来，实际上你的项目压根儿没这个功能。
3. 架构文档模式
这个比较高级，适合中大型项目。不只是给代码加注释，而是生成架构设计文档。
提示词技巧：
`
请分析整个项目的代码结构，输出一份架构文档。
要求：
- 用Mermaid图表展示模块依赖关系
- 标注数据流向
- 说明核心模块的职责
- 指出可能的性能瓶颈（如果有）
- 每个模块的代码行数统计
`
这里有个坑：Claude Code对大型项目的一次性分析能力有限。超过10万行的项目，建议按模块分批处理。
我遇到过最离谱的是，让Claude分析一个20万行的Java项目，它直接报错说"代码库太大，我已打了折扣"。最后只输出了30%的内容。所以，大型项目一定要分模块处理。
实战：为一个FastAPI项目生成完整文档
来看一个完整案例。这是我最近的一个项目，一个图书管理API。
第一步：分析现有代码
`bash
claude-code
然后输入：
请分析项目的整体结构，列出所有Python文件及其功能
`
Claude Code输出：
`
app/
├── main.py # 应用入口，FastAPI实例
├── models/
│ ├── book.py # Book模型
│ └── user.py # User模型
├── routers/
│ ├── books.py # 图书CRUD路由
│ └── auth.py # 认证路由
└── schemas/
├── book.py # Pydantic schema
└── user.py # Pydantic schema
第二步：批量生成注释
`
请为以下文件生成Google风格文档字符串：
- app/models/book.py
- app/schemas/book.py
- app/routers/books.py
要求：每个文件分别输出完整的新版本，不要只输出修改部分。
`
这里有个技巧：要求每个文件单独输出完整版本。如果不加这个，Claude经常会只输出新增的注释部分，你得自己拼接，非常麻烦。
第三步：生成API文档
`
从app/routers/books.py中提取所有API端点，生成OpenAPI风格的Markdown文档。
包含：
- 请求方法、路径
- 参数说明（路径参数、查询参数、请求体）
- 响应格式
- 状态码说明
- 使用示例（curl命令）
`
第四步：生成最终README
把前三步的结果汇总，生成最终的README。
*图3：从代码分析到文档输出的一站式工作流*
避坑指南
踩过的坑，我替你总结了三个立刻能用的：
坑1：生成的文档没有目录结构
解决方案：在提示词里明确要求"请用Markdown生成目录树，支持点击跳转"。
坑2：中文文档和英文文档混在一起
解决方案：在提示词里指定语言。比如"请用中文写文档，所有代码示例保留英文"。
坑3：生成的Mermaid图表渲染不出来
解决方案：要求Claude Code输出纯文本的Mermaid代码，不要用`mermaid包裹，而是用`包裹。VSCode的Markdown预览支持这种格式。
进阶技巧：用配置文件实现一键生成
这是我目前的生产力工具。创建一个.claude-docs.json配置文件：
`json`
{
"project_name": "图书管理API",
"project_type": "FastAPI",
"language": "zh",
"output_dir": "./docs",
"files_to_scan": [
"app/**/*.py",
"!app/tests/*"
],
"doc_types": {
"readme": true,
"api_docs": true,
"architecture": true,
"code_comments": false
},
"mermaid_enabled": true
}
然后在Claude Code里输入：
`
根据项目根目录下的.claude-docs.json配置文件，按需求生成所有文档。
先读取配置文件，然后按配置批量处理。
Claude Code会按配置逐个生成文档文件，自动放到./docs`目录。这个过程完全自动化，你只需要等着就行。
总结一下，你可以立刻用的三个点
最后说一句：AI生成的文档确实省时间，但一定要人工review。我遇到过最离谱的，Claude把”删除图书接口”的文档写成”创建图书接口”，这种错误如果不检查就发布，后果很严重。
记住：AI是辅助工具，最终的责任在你手上。