项目文档生成器
通过分析代码库生成结构化的项目文档。生成的文档反映实际的代码，而非理想化的架构。
何时使用
- 新项目需要初始文档
- 文档缺失或过时
- 为新成员介绍代码库
- 重构后刷新文档
工作流程
1. 检测项目类型
扫描项目根目录，确定项目类型：
| 指示器 | 项目类型 |
|---|---|
wrangler.jsonc / wrangler.toml | Cloudflare Worker |
vite.config.ts + src/App.tsx | React SPA |
astro.config.mjs | Astro 站点 |
next.config.js | Next.js 应用 |
package.json 包含 hono | Hono API |
src/index.ts 包含 Hono | API 服务器 |
drizzle.config.ts | 包含数据库层 |
schema.ts 或 schema/ | 包含数据库模式 |
pyproject.toml / setup.py | Python 项目 |
Cargo.toml | Rust 项目 |
2. 询问生成内容
应该生成哪些文档？
1. ARCHITECTURE.md — 系统概述、技术栈、目录结构、关键流程
2. API_ENDPOINTS.md — 路由、方法、参数、响应结构、认证
3. DATABASE_SCHEMA.md — 表、关系、迁移、索引
4. 以上全部
仅提供与项目匹配的文档。不为静态站点提供 API_ENDPOINTS.md。如果没有数据库，则不提供 DATABASE_SCHEMA.md。
3. 扫描代码库
对于每个请求的文档，读取相关的源文件：
ARCHITECTURE.md — 扫描：
package.json/pyproject.toml（技术栈、依赖）- 入口点（
src/index.ts、src/main.tsx、src/App.tsx） - 配置文件（
wrangler.jsonc、vite.config.ts、tsconfig.json） - 目录结构（前两层）
- 关键模块及其导出
API_ENDPOINTS.md — 扫描：
- 路由文件（
src/routes/、src/api/或内联在 index 中） - 中间件文件（认证、CORS、日志）
- 请求/响应类型或 Zod 模式
- 错误处理模式
DATABASE_SCHEMA.md — 扫描：
- Drizzle 模式文件（
src/db/schema.ts、src/schema/） - 迁移文件（
drizzle/、migrations/） - 原始 SQL 文件（如果存在）
- 种子文件（如果存在）
4. 生成文档
将每个文档写入 docs/（如果该目录不存在则创建）。如果项目在该目录中已有文档，则提供更新选项而非覆盖。
对于没有 docs/ 目录的小项目，直接写入项目根目录。
文档模板
ARCHITECTURE.md
# 架构
## 概述
[一段：项目功能及其结构]
## 技术栈
| 层 | 技术 | 版本 |
|----|------|-----|
| 运行时 | [例如 Cloudflare Workers] | — |
| 框架 | [例如 Hono] | [版本] |
| 数据库 | [例如 D1 (SQLite)] | — |
| ORM | [例如 Drizzle] | [版本] |
| 前端 | [例如 React 19] | [版本] |
| 样式 | [例如 Tailwind v4] | [版本] |
## 目录结构
[带注释的树状结构 — 前两层及用途说明]
## 关键流程
### [流程 1：例如“用户认证”]
[逐步说明：请求 → 中间件 → 处理程序 → 数据库 → 响应]
### [流程 2：例如“数据处理流水线”]
[逐步说明系统流程]
## 配置
[关键配置文件及其控制内容]
## 部署
[如何部署、所需环境变量、构建命令]
API_ENDPOINTS.md
# API 端点
## 基础 URL
[例如 `https://api.example.com` 或相对路径 `/api`]
## 认证
[方式：Bearer token、会话 cookie、API 密钥、无]
[令牌来源及获取方式]
## 端点
### [分组：例如用户]
#### `GET /api/users`
- **认证**：必需
- **参数**：`?page=1&limit=20`
- **响应**：`{ users: User[], total: number }`
#### `POST /api/users`
- **认证**：必需（管理员）
- **请求体**：`{ name: string, email: string }`
- **响应**：`{ user: User }` (201)
- **错误**：400（验证错误）、409（邮箱重复）
[对每个端点重复]
## 错误格式
[标准错误响应结构]
## 速率限制
[如果适用]
DATABASE_SCHEMA.md
# 数据库模式
## 引擎
[例如 Cloudflare D1 (SQLite)、PostgreSQL、MySQL]
## 表
### `users`
| 列名 | 类型 | 约束 | 描述 |
|------|------|------|------|
| id | TEXT | 主键 | UUID |
| email | TEXT | UNIQUE, NOT NULL | 用户邮箱 |
| name | TEXT | NOT NULL | 显示名称 |
| created_at | TEXT | NOT NULL, DEFAULT now | ISO 时间戳 |
### `posts`
[相同格式]
## 关系
[外键、连接模式、级联规则]
## 索引
[非主键索引及其存在原因]
## 迁移
- 生成：`npx drizzle-kit generate`
- 本地应用：`npx wrangler d1 migrations apply DB --local`
- 远程应用：`npx wrangler d1 migrations apply DB --remote`
## 种子数据
[引用种子脚本（如果存在）]
质量标准
- 记录实际存在的内容，而非计划中的内容 — 读取实际代码，不要发明端点或表
- 包含版本信息 — 从 package.json/lock 文件中提取，而非凭记忆
- 展示真实的响应结构 — 从代码中的 TypeScript 类型或 Zod 模式复制
- 保持可扫描性 — 表格优于段落，代码块优于散文
- 不要重复 CLAUDE.md — 如果架构信息已在 CLAUDE.md 中，则将其移至 ARCHITECTURE.md 或引用它
- 标记缺失 — 如果发现未记录的路由或用途不明确的表，使用
<!-- TODO: document purpose -->进行标注
更新现有文档
如果文档已存在：
- 读取现有文档
- 与当前代码库进行差异比较
- 向用户展示变更内容（新增端点、删除的表、更新的技术栈）
- 应用更新，同时保留任何手写笔记或章节
绝不在不告知的情况下静默覆盖用户添加的自定义内容。