專案文件產生器
透過分析程式碼庫來產生結構化的專案文件。產出的文件反映實際的程式碼，而非預期的架構。
使用時機
- 新專案需要初始文件
- 文件遺失或過時
- 引導新人加入程式碼庫
- 重構後的文件更新
工作流程
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/ | 有資料庫 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 schema
- 錯誤處理模式
DATABASE_SCHEMA.md — 掃描：
- Drizzle schema 檔案（
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、session cookie、API key、無]
[Token 的來源與取得方式]
## 端點
### [群組：例如「使用者」]
#### `GET /api/users`
- **驗證**：必要
- **參數**：`?page=1&limit=20`
- **回應**：`{ users: User[], total: number }`
#### `POST /api/users`
- **驗證**：必要（管理員）
- **主體**：`{ name: string, email: string }`
- **回應**：`{ user: User }`（201）
- **錯誤**：400（驗證失敗）、409（重複的 email）
[為每個端點重複]
## 錯誤格式
[標準錯誤回應格式]
## 速率限制
[如果適用]
DATABASE_SCHEMA.md
# 資料庫 Schema
## 引擎
[例如 Cloudflare D1 (SQLite)、PostgreSQL、MySQL]
## 資料表
### `users`
| 欄位 | 型別 | 約束 | 說明 |
|--------|------|-------------|-------------|
| id | TEXT | PK | UUID |
| email | TEXT | UNIQUE, NOT NULL | 使用者 email |
| name | TEXT | NOT NULL | 顯示名稱 |
| created_at | TEXT | NOT NULL, DEFAULT now | ISO 時間戳 |
### `posts`
[相同格式]
## 關聯
[外鍵、JOIN 模式、串聯規則]
## 索引
[非主鍵索引及其存在原因]
## 遷移
- 產生：`npx drizzle-kit generate`
- 套用到本機：`npx wrangler d1 migrations apply DB --local`
- 套用到遠端：`npx wrangler d1 migrations apply DB --remote`
## 種子資料
[參考種子腳本（如果存在）]
品質規則
- 記錄現有項目，而非計劃中的項目 — 讀取實際程式碼，不要虛構端點或資料表
- 包含版本資訊 — 從 package.json/lock 檔案中提取，而非根據記憶
- 顯示真實的回應格式 — 從程式碼中的 TypeScript 型別或 Zod schema 複製
- 保持易於掃讀 — 表格優於段落，程式碼區塊優於散文
- 不要重複 CLAUDE.md 的內容 — 如果架構資訊已在 CLAUDE.md 中，則將其移至 ARCHITECTURE.md，或直接引用
- 標記缺口 — 如果發現未記載的路由或用途不明的資料表，請以
<!-- TODO: document purpose -->註記
更新現有文件
如果文件已存在：
- 讀取現有文件
- 與目前的程式碼庫進行比對
- 向使用者顯示變更內容（新端點、已移除的資料表、更新的技術棧）
- 套用更新，同時保留任何手寫的備註或章節
永遠不要靜默地覆寫使用者已添加到文件中的自訂內容。