docs
目的
ドキュメントライフサイクルマネージャー。プロジェクトの初期ドキュメントを生成し、コード変更とドキュメントを同期し、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直接呼び出し
モード
Init モード — /rune docs init
プロジェクトの初回ドキュメント生成。
Update モード — /rune docs update
インクリメンタル同期 — 最近のコード変更によって影響を受けたドキュメントのみを更新。
API モード — /rune docs api
APIドキュメントを特異的に生成または更新。
Changelog モード — /rune docs changelog
gitコミット履歴から変更履歴を自動生成。
実行可能ステップ
Init モード
ステップ 1 — コードベースをスキャン
rune:scout を呼び出して以下を抽出:
- プロジェクト名、説明、技術スタック
- ディレクトリ構造と主要ファイル
- エントリポイント(main、index、app)
- 公開APIサーフェス(エクスポート、ルート、コンポーネント)
- 設定ファイル(.env.example、設定パターン)
- 既存のドキュメント(あれば — マージし、上書きしない)
ステップ 2 — README.md を生成
構造:
# [プロジェクト名]
[1行の説明]
## クイックスタート
[実行するための3〜5のコマンド: インストール、設定、起動]
## 機能
[コードから抽出した箇条書き — ルート、コンポーネント、機能]
## 技術スタック
[package.json、requirements.txt、Cargo.toml等から検出]
## プロジェクト構造
[主要ディレクトリと1行の説明]
## 設定
[.env.exampleの環境変数と説明]
## 開発
[開発サーバー、テスト、リント、ビルドコマンド]
## APIリファレンス
[該当する場合はAPI.mdへのリンク、またはインライン要約]
## ライセンス
[LICENSEファイルまたはpackage.jsonから検出]
ステップ 3 — ARCHITECTURE.md を生成(プロジェクトに10ファイル以上ある場合)
構造:
# アーキテクチャ
## 概要
[テキストまたはmermaidによるシステム図 — コンポーネントとデータフロー]
> ARCHITECTUREの概要では、生のMermaidの代わりに、設計されたシステム図(タイプ `architecture`)のために `rune:diagram` を呼び出すことができます — `suggested_next: diagram`。
## 主要な決定
[検出されたパターン: フレームワークの選択、状態管理、DB、認証アプローチ]
## モジュールマップ
[各トップレベルディレクトリ: 目的、主要ファイル、依存関係]
## データフロー
[リクエストライフサイクルまたはデータパイプラインの説明]
ステップ 4 — API.md を生成(ルート/エンドポイントが検出された場合)
ルートファイルをスキャンして抽出:
- HTTPメソッド + パス
- リクエストパラメータ(パス、クエリ、ボディ)
- レスポンス形状
- 認証要件
- エラーレスポンス
MarkdownテーブルまたはOpenAPI準拠のリファレンスとしてフォーマット。
ステップ 5 — レポート
生成されたドキュメントを要約とともにユーザーに提示:
- 生成されたファイル: [リスト]
- カバレッジ: [文書化されているものと存在するもの]
- ギャップ: [ドキュメントがないコード領域 — 次のステップを提案]
Update モード
ステップ 1 — 変更を検出
前回のドキュメント更新(ドキュメントファイルのgitログまたは .rune/docs-sync.json で追跡)以降の git diff を読み取る。
特定:
- 新しいファイル/モジュール → 新しいドキュメントセクションが必要
- 変更された関数/ルート → ドキュメントの更新が必要
- 削除されたコード → ドキュメントの削除が必要
- 新しい設定 → 設定ドキュメントの更新が必要
ステップ 2 — 影響を受けるセクションを更新
変更された領域ごとに:
- 変更されたコードを読む
- 対応するドキュメントセクションを見つける
- 現在のコードに一致するようにドキュメントを更新する
- ドキュメントセクションが存在しない場合は作成する
- コードが削除された場合は、ドキュメントから削除するか非推奨としてマークする
<ハードゲート> ドキュメントコンテンツを黙って削除してはいけません。コードが削除された場合は、ドキュメントセクションを「[コミット]で削除」とマークするか、ドキュメントセクションを削除する前にユーザーに確認を取ってください。 </ハードゲート>
ステップ 3 — 変更履歴エントリを生成
rune:git changelog に委譲し、前回のドキュメント更新以降のコミットから変更履歴エントリを生成する。
ステップ 4 — クロスドキュメント一貫性パス
クロスドキュメント一貫性は、2番目に多いドキュメント問題を防ぎます:存在するが互いに矛盾するドキュメント。
任意のドキュメントを更新した後、すべてのプロジェクトドキュメント間の一貫性を検証します:
| チェック | ファイル | 比較内容 |
|---|---|---|
| バージョン番号 | 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スキーマ、TypeScript型、Pydanticモデルから)
- レスポンス: 形状(戻り値の型またはレスポンスヘルパーから)
- 認証: 必要か?(ミドルウェア
authMiddleware、@UseGuardsなどを検出) - 説明: JSDoc/docstringから(利用可能な場合)
ステップ 3 — APIリファレンスを生成
Markdownとしてフォーマット:
# APIリファレンス
## 認証
[認証メカニズムの説明]
## エンドポイント
### `POST /api/auth/login`
**説明**: ユーザーを認証しトークンを返す
**認証**: なし
**リクエストボディ**:
| フィールド | 型 | 必須 | 説明 |
|-------|------|----------|------|
| email | string | はい | ユーザーのメールアドレス |
| password | string | はい | ユーザーのパスワード |
**レスポンス** (200):
```json
{ "token": "string", "refreshToken": "string" }
エラー:
- 401: 無効な認証情報
- 422: バリデーションエラー
#### ステップ 4 — 出力
`docs/API.md` またはプロジェクト固有の場所に保存。OpenAPIが要求された場合は `openapi.yaml` を生成。
### Changelog モード
#### ステップ 1 — Gitに委譲
`rune:git changelog` を呼び出して、コミットをタイプごとにグループ化し、Keep a Changelog形式でフォーマット。
#### ステップ 2 — 拡張
生の変更履歴にコンテキストを追加:
- PR番号を実際の説明にリンク
- 関連する変更を機能ヘッダーの下にグループ化
- 破壊的変更を目立つように強調表示
#### ステップ 3 — 出力
`CHANGELOG.md` に追加または更新。
## 出力形式
### Init モード出力
プロジェクトルートに生成されるファイル:
- `README.md` — クイックスタート、機能、技術スタック、構造、設定、開発コマンド
- `ARCHITECTURE.md` — 概要図、主要な決定、モジュールマップ、データフロー(10ファイル以上の場合)
- `docs/API.md` — メソッド、パス、パラメータ、レスポンス、認証を含むエンドポイントリファレンス(ルートが検出された場合)
### Update モード出力
変更後のドキュメントセクションと変更概要:
Docs 更新レポート:
- 更新: [変更されたドキュメントセクションのリスト]
- 追加: [新しいコード用の新しいセクション]
- フラグ: [削除されたコードを参照する古いセクション]
- 変更履歴: [CHANGELOG.md に追記されたエントリ]
### API モード出力
`docs/API.md` — エンドポイントごとのMarkdownリファレンス:
METHOD /path/:param
説明: [JSDoc/docstringから] 認証: [必須/なし] リクエスト: [パラメータ、クエリ、ボディテーブル] レスポンス: [ステータスコード付きの形状] エラー: [エラーコードと説明]
### Changelog モード出力
`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: マージし、上書きしない — カスタムセクションを検出する |
| コード変更後に古いドキュメントが残る | 高 | Updateモードで差分を検出し、影響を受けるセクションを更新する |
| リクエスト/レスポンス形状が間違っているAPIドキュメント | 高 | 記憶からではなく、Zod/Pydantic/TypeScript型から抽出する |
| クイックスタートセクションの欠落 | 中 | 制約4: すべてのREADMEにクイックスタートがある |
| 孤立したPRリンクがある変更履歴 | 低 | リンクする前にPR番号が存在することを検証する |
| クロスドキュメントの不整合(READMEがXと言っている、CLAUDE.mdがYと言っている) | 高 | ステップ7: クロスドキュメント一貫性パス — 統計、バージョン、機能リストがすべてのドキュメント間で一致することを確認する |
| 一方のドキュメントのみを更新し他方を更新しない(統計のずれ) | 高 | ドキュメント更新後、関連するすべてのドキュメントの古い統計をスイープする — 特に README ↔ CLAUDE.md ↔ ランディングページ |
## 完了条件
### Init モード
- コードベースが scout でスキャンされた
- README.md がクイックスタート、機能、技術スタック、構造を含めて生成された
- ARCHITECTURE.md が生成された(10ファイル以上の場合)
- API.md が生成された(ルートが検出された場合)
- カバレッジレポートがユーザーに提示された
### Update モード
- 前回のドキュメント更新以降の変更が検出された
- 影響を受けるドキュメントセクションが更新された
- 変更履歴エントリが生成された
- 更新レポートがユーザーに提示された
### API モード
- APIフレームワークが検出された
- すべてのエンドポイントがメソッド、パス、リクエスト、レスポンスとともに抽出された
- APIリファレンスがMarkdownで生成された
- docs/API.md に保存された
### Changelog モード
- コミットがタイプごとにグループ化された
- Keep a Changelog形式でフォーマットされた
- CHANGELOG.md が更新された
## コストプロファイル
インプット約2000〜5000トークン、アウトプット約1000〜3000トークン。Sonnet — ドキュメント作成にはコードパターンの理解が必要ですが、深いアーキテクチャ推論は必要ありません。