codewiki-generator

Codewiki Generator

概要

指定したリポジトリについて、DeepWiki 風のコードファーストなドキュメントサイトを生成します。出力先は codewiki/ ディレクトリで、VitePress の設定と自動生成されたサイドバーが含まれます。ドキュメントにはプロジェクトの現在の状態を反映し、単に機能を説明するのではなく、システム設計の根拠を優先して説明する必要があります。

ワークフロー

0) 言語の希望を確認する

ユーザーに次のように尋ねます：「ドキュメントは何語で作成しますか？（例：English、中文、日本語など）」 IF ユーザーが言語を指定した場合 THEN 指定された言語を保存し、生成するすべての文章に適用します。 ELSE IF ユーザーが言語を指定しなかった場合 THEN 英語をデフォルトとします。

1) まずコードベースを調査する（コード > ドキュメント）

• ソースファイル、設定ファイル、ビルド／テストパイプライン、エントリーポイント、アーキテクチャ関連のディレクトリをスキャンします。
• 既存のドキュメント（例：README、docs/）は補助的な手がかりとして扱います。
• 最終的な情報源として、コードに基づく証拠を優先します。
• ドキュメントとコードに食い違いがあれば、特定して報告します。

2) コードベースを分析 → 構造化メタデータ

アナライザースクリプトを実行してコードベースをスキャンし、構造化メタデータを生成します。<skill-root> は、この SKILL.md が置かれているディレクトリを指します。

python3 <skill-root>/scripts/codewiki_analyze.py \
  --repo-root <repo-root> \
  --out-dir codewiki \
  --force

このコマンドは、次の出力を生成します。

• deps.json、entrypoints.json、evidence.json、doc_plan.json、および（ctags が利用可能な場合は）symbols.json を含む codewiki/.meta/ ディレクトリ。
• カバレッジと信頼度の低いページを記載した codewiki/quality-report.md。
• VitePress の設定用スキャフォールディング（プレースホルダーの .md ファイルは含みません）。

注：この手順では、プレースホルダーの .md ファイルは生成されません。LLM がステップ 4 でドキュメントの内容を直接作成します。 注：既存の Markdown ファイルで参照されている画像は codewiki/assets/ にコピーされます。

3) ドキュメントの構成を動的に決定する

• 必要最小限のページをすべて含めます。
• 対応するコード上の証拠がある場合に限り、条件付きモジュールを追加します。
• プロジェクトの規模と複雑さに応じて、ページを分割または統合します。
• references/structure-and-heuristics.md に記載されたガイドラインに従います。
• 生成するすべてのドキュメントでは、ディレクトリ名とファイル名を小文字にします。

4) ドキュメントを作成する（コードファースト、ビジュアルファースト）

codewiki/.meta/doc_plan.json を読み込み、計画された各ページを処理します。

• IF ページに裏付けとなる証拠がない OR コードベースとの関連性が低い THEN そのページはスキップします。
• ELSE 実際の内容を含むページに限り、.md ファイルを作成します。

作成ガイドライン：

• すべての文章には、ステップ 0 で決定した言語を使用します。
• コードスニペット、ファイルパス、技術用語の元の表記を維持します。
• すべてのページの冒頭に、見出しではなく、コントラストを抑えた # Related Code ブロック（フェンス付きの text ブロック）を置きます。
• 図（コンテキスト図、クラス図、シーケンス図、コンポーネント図、データフロー図）には Mermaid を使用します。
• Mermaid で安全な構文に従います。ノード ID はシンプルにし、ラベル内の /、()、: を避け、node[plain label] の形式を優先します。
• 設計上の選択、トレードオフ、制約の背景を説明します。
• 根拠に基づいた見解を示し、強み、技術的負債、または「コードの不吉な臭い」を明らかにします。
• 概念を具体的なファイルパス、クラス、またはエントリーポイントに結び付けます。
• 正確であれば、既存の画像や図を再利用します。
• Markdown のリンターで問題が起きにくい書き方を保ちます。見出しの一貫性、末尾の空白がないこと、適切なリスト形式を維持します。

根拠に結び付けられたページテンプレートの詳細については、references/doc-templates.md を参照してください。

5) サイドバーを更新してサイトを実行する

ドキュメントを生成した後、実際のファイルを反映するようにサイドバーを更新します。

python3 <skill-root>/scripts/codewiki_bootstrap.py \
  --repo-root <repo-root> \
  --out-dir codewiki \
  --refresh-sidebar

ドキュメントの依存関係をインストールします（Mermaid のサポートはデフォルトで有効です）。

npm --prefix codewiki install

ドキュメントサイトを起動します。

npm --prefix codewiki run docs:dev

代替の起動コマンド（事前に npm install を実行しない場合）：

npx -p vitepress -p vitepress-plugin-mermaid -p mermaid vitepress dev codewiki

6) オプションのワークフローを提示する

サイトの準備が完了したら、利用可能なオプションをユーザーに案内します。

「ドキュメントサイトの準備ができました！次のことができます。

• オプション A：Cloudflare Pages にデプロイ — サイトを公開 URL で公開します
• オプション B：多言語対応（i18n）を追加 — ドキュメントを別の言語に翻訳します

いずれかをご希望の場合はお知らせください。」

オプションのワークフロー

コアとなるドキュメント生成プロセスの完了後に、これらのワークフローを実行できます。

オプション A) Cloudflare Pages にデプロイする

wrangler CLI を使用して、ドキュメントサイトを Cloudflare Pages にデプロイします。

実行条件：ユーザーがドキュメントのデプロイ、公開、またはホスティングを依頼した場合。

参照先：詳細な手順（wrangler のインストール、ログインの確認、ビルドプロセス、デプロイ、公開 URL を使った index.md の更新を含む）については、references/deploy-cloudflare.md を参照してください。

オプション B) 多言語対応（i18n）を追加する

既存のドキュメントを第 2 言語に翻訳し、VitePress の言語切り替え機能を設定します。

実行条件：ユーザーが翻訳、多言語対応、または国際化（i18n）のサポートを依頼した場合。

参照先：詳細な手順（ディレクトリ構成、VitePress の locales 設定、翻訳ガイドラインを含む）については、references/i18n-setup.md を参照してください。

品質基準（妥協不可）

• ビジュアル優先：大量のテキストブロックよりも図を優先します。
• 洞察に富む内容：仕組みの説明だけでなく、設計意図も説明します。
• 明確な見解：アーキテクチャの強みと特定されたリスクを強調します。
• リンクを付ける：重要な概念には、具体的なファイルやクラスを必ず参照します。
• コード優先：コードベースを信頼できる情報源とし、ドキュメントは補足説明として提供します。

リソース

scripts/

• codewiki_analyze.py：コードベースをスキャンし、.meta/*.json メタデータファイルを生成します。
• codewiki_bootstrap.py：codewiki/ ディレクトリを作成し、参照されている画像をコピーして、サイドバーを生成します。

references/

• structure-and-heuristics.md：モジュールの選定とシグナルの特定に関するルールが記載されています。
• doc-templates.md：すべてのページタイプに対応する、根拠へのリンク付きの包括的なテンプレートが用意されています。
• deploy-cloudflare.md：Cloudflare Pages にデプロイするワークフローの詳細を説明します。
• i18n-setup.md：多言語対応の設定プロセスについて説明します。

assets/

• vitepress/：最小限の VitePress 設定とランディングページのテンプレートが含まれています。