repo-wiki-skill

リポジトリ Wiki

概要

大規模なリポジトリ向けに、正確で複数ページからなる包括的な Markdown Wiki パッケージを作成します。このスキルは、モノレポ、フレームワーク、コンパイラー、プラットフォーム、サービス、または数十万行のコードを含む製品など、メンテナーに負担がかかるほど大規模なコードベースに最適化されています。推測よりファイルから得られる根拠を優先し、リポジトリ全体を実用的な粒度で網羅して、コアコード、設計上の判断、アルゴリズム、トレードオフを専用ページで説明します。

運用原則

• ユーザーが明示的に単一ファイルを求めない限り、巨大な Markdown ファイルを1つ作るのではなく、独立したWiki パッケージディレクトリを作成します。
• パッケージディレクトリの既定値は wiki/ です。すでに wiki/ が存在する場合は、maintainer-wiki/ など、明確で競合しない名前を選びます。
• 生成する Wiki は、既存のドキュメント製品から独立させます。既存の docs/、website/、site/、または製品のドキュメントアプリに混ぜたり、その隣に複製したりしないでください。
• リポジトリを個別のファイルではなく、システムとして読み解きます。
• 大規模で複雑なコードベースを把握する必要があるメンテナーや、コードを学ぶ人を主な対象とします。
• 網羅性を確保しつつ、深さは選択します。重要なコードパス、意外性のあるコードパス、リスクの高いコードパスは詳しく説明し、定型コードや生成コードは簡潔にまとめます。
• 主張の根拠として、具体的なファイルパス、シンボル、設定名、スクリプト、テスト、確認された動作を示します。
• 根拠が不十分な場合は、不確実であることを明記します。
• アーキテクチャ、データフロー、状態機械、依存関係グラフ、アルゴリズムを明確にする場合は、Mermaid と KaTeX を使用します。プレーンな Wiki 出力では Mermaid を優先します。Graphviz（DOT）はビルド時プラグインが必要なため、ユーザーがドキュメントサイトを明示的に求めた場合に限り使用します。
• 数値による規模の目標は最低ラインであり、目標そのものではありません。品質チェッカーを通過することは必要ですが、それだけでは不十分です。反復的、テンプレートに過度に依存した、ファイル一覧中心、または件数合わせの文章を書かないでください。
• ファイル名だけから Wiki を一括生成しないでください。スクリプトは棚卸しや品質チェックに使用できますが、アーキテクチャ、サブシステム、アルゴリズム、メンテナー向けガイダンスは、実際のソースを読み、設計を検討したうえで執筆します。
• スクリプトでナビゲーションや一覧をひな形として作成することはできますが、中心となる説明文を作成してはいけません。広範な補助ページを作成する前に、ソースの根拠に基づいてアーキテクチャページを手作業でまとめます。
• ドキュメントサイトへのデプロイは任意です。ユーザーが Wiki を Rspress／docs サイトとして公開するよう求めた場合は、references/rspress_docs_site.md を読みます。それ以外の場合は、メインのワークフローにサイト設定を含めないでください。

標準ワークフロー

1. 対象範囲と出力先を決める

以下を確認するか、推定します。

• リポジトリのルートと、対象とするサブディレクトリ。
• 出力するパッケージディレクトリ。指定がなければ wiki/ を作成します。そのパスがすでに存在する場合は、maintainer-wiki/ または別の明確で競合しない Wiki パッケージ名を使用します。
• ユーザーが指定した場合は、希望する言語と対象読者。

指定がなければ、リポジトリを学ぶ人や新任メンテナーを対象とする、複数ページの Wiki パッケージを作成します。

Wiki は独立したパッケージとして作成する必要があります。対象リポジトリにすでに docs/、website/、または別のドキュメントアプリが存在する場合は、それらに手を加えず、独立した wiki/ パッケージを作成します。リポジトリにすでに wiki/ が存在する場合は、maintainer-wiki/、repo-wiki/、または同様に明確な名前を使用し、競合を避けます。

