用 Cursor + Claude API 为遗留代码自动生成项目文档（实战）

2601_96168194

227人浏览 · 2026-06-12 11:20:03

2601_96168194 · 2026-06-12 11:20:03 发布

接手一个没有文档、没有注释的遗留项目，光是搞懂代码结构就要花上几天时间。本文将教你如何利用 Cursor Agent 分析整个代码库，再调用 Claude API 自动生成模块说明、API 文档、数据流向图和维护指南。全程自动化，你只需提供项目路径和几个自然语言指令。

在这里插入图片描述

一、为什么自动化文档生成是刚需

痛点	传统方式	AI 辅助方式
理解项目架构	人工阅读所有文件，耗时数天	AI 扫描生成架构概览，分钟级
编写 API 文档	手工整理路由、参数、返回值	AI 从代码中提取并生成标准格式
绘制依赖关系图	手动梳理，容易遗漏	AI 自动生成 Mermaid 流程图
保持文档同步	代码变更后文档常忘记更新	每次重构后重新生成，确保一致

对于 1 万行代码的项目，传统文档编写需要 5-7 人天，而 AI 辅助可将时间压缩到 1-2 小时，且文档质量更高。

二、准备工作

2.1 获取 Claude API Key

Anthropic API Key 可通过官方申请（需境外信用卡）。若无法自行办理，可参考 gpt108.com（仅作信息分享，支持支付宝/微信）。

2.2 环境要求

Cursor 编辑器（建议 Pro 版，以使用 Agent 模式）
目标项目代码（Python / JavaScript / TypeScript / Java 均可，本文以 Python Flask 为例）
网络环境能正常访问 Anthropic API

三、实战：为 Flask 项目生成完整文档

假设有一个 Flask 项目，目录结构如下：

my_project/
├── app/
│   ├── __init__.py
│   ├── models/
│   │   ├── user.py
│   │   └── product.py
│   ├── routes/
│   │   ├── user.py
│   │   └── product.py
│   └── utils/
│       └── db.py
├── config.py
└── run.py

3.1 让 Cursor Agent 分析项目并生成概览

在 Cursor 中打开项目根目录，按 Cmd+Shift+P → AI: New Chat → 选择 Agent 模式，输入：

@Codebase 请分析整个项目，生成一份 PROJECT_OVERVIEW.md，包含：
1. 技术栈（框架、数据库、第三方库）
2. 目录结构及每个模块的职责（一句话说明）
3. 主要的数据流（从请求到响应的路径）
4. 外部依赖（API、数据库表等）
使用 Mermaid 语法绘制架构图。

Agent 会扫描所有文件，输出类似：

# 项目概览

## 技术栈
- Web框架: Flask 2.3
- ORM: SQLAlchemy 2.0
- 数据库: PostgreSQL
- 认证: JWT

## 目录结构
- `app/models/` - 数据库模型定义
- `app/routes/` - API 路由处理
- `app/utils/` - 通用工具函数

## 架构图
```mermaid
graph TD
    Client[客户端] --> Flask[Flask App]
    Flask --> Auth[认证中间件]
    Auth --> UserRoute[用户路由]
    Auth --> ProductRoute[产品路由]
    UserRoute --> UserModel[用户模型]
    ProductRoute --> ProductModel[产品模型]
    UserModel --> DB[(PostgreSQL)]
    ProductModel --> DB


### 3.2 生成 API 文档

继续输入：

```text
@Codebase 请生成 API_DOCS.md，列出所有路由，每个路由包含：
- URL 和方法（GET/POST/PUT/DELETE）
- 请求参数（路径/查询/Body）及类型
- 响应示例（成功和失败）
- 权限要求
格式参考 OpenAPI 风格。

Agent 会遍历所有路由函数，提取装饰器、参数、返回值，生成类似：

## POST /api/v1/user/login

**描述**：用户登录，返回 JWT token。

**请求体**：
```json
{
  "email": "string (required)",
  "password": "string (required)"
}

成功响应 (200)：

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_in": 3600
}

失败响应 (401)：

{
  "error": "用户名或密码错误"
}


### 3.3 生成数据模型文档

```text
@Codebase 请生成 MODELS.md，列出所有数据库模型，每个模型包含：
- 表名
- 字段名、类型、约束（主键、外键、唯一等）
- 与其他模型的关系（一对多、多对多）
- 索引信息

3.4 生成环境配置说明

@Codebase 请分析 config.py 和环境变量，生成 CONFIGURATION.md，列出：
- 所有配置项及其默认值
- 生产环境需要覆盖的变量
- 敏感信息提示（如密钥、数据库密码）

3.5 生成维护指南

@Codebase 请生成 MAINTENANCE.md，包含：
- 如何运行开发服务器
- 如何运行测试
- 如何构建生产环境镜像
- 常见故障排查（基于代码中的异常处理）
- 代码贡献指南（基于现有代码风格）

四、一键生成所有文档

你也可以在一个指令中要求 Agent 生成全部文档：

@Codebase 请执行完整的文档生成任务：
1. 创建 docs/ 目录
2. 生成 PROJECT_OVERVIEW.md（含 Mermaid 架构图）
3. 生成 API_DOCS.md（所有路由）
4. 生成 MODELS.md（所有数据库模型）
5. 生成 CONFIGURATION.md（配置说明）
6. 生成 MAINTENANCE.md（维护指南）
所有文档使用中文，保存到 docs/ 文件夹下。

Agent 会自动创建目录、生成文件，并写入内容。

五、增量更新：代码变更后重新生成

当代码发生变更时，可以让 Agent 只更新受影响的文档：

@Codebase 我刚刚修改了 app/routes/user.py，请更新 API_DOCS.md 中关于用户模块的部分，其他部分保持不变。

Agent 会 diff 变化，仅更新相关章节。

六、与其他工具集成

6.1 发布到 GitHub Wiki

生成 Markdown 文档后，可以一键推送到 GitHub Wiki：

git clone https://github.com/your-repo.wiki.git
cp docs/*.md your-repo.wiki/
cd your-repo.wiki && git add . && git commit -m "Update docs" && git push

6.2 生成静态站点（如 Docusaurus）

让 Agent 生成 Docusaurus 兼容的 Markdown 格式，并自动创建侧边栏配置：

请将已生成的文档转换为 Docusaurus 格式，创建 sidebars.js 配置文件。

七、成本与效率

项目规模	传统文档编写耗时	AI 辅助耗时	节省比例
小型（10 个文件）	4 小时	10 分钟	96%
中型（50 个文件）	2 天	40 分钟	95%
大型（200 个文件）	1 周	2 小时	94%

成本：以 50 个文件的中型项目为例，Claude API 调用约 30k-50k token，成本 $0.15-0.25。

八、常见问题

问题	解决方法
Agent 忽略某些文件	确认文件未被 `.gitignore` 排除，或显式指定路径
生成的 Mermaid 图语法错误	让 Agent 重新输出，要求“使用标准 Mermaid 语法”
文档中缺少某些路由	检查路由定义是否使用了变量或装饰器工厂，Agent 可能无法解析，手动补充后让 Agent 学习
API 调用超时	使用 `claude-3-haiku` 处理简单文档，或分批次生成