project-docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Project Documentation Generator

项目文档生成器

Generate structured project documentation by analysing the codebase. Produces docs that reflect the actual code, not aspirational architecture.

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

When to Use

适用场景

New project needs initial documentation
Docs are missing or stale
Onboarding someone to the codebase
Post-refactor doc refresh

新项目需要初始文档
文档缺失或过时
帮助新成员熟悉代码库
重构后更新文档

Workflow

工作流程

1. Detect Project Type

1. 检测项目类型

Scan the project root to determine what kind of project this is:

Indicator	Project Type
`wrangler.jsonc` / `wrangler.toml`	Cloudflare Worker
`vite.config.ts` + `src/App.tsx`	React SPA
`astro.config.mjs`	Astro site
`next.config.js`	Next.js app
`package.json` with `hono`	Hono API
`src/index.ts` with `Hono`	API server
`drizzle.config.ts`	Has database layer
`schema.ts` or `schema/`	Has database schema
`pyproject.toml` / `setup.py`	Python project
`Cargo.toml`	Rust project

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

识别标识	项目类型
`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. Ask What to Generate

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

Only offer docs that match the project. Don't offer API_ENDPOINTS.md for a static site. Don't offer DATABASE_SCHEMA.md if there's no database.

需要生成哪些文档？
1. ARCHITECTURE.md — 系统概述、技术栈、目录结构、核心流程
2. API_ENDPOINTS.md — 路由、请求方法、参数、响应结构、认证方式
3. DATABASE_SCHEMA.md — 数据表、关系、迁移脚本、索引
4. 全部生成

仅提供与项目匹配的文档选项。静态站点不提供API_ENDPOINTS.md选项，无数据库的项目不提供DATABASE_SCHEMA.md选项。

3. Scan the Codebase

3. 扫描代码库

For each requested doc, read the relevant source files:

ARCHITECTURE.md — scan:

```
package.json
```
/
```
pyproject.toml
```
(stack, dependencies)
Entry points (
```
src/index.ts
```
,
```
src/main.tsx
```
,
```
src/App.tsx
```
)

Config files (

wrangler.jsonc

vite.config.ts

tsconfig.json

)

Directory structure (top 2 levels)
Key modules and their exports

API_ENDPOINTS.md — scan:

Route files (
```
src/routes/
```
,
```
src/api/
```
, or inline in index)
Middleware files (auth, CORS, logging)
Request/response types or Zod schemas
Error handling patterns

DATABASE_SCHEMA.md — scan:

Drizzle schema files (
```
src/db/schema.ts
```
,
```
src/schema/
```
)
Migration files (
```
drizzle/
```
,
```
migrations/
```
)
Raw SQL files if present
Seed files if present

针对每个选定的文档，读取相关源文件：

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/
```
或入口文件内联定义）
中间件文件（认证、CORS、日志）
请求/响应类型或Zod模式
错误处理模式

DATABASE_SCHEMA.md — 扫描内容：

Drizzle模式文件（
```
src/db/schema.ts
```
、
```
src/schema/
```
）
迁移文件（
```
drizzle/
```
、
```
migrations/
```
）
原始SQL文件（如果存在）
种子数据文件（如果存在）

4. Generate Documentation

4. 生成文档

Write each doc to

docs/

(create the directory if it doesn't exist). If the project already has docs there, offer to update rather than overwrite.

For small projects with no

docs/

directory, write to the project root instead.

将每个文档写入

docs/

目录（若不存在则创建）。如果项目中已存在该目录下的文档，需询问用户是否更新而非直接覆盖。

对于无

docs/

Document Templates

文档模板

ARCHITECTURE.md

markdown

undefined

markdown

undefined

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]

层级	技术选型	版本
运行时	[示例：Cloudflare Workers]	—
框架	[示例：Hono]	[版本号]
数据库	[示例：D1 (SQLite)]	—
ORM	[示例：Drizzle]	[版本号]
前端	[示例：React 19]	[版本号]
样式	[示例：Tailwind v4]	[版本号]

Directory Structure

目录结构

[Annotated tree — top 2 levels with purpose comments]

[带注释的目录树 — 前两层目录及用途说明]

Key Flows

核心流程

[Flow 1: e.g. "User Authentication"]