2. リポジトリマップを作成する

詳細に読み込む前に、高速なローカル調査を行います。rg --files、find、言語固有のメタデータコマンドを優先してください。コンテキストにすべてのファイルを読み込まずに構造化された一覧を生成するには、必要に応じて Node で scripts/repo_snapshot.cjs を実行します。

推奨される最初の調査：

node <skill_dir>/scripts/repo_snapshot.cjs <repo_root> --output /tmp/repo-snapshot.md

少なくとも次の項目を調べます。

• ルートのドキュメント：README*、CONTRIBUTING*、CHANGELOG*、LICENSE*、docs/、wiki/。
• パッケージとビルドのメタデータ：package.json、pnpm-workspace.yaml、Cargo.toml、go.mod、pyproject.toml、requirements*.txt、pom.xml、build.gradle、Makefile、CI 設定。
• ソースのルート：src/、lib/、app/、packages/、crates/、cmd/、internal/、pkg/、tests/、examples/。
• 設定：バンドラー、リンター、フォーマッター、テストランナー、コード生成、デプロイ、Docker、環境変数の例。
• 生成物、ベンダーコード、ロックファイル、ビルド、キャッシュの各ディレクトリ。関連する場合を除き、詳しく読み込まずに特定します。

3. Wiki の計画を立てる

ページを作成する前に、Wiki パッケージの簡潔な計画を作成します。

• index.md：ナビゲーションハブ、対象読者、読む順序、エグゼクティブサマリー。
• repository-map.md：トップレベルのディレクトリとパッケージの案内。
• architecture/：アーキテクチャの概要と主要なランタイムフロー。
• modules/：モジュール、パッケージ、ディレクトリの詳細解説。単純なモジュールには 1 ファイルを使用し、複雑なモジュールには複数ページを含むサブディレクトリを使用します。
• subsystems/：コアドメイン、アルゴリズム、状態、永続化、ネットワーク、セキュリティ、プラグイン、コンパイラーの各サブシステム。単純なサブシステムには 1 ファイルを使用し、複雑なサブシステムには複数ページを含むサブディレクトリを使用します。
• development/：セットアップ、ビルド、テスト、リンター、デバッグ、リリース、CI、運用。
• maintainer-playbook.md：よくある変更手順、安全に編集できる箇所、リスク、トラブルシューティング。
• reference/：用語集、ファイルインデックス、シンボルインデックス、未解決の疑問。

この構成はリポジトリに合わせて調整します。ただし、独立した Wiki パッケージ内に、複数ページからなるナビゲーション可能な構成でまとめてください。

まとめて執筆する前に、リポジトリの実際の設計の中心を特定します。主なランタイムパス、コアデータモデル、境界インターフェース、設定モデル、永続化／キャッシュ／ネットワーク層、拡張ポイント、動作を定義するテストを確認してください。まず、それらを説明する名前付きのアーキテクチャページまたはサブシステムページを作成します。ファイルインデックスとモジュール一覧はその後に作成し、Wiki の中心にならないようにします。

作業中は、簡潔な analysis-plan.md または同等の作業用アウトラインを作成して維持します。設計の中心、各中心についてすでに読んだソースファイル、主な仮説、それらを説明する Wiki ページを記載します。ユーザーがプロセスに関するメモを求めない限り、最終的な Wiki からこの作業用ファイルを削除するか、含めないでください。

4. 重要度に応じて深く読む

詳細な調査は、次の優先順位で進めます。

1. 公開 API、エントリーポイント、CLI コマンド、サーバールート、プラグインフック、エクスポートされたパッケージ。
2. コアドメインモジュールとオーケストレーションコード。
3. アルゴリズム、パーサー、コンパイラー、スケジューラー、状態機械、キャッシュ、並行処理、セキュリティ、永続化、ネットワーク境界、エラー処理。
4. 期待される動作とエッジケースを明らかにするテスト。
5. ビルド、CI、リリース、開発者向けツール。
6. 例、フィクスチャ、マイグレーション、生成物、レガシーコード。

