文件管理
目的
文件生命週期管理工具。產生初始的專案文件、讓文件與程式碼變更保持同步、產生 API 參考,並自動產生變更日誌。解決文件管理中的頭號問題:文件雖然存在,但內容已經過時。
觸發條件
scaffold任務的階段 7 呼叫,用於初始文件產生cook任務階段 7 之後呼叫,用於更新功能實作後的文件launch任務部署前呼叫,確保文件是最新的/rune docs init— 首次文件產生/rune docs update— 同步文件與近期程式碼變更/rune docs api— 產生 API 文件/rune docs changelog— 從 git 歷史記錄自動產生變更日誌
對外呼叫(出站)
scout(L2):掃描程式碼基底,尋找文件目標(路由、匯出、元件、設定)doc-processor(L3):若需要,產生 PDF/DOCX 匯出git(L3):讀取提交歷史記錄,用於產生變更日誌
被誰呼叫(入站)
scaffold(L1):階段 7 — 為新專案產生初始文件cook(L1):功能實作後 — 更新已變更模組的文件launch(L1):部署前 — 驗證文件是否為最新mcp-builder(L2):產生 MCP 伺服器文件- 使用者:直接呼叫
/rune docs
模式
初始化模式 — /rune docs init
為專案進行首次文件產生。
更新模式 — /rune docs update
增量同步 — 僅更新受近期程式碼變更影響的文件。
API 模式 — /rune docs api
專門產生或更新 API 文件。
變更日誌模式 — /rune docs changelog
從 git 提交歷史記錄自動產生變更日誌。
可執行的步驟
初始化模式
步驟 1 — 掃描程式碼基底
呼叫 rune:scout 以擷取:
- 專案名稱、描述、技術棧
- 目錄結構與關鍵檔案
- 進入點(main、index、app)
- 公開 API 表面(匯出、路由、元件)
- 設定檔案(.env.example、設定模式)
- 現有文件(若有 — 合併,不要覆蓋)
步驟 2 — 產生 README.md
結構:
# [專案名稱]
[一行描述]
## 快速開始
[3-5 個指令即可執行:安裝、設定、啟動]
## 功能特性
[從程式碼中提取的項目清單 — 路由、元件、功能]
## 技術棧
[從 package.json、requirements.txt、Cargo.toml 等偵測]
## 專案結構
[關鍵目錄及其一行描述]
## 設定
[來自 .env.example 的環境變數及其描述]
## 開發
[開發伺服器、測試、程式碼檢查、建置指令]
## API 參考
[若適用,連結至 API.md 或內嵌摘要]
## 授權條款
[從 LICENSE 檔案或 package.json 偵測]
步驟 3 — 產生 ARCHITECTURE.md(若專案有 10 個以上檔案)
結構:
# 架構
## 概覽
[文字/mermaid 格式的系統圖 — 元件與資料流]
> ARCHITECTURE 概覽可以呼叫 `rune:diagram` 來取得設計好的系統圖(類型 `architecture`),而非原始 Mermaid — `suggested_next: diagram`。
## 關鍵決策
[偵測到的模式:框架選擇、狀態管理、資料庫、驗證方式]
## 模組地圖
[每個頂層目錄:用途、關鍵檔案、相依關係]
## 資料流
[請求生命週期或資料管線描述]
步驟 4 — 產生 API.md(若偵測到路由/端點)
掃描路由檔案並提取:
- HTTP 方法 + 路徑
- 請求參數(路徑參數、查詢參數、請求主體)
- 回應結構
- 驗證需求
- 錯誤回應
格式化為 Markdown 表格或相容於 OpenAPI 的參考。
步驟 5 — 回報
向使用者呈現產生的文件,附帶摘要:
- 已產生的檔案:[清單]
- 覆蓋率:〔已文件化的項目 vs 存在的項目〕
- 缺口:〔沒有文件的程式碼區域 — 建議下一步〕
更新模式
步驟 1 — 偵測變更
讀取自上次文件更新以來的 git diff(透過對文件檔案的 git 日誌或 .rune/docs-sync.json 追蹤)。
識別:
- 新檔案/模組 → 需要新的文件區段
- 已變更的函式/路由 → 需要更新文件
- 已刪除的程式碼 → 需要移除文件
- 新的設定 → 需要更新設定文件
步驟 2 — 更新受影響的區段
針對每個變更區域:
- 讀取已變更的程式碼
- 尋找對應的文件區段
- 更新文件以符合當前程式碼
- 若文件區段不存在 → 建立它
- 若程式碼已刪除 → 在文件中標記為移除或棄用
步驟 3 — 產生變更日誌條目
委派給 rune:git changelog,從自上次文件更新以來的提交中產生變更日誌條目。
步驟 4 — 跨文件一致性檢查
跨文件一致性可預防第二常見的文件問題:文件內容互相矛盾。
更新任何文件後,請驗證所有專案文件之間的一致性:
| 檢查項目 | 檔案 | 比較項目 |
|---|---|---|
| 版本號碼 | README、CLAUDE.md、package.json、CHANGELOG | 必須全都符合當前版本 |
| 功能清單 | README、登陸頁面、CLAUDE.md | 列出相同的功能(詳細程度可能不同) |
| 統計資料 | README、CLAUDE.md、登陸頁面、儀表板 | 技能數量、測試數量、訊號數量必須相符 |
| 指令 | README、CLAUDE.md、docs/ | 相同的指令與相同的旗標 |
| 技術棧 | README、ARCHITECTURE.md、CLAUDE.md | 一致的框架/函式庫參照 |
跨文件一致性:
- [x] README.md ↔ CLAUDE.md:版本相符、指令相符
- [x] README.md ↔ docs/index.html:統計資料相符、功能相符
- [ ] README.md 顯示「62 項技能」但 CLAUDE.md 顯示「59」 → 修正 CLAUDE.md
立即修正不一致之處 — 不要僅回報。將過時的文件更新為與事實來源(通常是程式碼或最近更新的文件)一致。
步驟 5 — 回報
向使用者顯示:更新了哪些項目、新增了哪些項目、哪些項目被標記為需要審查。包含跨文件一致性結果。
API 模式
步驟 1 — 偵測 API 框架
| 框架 | 路由模式 | 檔案模式 |
|---|---|---|
| Express | router.get/post/put/delete | routes/*.ts、*.router.ts |
| FastAPI | @app.get/post/put/delete | routers/*.py、main.py |
| NestJS | @Get/@Post/@Put/@Delete | *.controller.ts |
| Next.js App | export async function GET/POST | app/**/route.ts |
| Next.js Pages | export default function handler | pages/api/**/*.ts |
| SvelteKit | export function GET/POST | src/routes/**/+server.ts |
| Hono | app.get/post/put/delete | src/*.ts |
步驟 2 — 提取端點
針對每個偵測到的路由:
- 方法(GET、POST、PUT、DELETE、PATCH)
- 路徑(參數需標示)
- 請求:參數、查詢、主體結構(來自 Zod schemas、TypeScript 型別、Pydantic 模型)
- 回應:結構(來自回傳型別或回應輔助函式)
- 驗證:是否需要?(偵測中介軟體如
authMiddleware、@UseGuards) - 描述:若可用,來自 JSDoc/docstring
步驟 3 — 產生 API 參考
格式化為 Markdown:
# API 參考
## 驗證
[驗證機制描述]
## 端點
### `POST /api/auth/login`
**描述**:驗證使用者並回傳 Token
**驗證**:無
**請求主體**:
| 欄位 | 型別 | 必填 | 描述 |
|-------|------|----------|-------------|
| email | string | 是 | 使用者電子郵件 |
| password | string | 是 | 使用者密碼 |
**回應**(200):
```json
{ "token": "string", "refreshToken": "string" }
錯誤:
- 401:憑證無效
- 422:驗證錯誤
#### 步驟 4 — 輸出
儲存至 `docs/API.md` 或專案特定位置。若要求 OpenAPI,則產生 `openapi.yaml`。
### 變更日誌模式
#### 步驟 1 — 委派給 Git
呼叫 `rune:git changelog` 以將提交依類型分組,並格式化為「Keep a Changelog」格式。
#### 步驟 2 — 增強
為原始變更日誌加入上下文:
- 將 PR 編號連結至實際描述
- 將相關變更分組至功能標題下
- 突出顯示重大變更
#### 步驟 3 — 輸出
附加至或更新 `CHANGELOG.md`。
## 輸出格式
### 初始化模式輸出
在專案根目錄產生的檔案:
- `README.md` — 快速開始、功能特性、技術棧、結構、設定、開發指令
- `ARCHITECTURE.md` — 概覽圖、關鍵決策、模組地圖、資料流(10 個以上檔案)
- `docs/API.md` — 端點參考,包含方法、路徑、參數、回應、驗證(若偵測到路由)
### 更新模式輸出
已修改的文件區段與變更摘要:
文件更新報告:
- 已更新:[已修改的文件區段清單]
- 已新增:[新程式碼的新區段]
- 已標記:[參照已刪除程式碼的過時區段]
- 變更日誌:[已附加至 CHANGELOG.md 的條目]
### API 模式輸出
`docs/API.md` — 每個端點的 Markdown 參考:
METHOD /path/:param
描述:[來自 JSDoc/docstring] 驗證:[必要/無] 請求:[參數、查詢、主體表格] 回應:[含狀態碼的結構] 錯誤:[錯誤碼與描述]
### 變更日誌模式輸出
`CHANGELOG.md` — 按「Keep a Changelog」格式分組:新增、修正、變更、移除。
## 限制條件
1. 必須從實際程式碼產生文件 — 絕不捏造不存在的功能或 API
2. 必須保留現有文件 — 更新區段,不要覆蓋整個檔案
3. 必須偵測文件過時 — 標記參照已刪除/變更程式碼的區段
4. 每個 README 必須包含「快速開始」 — 使用者在 2 分鐘內即可上手
5. 絕不為尚未存在的程式碼產生文件(除非明確建立規格文件)
6. API 文件必須與實際路由簽名相符 — 錯誤的 API 文件比沒有文件更糟
## 回傳值
| 產出物 | 格式 | 位置 |
|----------|--------|----------|
| README.md | Markdown | 專案根目錄 |
| ARCHITECTURE.md | Markdown | 專案根目錄(10 個以上檔案) |
| API 參考 | Markdown | `docs/API.md` |
| 變更日誌條目 | Markdown(Keep a Changelog) | `CHANGELOG.md` |
| 文件更新報告 | Markdown | 內聯(聊天輸出) |
**範圍護欄:** 僅記錄程式碼基底中存在的項目 — 絕不捏造功能、端點或 API。
## 邊緣案例
| 失敗模式 | 嚴重性 | 緩解措施 |
|---|---|---|
| 捏造不存在的 API 端點 | 嚴重 | 限制條件 1:掃描實際路由檔案,不要猜測 |
| 覆蓋使用者撰寫的 README 區段 | 高 | 限制條件 2:合併,不要覆蓋 — 偵測自訂區段 |
| 程式碼變更後文件過時 | 高 | 更新模式偵測差異並更新受影響區段 |
| API 文件帶有錯誤的請求/回應結構 | 高 | 從 Zod/Pydantic/TypeScript 型別提取,而非從記憶 |
| 缺少快速開始區段 | 中 | 限制條件 4:每個 README 都有快速開始 |
| 變更日誌帶有孤立的 PR 連結 | 低 | 在連結前驗證 PR 編號是否存在 |
| 跨文件不一致(README 說 X,CLAUDE.md 說 Y) | 高 | 步驟 7:跨文件一致性檢查 — 驗證所有文件中的統計資料、版本與功能清單是否相符 |
| 更新一份文件但未更新其他文件(統計資料飄移) | 高 | 任何文件更新後,全面檢查所有相關文件中的過時統計資料 — 尤其是 README ↔ CLAUDE.md ↔ 登陸頁面 |
## 完成條件
### 初始化模式
- 已使用 scout 掃描程式碼基底
- 已產生 README.md,包含快速開始、功能特性、技術棧、結構
- 已產生 ARCHITECTURE.md(10 個以上檔案)
- 已產生 API.md(若偵測到路由)
- 已向使用者呈現覆蓋率報告
### 更新模式
- 已偵測到自上次文件更新以來的變更
- 已更新受影響的文件區段
- 已產生變更日誌條目
- 已向使用者呈現更新報告
### API 模式
- 已偵測到 API 框架
- 已提取所有端點的方法、路徑、請求、回應
- 已產生 Markdown 格式的 API 參考
- 已儲存至 docs/API.md
### 變更日誌模式
- 已依類型分組提交
- 已格式化為「Keep a Changelog」
- 已更新 CHANGELOG.md
## 成本概況
約 2000-5000 tokens 輸入、約 1000-3000 tokens 輸出。使用 Sonnet 模型 — 文件工作需要理解程式碼模式,但不需要深入的架構推理。