project-docs

项目文档生成器

通过分析代码库生成结构化项目文档。生成的文档反映实际代码，而非理想化的架构。

适用场景

• 新项目需要初始文档
• 文档缺失或已过时
• 帮助他人熟悉代码库
• 重构后刷新文档

工作流

1. 检测项目类型

扫描项目根目录，确定项目类型：

指示项	项目类型
wrangler.jsonc / wrangler.toml	Cloudflare Worker
vite.config.ts + src/App.tsx	React SPA
astro.config.mjs	Astro 站点
next.config.js	Next.js 应用
包含 hono 的 package.json	Hono API
包含 Hono 的 src/index.ts	API 服务端
drizzle.config.ts	包含数据库层
schema.ts 或 schema/	包含数据库架构
pyproject.toml / setup.py	Python 项目
Cargo.toml	Rust 项目

2. 询问要生成哪些文档

Which docs should I generate?
1. ARCHITECTURE.md — system overview, stack, directory structure, key flows
2. API_ENDPOINTS.md — routes, methods, params, response shapes, auth
3. DATABASE_SCHEMA.md — tables, relationships, migrations, indexes
4. All of the above

只提供与项目匹配的文档。静态站点不要提供 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）
• 目录结构（前 2 层）
• 关键模块及其导出项

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

# Architecture

## Overview
[One paragraph: what this project does and how it's structured]

## Stack
| Layer | Technology | Version |
|-------|-----------|---------|
| Runtime | [e.g. Cloudflare Workers] | — |
| Framework | [e.g. Hono] | [version] |
| Database | [e.g. D1 (SQLite)] | — |
| ORM | [e.g. Drizzle] | [version] |
| Frontend | [e.g. React 19] | [version] |
| Styling | [e.g. Tailwind v4] | [version] |

## Directory Structure
[Annotated tree — top 2 levels with purpose comments]

## Key Flows
### [Flow 1: e.g. "User Authentication"]
[Step-by-step: request → middleware → handler → database → response]

### [Flow 2: e.g. "Data Processing Pipeline"]
[Step-by-step through the system]

## Configuration
[Key config files and what they control]

## Deployment
[How to deploy, environment variables needed, build commands]

API_ENDPOINTS.md

# API Endpoints

## Base URL
[e.g. `https://api.example.com` or relative `/api`]

## Authentication
[Method: Bearer token, session cookie, API key, none]
[Where tokens come from, how to obtain]

## Endpoints

### [Group: e.g. Users]

#### `GET /api/users`
- **Auth**: Required
- **Params**: `?page=1&limit=20`
- **Response**: `{ users: User[], total: number }`

#### `POST /api/users`
- **Auth**: Required (admin)
- **Body**: `{ name: string, email: string }`
- **Response**: `{ user: User }` (201)
- **Errors**: 400 (validation), 409 (duplicate email)

[Repeat for each endpoint]

## Error Format
[Standard error response shape]

## Rate Limits
[If applicable]

DATABASE_SCHEMA.md

# Database Schema

## Engine
[e.g. Cloudflare D1 (SQLite), PostgreSQL, MySQL]

## Tables

### `users`
| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| id | TEXT | PK | UUID |
| email | TEXT | UNIQUE, NOT NULL | User email |
| name | TEXT | NOT NULL | Display name |
| created_at | TEXT | NOT NULL, DEFAULT now | ISO timestamp |

### `posts`
[Same format]

## Relationships
[Foreign keys, join patterns, cascading rules]

## Indexes
[Non-primary indexes and why they exist]

## Migrations
- Generate: `npx drizzle-kit generate`
- Apply local: `npx wrangler d1 migrations apply DB --local`
- Apply remote: `npx wrangler d1 migrations apply DB --remote`

## Seed Data
[Reference to seed script if one exists]

质量规则

1. 记录现有内容，而非计划内容 — 阅读实际代码，不要编造端点或表
2. 包含版本号 — 从 package.json/锁文件中提取，不要凭记忆填写
3. 展示真实的响应结构 — 从代码中的 TypeScript 类型或 Zod 架构复制
4. 保持易于浏览 — 多用表格，少用段落；多用代码块，少用散文
5. 不要重复 CLAUDE.md 的内容 — 如果 CLAUDE.md 中已有架构信息，则将其移至 ARCHITECTURE.md 或引用该文件
6. 标记缺漏 — 如果发现未记录的路由或用途不明确的表，请使用 `` 注明

更新现有文档

如果文档已存在：

1. 阅读现有文档
2. 与当前代码库进行差异比较
3. 向用户展示变更内容（新增端点、已删除的表、更新后的技术栈）
4. 应用更新，同时保留任何手写备注或章节

绝不要在未告知用户的情况下，静默覆盖用户添加到文档中的自定义内容。