重要な各サブシステムについて、次の項目を特定します。

• 主要なファイルとシンボル。
• 責務と境界。
• 入力、出力、副作用、不変条件。
• 正常系と失敗系のパス。
• 設計上のトレードオフと、現在のコード構成に至ったと考えられる理由。
• テスト、または不足しているテスト。
• 保守上の注意点と、安全に変更できる箇所。

各詳細解説ページについて、設計品質を示す次の観点をすべて裏付けられるだけの実装とテストを読み込みます。設計／アーキテクチャ、制御フローまたはデータフロー、トレードオフまたは意思決定、不変条件または契約、失敗モード、テストによる根拠、保守上のリスクです。ソースコードからこれらの観点の大半を裏付けられない場合は、内容を水増しせず、そのページのカバレッジを中程度に下げてください。

5. Wiki ディレクトリを作成する

references/wiki_structure.md のアウトラインを、標準のディレクトリ構成として使用します。無関係なセクションを無理に含めず、リポジトリに合わせてファイル名と見出しを調整してください。

初稿は、次の順序で作成します。

1. index.md、repository-map.md、アーキテクチャの概要、メンテナープレイブック。
2. エンドツーエンドのランタイムフローと、最も難しいサブシステムを5〜15個。
3. 複雑なモジュールのディレクトリ。それぞれに設計、フロー、テスト、メンテナー向けのページを用意します。
4. 補助的なモジュールページ、開発ページ、用語集、インデックス。

内容がほぼ同じファイルページを何百個も生成することから始めないでください。ファイルインデックスを作成してよいのは、概念的なページが役立つ内容になった後に、ナビゲーション補助として使う場合のみです。

ページを生成済みと記載したり、番号付きの保守セクションを繰り返し含めたり、「メンテナーの確認が必要」といった一般的な表現で分析の代わりにしたりしないでください。コードから確認できることを説明した後にのみ、範囲を限定した未解決の質問を示してください。

Wiki パッケージには、通常、次の内容を含めます。

• 完全なページインデックスと推奨する読み進め方を含む、ルートの index.md。
• リポジトリマップとディレクトリ案内。
• ローカル開発向けクイックスタート。
• 図を含むアーキテクチャの概要。
• エンドツーエンドの実行パスのページ。
• モジュール、パッケージ、ディレクトリの詳細解説ページまたはサブディレクトリ。
• コアサブシステムのページまたはサブディレクトリ。
• 重要なアルゴリズム、データ構造、不変条件。
• 設定、ビルド、テスト、リリース、運用に関するページ。
• 一般的な変更手順を含むメンテナープレイブック。
• トラブルシューティング、用語集、ファイルインデックス、シンボルインデックス、未解決の質問。

最小規模と構成の目標

短い概要を作成しないでください。このスキルは、保守担当者が充実したドキュメントを必要とするコードベースを対象としています。品質チェッカーは、次の 2 つのモードに対応しています。

ダイナミックモード（推奨）： プロジェクトのコード行数を --loc で渡すと、スクリプトが比例しきい値を計算します。これにより、プロジェクトの規模に対して Wiki が大きすぎたり小さすぎたりするのを防げます。

node <skill_dir>/scripts/wiki_quality_check.cjs <wiki_dir> --loc <project_loc>

この計算式では、単語数（LOC の約 4 倍）、ファイル数（LOC 2,000 行につき約 1 ファイル）、ファイル参照数（LOC の約 7%）、詳細解説ページ数を比例させて算出します。水増しを防ぐチェックの基準は固定です。