[流程1：示例："用户认证流程"]

[Step-by-step: request → middleware → handler → database → response]

[分步说明：请求 → 中间件 → 处理器 → 数据库 → 响应]

[Flow 2: e.g. "Data Processing Pipeline"]

[流程2：示例："数据处理流水线"]

[Step-by-step through the system]

[系统内的分步处理流程]

Configuration

配置说明

[Key config files and what they control]

[核心配置文件及其作用]

Deployment

部署方式

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

undefined

[部署步骤、所需环境变量、构建命令]

undefined

API_ENDPOINTS.md

markdown

undefined

markdown

undefined

API Endpoints

API 端点文档

Base URL

基础URL

[e.g.

https://api.example.com

or relative

/api

]

[示例：

https://api.example.com

或相对路径

/api

]

Authentication

认证方式

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

[认证方法：Bearer令牌、会话Cookie、API密钥、无认证] [令牌获取方式]

Endpoints

端点列表

[Group: e.g. Users]

[分组：示例：用户模块]

GET /api/users

GET /api/users

Auth: Required
Params:
```
?page=1&limit=20
```
Response:
```
{ users: User[], total: number }
```

认证要求：需要
查询参数：
```
?page=1&limit=20
```
响应格式：
```
{ users: User[], total: number }
```

POST /api/users

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]

认证要求：需要（管理员权限）
请求体：
```
{ name: string, email: string }
```
响应格式：
```
{ user: User }
```
（状态码201）
错误码：400（参数验证失败）、409（邮箱已存在）

[每个端点重复上述格式]

Error Format

错误响应格式

[Standard error response shape]

[标准错误响应结构]

Rate Limits

速率限制

[If applicable]

undefined

[如果适用]

undefined

DATABASE_SCHEMA.md

markdown

undefined

markdown

undefined

Database Schema

数据库模式文档

Engine

数据库引擎

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

[示例：Cloudflare D1 (SQLite)、PostgreSQL、MySQL]

Tables

数据表

users

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

列名	类型	约束	说明
id	TEXT	PK	UUID
email	TEXT	UNIQUE, NOT NULL	用户邮箱
name	TEXT	NOT NULL	显示名称
created_at	TEXT	NOT NULL, DEFAULT now	ISO时间戳

posts

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

生成迁移：
```
npx drizzle-kit generate
```

本地应用迁移：

npx wrangler d1 migrations apply DB --local

远程应用迁移：

npx wrangler d1 migrations apply DB --remote

Seed Data

种子数据

[Reference to seed script if one exists]

undefined

[种子脚本的引用（如果存在）]

undefined

Quality Rules

质量规则

Document what exists, not what's planned — read the actual code, don't invent endpoints or tables
Include versions — extract from package.json/lock files, not from memory
Show real response shapes — copy from TypeScript types or Zod schemas in the code
Keep it scannable — tables over paragraphs, code blocks over prose
Don't duplicate CLAUDE.md — if architecture info is already in CLAUDE.md, either move it to ARCHITECTURE.md or reference it
Flag gaps — if you find undocumented routes or tables without clear purpose, note them with
```

```

记录实际存在的内容，而非计划内容 — 基于实际代码生成，不要虚构端点或数据表
包含版本信息 — 从package.json/锁文件中提取，而非凭记忆填写
展示真实响应结构 — 从代码中的TypeScript类型或Zod模式中复制
保持易读性 — 优先使用表格而非段落，优先使用代码块而非散文
不重复CLAUDE.md内容 — 如果架构信息已存在于CLAUDE.md中，要么迁移到ARCHITECTURE.md，要么添加引用
标记缺失内容 — 如果发现未文档化的路由或用途不明确的数据表，使用
```

```
进行标记

Updating Existing Docs

更新现有文档

If docs already exist:

Read the existing doc
Diff against the current codebase
Show the user what's changed (new endpoints, removed tables, updated stack)
Apply updates preserving any hand-written notes or sections

Never silently overwrite custom content the user has added to their docs.

如果文档已存在：

读取现有文档内容
与当前代码库进行对比
向用户展示变更内容（新增端点、删除的数据表、更新的技术栈）
在保留用户手写注释或自定义内容的基础上应用更新

切勿静默覆盖用户添加的自定义内容。