Communitygithub.com

Rune-kit/rune 文件自動化工具

自動生成與維護專案文件。建立 README、API 文件、架構文件與變更日誌,並使其與程式碼變更保持同步。號稱「文件永不落後」的技能。

rune 文件自動化工具 是什麼?

這個 AI 代理技能提供完整的文件生命週期管理:從首次初始化專案文件,到持續同步程式碼變更,再到自動產生 API 參考與變更日誌。它解決了文件管理中最常見的痛點:文件雖然存在,但內容已經過時。 此技能會直接掃描實際的程式碼基底來產生文件,確保每個陳述都可追溯到特定檔案、函式或設定,絕不憑空捏造功能或 API。它支援多種觸發方式,包括專案搭建(scaffold)、功能開發後更新(cook)、部署前檢查(launch),以及 `/rune docs` 指令的直接呼叫。 技能涵蓋四種主要模式:初始化模式、更新模式、API 模式與變更日誌模式。初始化模式會使用 scout 掃描程式碼基底,產生 README、架構文件(適用於 10 個以上檔案的事案)與 API 參考。更新模式則讀取 git diff 以找出受影響的文件區段,進行增量同步,並執行跨文件一致性檢查,確保所有文件(README、CLAUDE.md、CHANGELOG 等)中的版本號碼、功能清單與統計資料保持一致。 此技能支援多種 API 框架(Express、FastAPI、NestJS、Next.js、SvelteKit、Hono),並可從 Zod、Pydantic 與 TypeScript 型別中擷取請求/回應的定義。輸出格式為標準 Markdown 檔案,包括 README.md、ARCHITECTURE.md、docs/API.md 與 CHANGELOG.md,是確保專案文件永遠與實際程式碼同步的強大工具。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Rune-kit/rune/tree/HEAD/skills/docs

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

文件管理

目的

文件生命週期管理工具。產生初始的專案文件、讓文件與程式碼變更保持同步、產生 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 — 更新受影響的區段

針對每個變更區域:

  1. 讀取已變更的程式碼
  2. 尋找對應的文件區段
  3. 更新文件以符合當前程式碼
  4. 若文件區段不存在 → 建立它
  5. 若程式碼已刪除 → 在文件中標記為移除或棄用

步驟 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 框架

框架路由模式檔案模式
Expressrouter.get/post/put/deleteroutes/*.ts、*.router.ts
FastAPI@app.get/post/put/deleterouters/*.py、main.py
NestJS@Get/@Post/@Put/@Delete*.controller.ts
Next.js Appexport async function GET/POSTapp/**/route.ts
Next.js Pagesexport default function handlerpages/api/**/*.ts
SvelteKitexport function GET/POSTsrc/routes/**/+server.ts
Honoapp.get/post/put/deletesrc/*.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 模型 — 文件工作需要理解程式碼模式,但不需要深入的架構推理。

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

相關技能