言語に関する注意（CJK／英語以外の Wiki）： 単語数と空白でない行数の目標は、約 1 トークンを 1 単語として数えられる英語の文章向けに調整されています。中国語、日本語、韓国語の文章は、文字あたりの情報密度がはるかに高いため、同じアーキテクチャを適切に解説しても、単語数は大幅に少なくなります。チェッカーは CJK の比率を自動検出し、それに応じて単語数と行数の目標を緩和します（CJK のみの Wiki では、英語の目標単語数のおよそ半分になります）。構成、ファイル参照、詳細解説、水増し防止のしきい値は言語に左右されず、緩和されません。緩和後も CJK の Wiki が単語数の条件を満たせない場合がありますが、水増し防止チェックに問題がなく、設計の深さが十分であれば問題ありません。単語数の目標に達するために文章を水増ししないでください。それは、このスキルが明確に禁じている、品質を犠牲にして指標を満たす行為です。

プロファイルモード（非常に大規模なプロジェクト向けの基準値）：

プロファイル	典型的な条件	最小目標
大規模	相当規模のアプリケーション／ライブラリ、数万 LOC	Markdown ファイル 30 個以上、250,000 語以上、空白でない行 15,000 行以上、見出し 1,200 個以上、バッククォートで囲まれた固有のファイル参照 1,800 個以上
超大規模	数十万 LOC、モノレポ／プラットフォーム／フレームワーク	Markdown ファイル 80 個以上、600,000 語以上、空白でない行 35,000 行以上、見出し 2,600 個以上、バッククォートで囲まれた固有のファイル参照 4,500 個以上
極めて大規模	非常に大規模なモノレポ、または複数製品からなるシステム	Markdown ファイル 150 個以上、1,200,000 語以上、空白でない行 70,000 行以上、見出し 5,200 個以上、バッククォートで囲まれた固有のファイル参照 9,000 個以上

これらのプロファイルは、非常に大規模なプロジェクト向けの参考基準です。ほとんどのリポジトリでは、比例した目標を得るために --loc モードを使用してください。チェッカーは参考用のツールであり、必須条件ではありません。実際の品質基準は、設計の深さ、アーキテクチャの明確さ、保守担当者にとっての有用性です。

リポジトリの規模が分からない場合は、簡単に LOC を数えて（例：find src -name '*.rs' | xargs wc -l）、--loc を使用してください。規模の大きいトップレベルディレクトリごとに、専用のセクションまたはページを作成するか、既存のものに含めてください。複雑なモジュールや中核サブシステムごとに、1 つの長すぎるページにまとめるのではなく、複数のテーマ別ページを置いたサブディレクトリを優先してください。重要なファイルやシンボル、仕組み、テスト、障害モード、保守担当者向けの注意事項を含めてください。一般的な文章の水増しよりも、不足しているページの追加や、根拠に基づく解説を優先してください。

6. 網羅性と正確性の確認

完成前に、以下を確認してください。

• Markdown ファイルが1つだけではなく、Wiki パッケージが存在している。
• index.md から、すべての主要な Wiki ページにリンクされている。
• 最上位の各ディレクトリについて、説明があるか、生成物／ベンダー／キャッシュ／無関係なものとして明示的に分類されている。
• 主要な各パッケージ／モジュールに、少なくとも簡潔な目的の説明がある。
• コアとなるエントリーポイントと実行経路が、エンドツーエンドでたどられている。
• 動作に関する記述が、コード、テスト、設定、またはドキュメントによって裏付けられている。
• 図が文章による説明と一致している。
• Mermaid／Graphviz／KaTeX のブロックが、構文上妥当である。
• Wiki で事実と推論が区別されている。
• コア概念を扱うページが、表やファイル一覧で代用されていない。設計、データ／制御フロー、トレードオフ、不変条件、障害モード、テスト、安全に変更できる箇所を説明している。
• 繰り返される定型文、番号付きの汎用セクション、コピーされた段落は、深みのある内容とは見なされません。リポジトリ固有の分析に書き換えるか、削除してください。

