技术文档是开发者最头疼的事之一——代码写完了，文档总是拖着不写。 Claude Code 可以直接读你的代码，自动生成高质量文档。
工作流 1：生成项目 README
Generate a comprehensive README.md for this project.
Analyze the project structure, package.json/pyproject.toml, and source code.
README should include:
1. Project name + one-line description
2. Key features (bullet list, max 6)
3. Quick start (prerequisites + install + first run)
4. Usage examples (3 most common scenarios with code)
5. Configuration options (table format)
6. Contributing guidelines (brief)
7. License
工作流 2：从源码生成 API 文档
Read all FastAPI route handlers in src/routers/.
For each endpoint, add docstrings with:
1. One-line summary
2. Detailed description
3. Parameter descriptions
4. Response examples (200, 400, 401, 404)
5. Request body example
通用 API 参考文档模板：
Generate docs/api-reference.md for each endpoint:
- METHOD /path
- Description and authentication requirements
- Request/response JSON examples
- Error codes table
工作流 3：架构设计文档（含 Mermaid 图）
Generate docs/architecture.md:
1. System Overview
2. Component Diagram (Mermaid syntax)
3. Data Flow (Mermaid sequence diagram)
4. Technology Choices with rationale
5. Database Schema (Mermaid ER diagram)
6. Authentication Flow
7. Key Design Decisions
生成的 Mermaid 组件图示例：
mermaid
graph TB
Client[Web Client] --> API[FastAPI Backend]
API --> Auth[Auth Service]
API --> DB[(PostgreSQL)]
API --> Cache[(Redis)]
API --> Queue[Task Queue]
Queue --> Worker[Celery Worker]工作流 4：自动生成 CHANGELOG
bash
# 获取最近提交记录
git log --oneline --since='30 days ago' > commits.txt
# 让 Claude 整理成标准格式
claude -p "Read commits.txt and generate CHANGELOG.md entries.
Use Keep a Changelog format. Group by Added/Changed/Fixed.
Write user-facing descriptions, not raw commit messages."工作流 5：Hooks 自动更新文档
配置 Claude Code Hooks，代码修改后自动触发文档检查：
json
{
"hooks": {
"PostToolUse": [{
"matcher": "Edit",
"hooks": [{
"type": "command",
"command": "claude -p 'Check if API docs need updating after last code change. Update docs/api-reference.md if endpoints changed.' --no-interactive"
}]
}]
}
}工作流 6：批量添加代码注释
Add comprehensive docstrings to all public functions in src/.
Python: Google-style docstrings
- Args: each parameter with type and description
- Returns: return value description
- Raises: exceptions that can be raised
- Example: usage example
TypeScript: JSDoc format
- @param name - description
- @returns description
- @throws {ErrorType} when...
- @example
Focus on explaining WHY and WHAT, not HOW.
工作流 7：CONTRIBUTING.md 生成
Generate CONTRIBUTING.md for this open source project.
Include:
- Development setup (step by step, tested commands)
- Code style guide (reference ESLint/Prettier config)
- Branch naming: feat/fix/docs/chore prefix
- Commit format: Conventional Commits (conventionalcommits.org)
- PR process: how to submit, expected review timeline
- Testing: CI must pass, coverage requirements
Tone: Welcoming to first-time contributors.
Add a "Good First Issues" section pointer.
CLAUDE.md 文档维护规范模板
markdown
## 文档规范（强制执行）
- 新增公共函数必须有 docstring，说明功能和参数
- 修改 API 端点后同步更新 docs/api-reference.md
- 每次发版前验证 README Quick Start 命令可以成功执行
- CHANGELOG 使用 Keep a Changelog 格式（keepachangelog.com）
- 架构变更后更新 docs/architecture.md 的 Mermaid 图
禁止：
- 代码里有 TODO 注释超过 2 周不处理
- API 有参数变更但文档未同步来源：Anthropic 官方文档 + 技术写作最佳实践