Wiki パッケージに対して Node 品質ゲートを実行し、失敗した場合は Wiki を拡充してください。

node <skill_dir>/scripts/wiki_quality_check.cjs <wiki_dir> --loc <project_loc>

非常に大規模なプロジェクトの参考基準としてのみ、--profile large|huge|massive を使用してください。規模に応じた期待値には、--loc を優先してください。チェッカーは、Markdown ファイル数、単語数、空白以外の行数、見出し数、H2 セクション数、バッククォートで囲まれた一意なファイル参照の数、フェンス付きコードブロック数、表の数、詳細解説ページ数、繰り返しの上限、内容の薄い表現の禁止、インデックスページの占有率の上限を検証します。

ページが詳細解説ページとして認められるには、十分な単語数、ファイル参照数、異なる設計品質の指標が必要です。これは意図的な仕様です。汎用的な説明しかない architecture.md という名前のページは、品質ゲートを通過しないようになっています。

チェッカーを通過しても、人によるレビューや後続レビューで Wiki が表面的だと指摘された場合は、実際の失敗として扱ってください。数値の最適化をやめ、コアとなるソースコードの経路を読み直し、アーキテクチャと保守を中心に Wiki を再設計し、弱いページを擁護するのではなく置き換えてください。

図と数式

図は控えめに、ただし具体的に使ってください。

Mermaid

アーキテクチャ、シーケンス、フロー、状態、依存関係の図には Mermaid を使ってください。

```mermaid
flowchart TD
  CLI["CLI entrypoint"] --> Core["Core orchestration"]
  Core --> Adapter["Platform adapter"]
  Core --> Tests["Behavior covered by tests"]

### Graphviz

Use Graphviz DOT only when the user has requested a documentation site (Rspress), since it requires `rspress-plugin-viz` to render. Prefer Mermaid for plain Markdown wiki output. Graphviz is useful when clustered subgraph layout or complex dependency visualization is clearer than Mermaid:

```markdown
```dot
digraph G {
  rankdir=LR;
  subgraph cluster_core { label="core"; parser; planner; executor; }
  parser -> planner -> executor;
}

### KaTeX

Use KaTeX for formulas, complexity, scoring, or algorithmic invariants:

```markdown
The cache hit ratio is $H = \frac{hits}{hits + misses}$, and the lookup path is expected $O(1)$ under normal hash distribution.

出力品質の基準

優れたリポジトリ Wiki パッケージは、次の条件を満たします。

• index.md とアーキテクチャ概要を読めば、新規参加者がリポジトリの機能を説明できる。
• 保守担当者が、巨大な単一ドキュメントを読み通すことなく、よくある変更に適したページを見つけられる。
• 重要なコードがどのファイルにあるかだけでなく、その構成になっている理由を説明している。
• わかりにくい結合、不変条件、エッジケースを明示している。
• ナビゲーションに役立つだけのファイル／シンボル参照が含まれている。
• 内容の水増しをせず、該当する最低限の規模と構造の目標を満たすか、それを上回っている。
• 解説なしの生のファイルツリーを並べていない。
• 生成されたファイルインデックス、繰り返される保守上の助言、汎用的なページテンプレートを、設計分析の代わりに使っていない。
• 架空のアーキテクチャを述べていない。確証がない場合は、どのような証拠があるか、何が不明なままかを明記している。

バンドルリソースの使用

• Node で scripts/repo_snapshot.cjs を使い、リポジトリの一覧、言語／設定の概要、読み込み候補の計画を作成してください。
• Node で scripts/wiki_quality_check.cjs を使い、生成された Wiki パッケージが小さすぎたり、構成が不十分だったりしないことを確認してください。
• 最終的な Wiki パッケージの構成を作成またはレビューする際は、references/wiki_structure.md を読んでください。
• ユーザーが Wiki を Rspress または静的ドキュメントサイトにすることを明示的に依頼した場合に限り、references/rspress_docs_site.md を読んでください。