wiki

Wiki の生成

リポジトリを読み込み、コードの動作と各要素の連携を説明する、相互に関連したドキュメントページを作成します。出力は Markdown ファイルを格納した droid-wiki/ ディレクトリです。droid wiki-upload を使って Factory にアップロードします。

1. リポジトリを調査する

何かを書く前に、コードベースの全体像を把握します。調査は、構造のスキャンとコードの詳細なスキャンの2段階で行います。

パス1：構造のスキャン

次のファイルを読みます（存在する場合）。

• README.md、AGENTS.md、CONTRIBUTING.md — プロジェクトの目的と規約
• package.json、Cargo.toml、go.mod、pyproject.toml — 依存関係とスクリプト
• docs/ ディレクトリ — 既存のドキュメント
• エントリポイント（src/index.ts、main.go、app.py など）— アプリケーションの起動方法
• CI/CD の設定（.github/workflows/、.gitlab-ci.yml、Jenkinsfile、azure-pipelines.yml など）
• ビルドツールの設定（webpack.config.*、vite.config.*、Makefile、build/、Gulpfile.* など）
• Lint／品質チェックの設定（eslint.config.*、カスタム Lint プラグイン、rustfmt.toml、.golangci.yml など）
• プロジェクトのルートと主要なサブディレクトリの一覧

次の項目を整理します。

• プロジェクトの機能 — 目的を1、2文で説明
• 主要なサブシステム — コードベースの主な領域（例：API 層、データベースモデル、CLI、フロントエンドコンポーネント）
• 主要なデータフロー — システム内でのデータの流れ（リクエスト → ハンドラー → データベース → レスポンス）
• 外部依存関係 — データベース、API、メッセージキュー、サードパーティサービス
• ビルドとテストのコマンド — プロジェクトのビルド、テスト、実行方法

パス2：コードの詳細なスキャン

構造のスキャンでは、ディレクトリ名や設定ファイルからわかる情報を確認します。詳細なスキャンでは、コード自体を見なければわからない機能、ドメイン、能力を明らかにします。構造のスキャンで見落としたトピックがないか、コードベースに現れる手がかりを調べます。

• 定数ファイルで機能フラグ名を検索します。各フラグは、個別に説明する価値のある機能を表していることがよくあります。
• フロントエンドのルート定義とページコンポーネントを調べます。各ルートグループは、ユーザー向けの機能です。
• API エンドポイントのグループを調べます。各コントローラーまたはルーターのファイルは、ドメイン領域を表しています。
• src/features/、src/modules/、src/domains/、または同等のディレクトリを確認します。名前と内容から、製品の機能がわかります。
• サービスクラス、イベントハンドラー、ジョブ／ワーカーの定義を調べます。これらから、バックグラウンドシステムがわかります。
• 明らかなトップレベルの名前には対応しない、ドメイン固有のディレクトリを確認します。

目標は、Wiki で扱うべきトピックの完全な一覧を見つけることです。構造のスキャンで骨格を把握し、詳細なスキャンで中身を補います。「Analytics」のような機能は、トップレベルの専用ディレクトリがなくても、src/features/analytics/ の中にあったり、機能フラグや API エンドポイントの組み合わせから見つかったりすることがあります。

サブシステムの徹底的な洗い出し

2段階のスキャンを終えたら、見落としたサブシステムがないか、すべてのトップレベルのソースディレクトリと、その1階層下を確認します。独自のサービス、モジュール、または機能を含む各ディレクトリについて、次のいずれかに分類します。

• ティア1 — ほとんどのコントリビューターが関わる中核的なサブシステム。専用ページで詳しく説明します。
• ティア2 — 重要ですが、対象が専門的なサブシステム。専用ページで簡潔に説明します。
• ティア3 — ニッチなもの、または薄いラッパー。ディレクトリへの参照を含め、「その他のサブシステム」ページの1段落で説明します。

小規模なリポジトリでは、ドメイン別のページは数ページで十分な場合があります。大規模なリポジトリでは、コードベースに見合う数のページを作成します。任意の上限は設けず、実際の構造に応じて網羅範囲を決めます。

見落とされやすい領域

ソースツリーを確認した後、次のような、よく見落とされる領域もチェックします。

• カスタムの lint／分析ルール — プロジェクト固有の規約を適用するプラグインや設定
• 自動化ワークフロー — CI/CD、ボット、スケジュールされたジョブ、コード生成スクリプト
• CLI または開発ツール — 内部ツールや、scripts/、tools/、bin/ 内のスクリプト
• テスト基盤 — 標準のテストランナー以外のカスタムテストフレームワーク、フィクスチャ、自動化ハーネス
• 複数言語のコンポーネント — リポジトリに 2 つ目の言語のコードがある場合（例：TypeScript プロジェクト内の Rust CLI）、その内容を記録します

これらに重要な内容があれば、個別のページまたは関連ページ内のセクションとして取り上げます。

調査結果

調査の最後に、サブエージェントと共有する簡潔な調査コンテキストドキュメントを作成します。このドキュメントには、次の内容を含めます。

• リポジトリの概要 — プロジェクトの内容、技術スタック、全体的な構成を 3〜5 文で説明
• アーキテクチャの概要 — 主なコンポーネントとその接続関係
• 発見したトピック — 2 回のスキャンで見つかった機能、システム、アプリ、パッケージ、プリミティブの完全な一覧
• 主なパターン — コーディング規約、エラー処理のパターン、テストのパターン
• 用語集の候補 — スキャン中に確認したプロジェクト固有の用語
• ディレクトリと用途の対応表 — ソースディレクトリと各トピックの対応関係

網羅性の相互確認

計画に進む前に、独立した 2 つのトピック情報源を照合し、見落としがないことを確認します。

情報源 A：発見したトピック。 パス 1（構造スキャン）とパス 2（コードの詳細スキャン）で見つかったトピックです。複数のディレクトリにまたがり、単一のディレクトリには対応しない横断的な機能（例：「LLM 統合」は複数のパッケージにまたがり、「認証」はフロントエンド、バックエンド、CLI に関わる）も含みます。

情報源 B：ディレクトリの列挙。 リポジトリに該当する観点ごとに、対応するソースディレクトリで ls を実行し、すべてのサブディレクトリを列挙します。

• アプリの場合：apps/（またはリポジトリ内で相当するディレクトリ）以下のすべてのディレクトリを列挙
• パッケージの場合：すべてのワークスペースパッケージディレクトリを列挙
• 機能の場合：機能ディレクトリ（例：src/features/、packages/frontend/src/features/、またはリポジトリ内で機能を管理しているディレクトリ）以下のすべてのサブディレクトリを列挙
• システムの場合：サービスまたはモジュールのコードを含む、ソースの最上位ディレクトリを列挙

照合： 2 つの一覧を統合します。どちらかの一覧にある項目すべてについて、次のいずれかを判断します。

1. Wiki ページ — 項目を計画するページ（またはページ内のセクション）にします
2. 理由を添えて除外 — 具体的な理由を示して意図的に除外します（例：「空のディレクトリ — ソースファイルが 0 件」「非推奨 — テスト用フィクスチャのみ残存」「薄いラッパー — 親パッケージのページで説明」「内部ツール — 3 ファイルのみのため、単独ページにする価値はない」）

発見したトピックからは、ディレクトリだけでは把握できないもの（横断的な関心事、創発的なパターン）を見つけられます。ディレクトリの列挙からは、確認したファイルだけでは見つけられない機能を把握できます。この両方によって、網羅的な内容にできます。

説明のない見落としは認められません。重要なコードを含むソースディレクトリに対応する Wiki トピックがない場合、それは見落としであり、理由を明示する必要があります。

2. 目次を計画する

文章を書く前にページツリーを設計します。Wiki のコンテンツは、常設ページ、整理の観点、条件付きセクションの 3 層で構成されます。

常に含まれるページ

これらのページはすべての Wiki に次の順序で表示されます。

1. overview/ — 1 つのセクションにまとめた導入資料
   • index.md — プロジェクトの概要：その役割、利用者、クイックリンク
   • architecture.md — Mermaid 図を使ったシステムアーキテクチャ
   • getting-started.md — 前提条件、インストール、ビルド、テスト、実行
   • glossary.md — プロジェクト固有の用語とドメイン用語
2. by-the-numbers.md — コードベースの統計スナップショット（以下を参照）
3. lore.md — コードベースのタイムラインと歴史（以下を参照）
4. how-to-contribute/ — このコードベースでの作業方法
   • index.md — 作業の引き受け方、PR プロセス、レビューの期待事項、完了の定義
   • development-workflow.md — ブランチ、コーディング、テスト、PR、マージのサイクル
   • testing.md — フレームワーク、パターン、テストの実行方法、モックの使用方法、カバレッジ
   • debugging.md — ログ、よくあるエラー、トラブルシューティング手順書
   • patterns-and-conventions.md — エラー処理、コーディングスタイル、横断的な関心事
   • tooling.md — ビルドシステム、リンター、コードジェネレーター、CI ツール（リポジトリのツール自体が製品の場合は、トップレベルのセクションに昇格させます）

数字で見るコードベース

コードベースを定量的に概観できる、トップレベルの by-the-numbers.md ページを用意します。数値の新しさが読者に伝わるよう、ページの冒頭に「Data collected on [date]」という注記を記載してください。

次のセクションを含めます。

• 規模 — 言語別のコード行数（Mermaid の横棒グラフを使用）、ソースファイル数とテストファイル数、設定ファイル数、モノレポの場合はパッケージ／モジュール数
• アクティビティ — 週／月ごとのコミット数（直近の傾向）、過去 90 日間で最も頻繁に変更されたファイル／ディレクトリ（変更頻度の高い箇所）
• ボットによるコミット — ボットによる共同執筆者が記録されたコミットの割合（例：Co-authored-by: factory-droid[bot]、dependabot[bot]、github-actions[bot]、copilot[bot]）。インライン AI ツール（Copilot など）は Git の履歴に記録を残さないため、この割合は AI 支援作業の下限値です。何を集計対象にしているかを明確にしてください。
• 複雑さ — ディレクトリごとの平均ファイルサイズ、最も深いインポートチェーン、パッケージごとのエクスポートされたシンボル数

言語の内訳や、視覚化が有効なその他の統計には Mermaid の xychart-beta（横棒グラフ）を使用してください。Mermaid の pie グラフはレンダラーでサポートされていないため、使用しないでください。ファイル／ディレクトリの一覧には表を使用してください。

個々のコントリビューターの統計（コミット数の上位者、個人ごとのコード行数、ランキング）は絶対に含めないでください。 by-the-numbers ページの対象はコードベースであり、個人ではありません。個人別の指標は有害な比較を生み、チームのドキュメントにふさわしくありません。所有関係の対応付けについては、別途 maintainers.md ページで扱います。

他のページに記載する統計： この概要ページに加えて、関連する統計を既存のページにも織り込んでください。

• architecture.md に言語の内訳
• cleanup-opportunities/ セクションがある場合は、そこに変更頻度の高い箇所
• 各ドメインページに、サブシステムごとのファイル数、バスファクター（一意なコミッター数）、テストとコードの比率
• reference/dependencies.md に依存関係の数

Lore

コードベースがどのように進化してきたかを伝える、トップレベルの lore.md ページです。技術リファレンスではなく、物語としての歴史を記述します。「ここで何が、いつ起きたのか？」に答えます。

他のセクションとの境界：

• by-the-numbers.md ＝ 現在のスナップショット（今日のコードベースの状態）
• lore.md ＝ 年表と歴史（何が、いつ変わったのか）
• fun-facts.md ＝ ちょっとした豆知識（イースターエッグ、興味深い発見）
• background/ ＝ 技術的な根拠（なぜその決定がなされたのか）

すべての出来事、時代、マイルストーンには、日付または月を含める必要があります（例：「2023年3月」「2024年第4四半期」）。Git のコミットタイムスタンプ、タグの日付、ファイルの作成日から日付を特定してください。正確な日付がわからない場合は、関連する最初のコミットがあった月を使用してください。

以下のセクションを含めてください。

• 時代 — コードベースの歴史を3〜8つの主要な段階に分け、それぞれに短い説明と主な出来事の箇条書きを付けます。Git の履歴から判断してください。タグの日付、大規模なマージコミット、コントリビューターの傾向、ディレクトリの作成日を参考にします。例：「TypeScript への移行（2023年3月〜8月）：5か月かけてバックエンド全体が JavaScript から TypeScript に書き換えられました……」
• 最も長く存続している機能 — 多くのリファクタリングを経ても残り、現在も積極的に使われているコードやサブシステムです。最初に導入された時期と、これまでに経た変更の回数を含めてください。
• 非推奨になった機能 — 構築・使用された後に、削除または置き換えられた機能です。ディレクトリ名、README の記述、明らかな @deprecated 注釈、削除されたルートから特定します。機能の内容、導入時期、非推奨になった時期、置き換えたものを説明してください。
• 大規模な書き換え — 多数のファイルに影響した大きな変更です。変更前に何があり、何に置き換えられたのか、そしていつ行われたのかを説明してください。Git の履歴（大規模な PR、「migration」や「rewrite」を含むブランチ名）から判断します。
• 成長の軌跡 — コードベースが時間とともにどのように拡大したかを説明します。パッケージやアプリが追加された時期、Git ログからわかるコントリビューターの増加傾向を含めてください。

推測について： コミットから変更の「理由」がはっきりわからない場合は、「〜だったようです」「〜が理由で置き換えられた可能性があります」のように、断定を避けた自然な表現を使ってください。推測を示すための特別な書式は必要ありません。

構成上の観点

コードベースを深く調査する際に、整理のために使える観点は5つあります。リポジトリの実際の内容に応じて、任意に組み合わせてください。最低1つの観点が必要です。ほとんどのリポジトリでは、2〜3つを使用します。features の観点を強くおすすめします。新しいエンジニアにとって最も直感的な入口（「これは何をするものか？」）だからです。小規模なリポジトリでも、通常は文書化する価値のある、ユーザー向けまたは開発者向けの機能があります。個別の機能がない単一目的のライブラリの場合に限り、省略してください。

概念	デフォルトのラベル	別名	使用する場面
デプロイ可能な単位	applications/	services/、apps/	リポジトリに複数の独立したランタイムが含まれる場合
内部の構成要素	systems/	services/、modules/、subsystems/	単一のアプリやパッケージに対応しないアーキテクチャ上のコンポーネント
横断的な機能	features/	capabilities/、workflows/	複数のシステムにまたがる、ユーザー向けまたは開発者向けの機能
ワークスペースのパッケージ	packages/	libraries/、crates/、modules/	個別に文書化する価値のある共有ライブラリを含むモノレポ
基盤となるドメインオブジェクト	primitives/	core-concepts/、domain-models/、entities/	3つ以上のシステムに登場する型や概念（例：セッション、ユーザー、メッセージ）

ラベルの選び方： リポジトリ独自の用語に合わせてください。リポジトリに apps/ ディレクトリがある場合、セクション名には applications/ ではなく apps/ を使います。リポジトリで「services」と呼んでいる場合は、services/ を使います。デフォルトのラベルは、リポジトリに既存の命名規則がない場合の代替案です。

配置ルール：

• 各概念は、リポジトリの構造から見て適切な場所に配置してください。エージェントのロジックが packages/droid-core にある場合は、systems ではなく packages の下に記載します。
• systems の観点は、apps や packages に自然な配置先がないもの、つまり新たに生まれたアーキテクチャパターン、複数のパッケージにまたがるシステム、複数のディレクトリにまたがるインフラストラクチャを対象とします。
• 複数の観点に同じ内容を重複して記載しないでください。packages に記載する内容に関連するアプリのページでは、内容を繰り返さず、相互リンクを追加してください。

各観点を特定するためのヒューリスティクス：

• 独自のエントリーポイントとデプロイ方法がある場合は、アプリケーションです
• 他のパッケージからインポートされるワークスペースのパッケージである場合は、パッケージです
• 単一のパッケージには対応しない、内部ロジックと明確な境界を持つモジュールの場合は、システムです
• 3つ以上のシステムに登場する型や概念の場合は、プリミティブです
• 理解するために複数のシステムやアプリをたどる必要がある場合は、機能です

条件付きセクション

リポジトリを調査したうえで、判断に応じて以下を含めてください。該当しないものは省略します。

• api/ — リポジトリが REST、GraphQL、WebSocket、またはその他の API を公開している場合
• deployment/ — 複雑なデプロイプロセス（CI/CD、環境、ロールバック、インフラストラクチャ）がある場合
• security/ — 信頼境界に関わる重要な要素（認証、認可、シークレット、入力検証）がある場合
• background/ — リポジトリに重要な歴史（設計上の決定事項、落とし穴や危険箇所、移行の経緯）がある場合
• how-to-monitor/ — リポジトリが、ロギング、メトリクス、トレーシング、アラートのインフラストラクチャを備えたサービスとして稼働する場合
• cleanup-opportunities/ — リポジトリに不要なコード、蓄積した TODO や FIXME、肥大化したファイル、または古くなった依存関係がある場合。報告すべき内容が実際にある場合に限り含めてください（以下を参照）
• fun-facts.md — 隠し要素、誕生秘話、最古のコード、名前の由来

監視方法

この条件付きセクションでは、システムの動作状況を確認する方法を記載します。ログ、メトリクス、トレースのインフラストラクチャを備えたサービスとして稼働するリポジトリでのみ生成してください。ライブラリ、CLI ツール、パッケージには適用されません。

サブページ：

• logging.md — ログの出力先、ログのクエリ方法、ログレベルと規約、構造化ロギングのパターン、新しいログステートメントの追加方法
• metrics.md — 計測しているメトリクス、主要な SLI／SLO、利用可能なダッシュボード、新しいメトリクスの追加方法
• tracing.md — 分散トレースの設定、リクエストをエンドツーエンドでトレースする方法、スパンの命名規約、新しいコードパスの計装方法
• alerting.md — 設定されているアラート、アラートのしきい値とその理由、エスカレーション経路、既知のノイズの多いアラート、新しいアラートの追加方法

リポジトリにインフラストラクチャがないサブページは省略してください。内容のあるサブページが1つだけの場合は、how-to-monitor/ をディレクトリではなく、単一の how-to-monitor.md ファイルにまとめてください。

クリーンアップの候補

この条件付きセクションでは、実行可能なメンテナンス作業を提示します。スキャンで有意義な内容が見つかった場合にのみ生成してください。サブページの候補：

• dead-ends.md — 何からもインポートされていないファイル、エクスポート、モジュール。コード上のゴーストタウンに相当します。
• todos-and-fixmes.md — ファイルの場所を含む、蓄積された TODO、FIXME、HACK コメント。最も古いものも含めてください。
• complexity-hotspots.md — 最大のソースファイル、最も深いネスト、または最も複雑な関数。リファクタリングを促すための情報です。
• dependency-freshness.md — 古くなった、またはメンテナンスされていない依存関係。現在も使用されている最も古い依存関係も記載してください。

該当事項がないサブページは省略してください。内容のあるサブページが1つだけの場合は、cleanup-opportunities/ をディレクトリではなく、単一の cleanup-opportunities.md ファイルにまとめてください。

メンテナー

サブシステムと、その分野に詳しい人を対応付けるトップレベルの maintainers.md ページを含めてください。このページでは、次の2つのデータソースを使用します。

• CODEOWNERS ファイル（存在する場合）— 公式な所有者の割り当て
• Git の blame／git log — ディレクトリまたはサブシステムごとの、直近または頻繁にコミットしている人を2～3名

表として提示してください：

| Subsystem | Official owners (CODEOWNERS) | Recent contributors (git history) | Last activity |
|---|---|---|---|
| Authentication | @alice | alice, bob | 2 weeks ago |
| CLI | @charlie, @dave | charlie, eve | 3 days ago |

リポジトリに CODEOWNERS ファイルがない場合は、その列を省略し、すべてのデータを Git の履歴から取得してください。コントリビューターがごく少数（例：個人プロジェクト）の場合は、このページ自体を省略してください。

ページごとのアクティブなコントリビューター

各ドメインページ（apps、systems、features、packages、primitives）では、ページ見出しの直後、Purpose セクションの前の最初の行に「Active contributors」のクレジット行を含めてください。

# Authentication

Active contributors: alice, bob

## Purpose
...

名前は、CODEOWNERS（利用可能な場合）と、そのサブシステムのディレクトリに対する git blame で直近にコミットした人の上位2～3名を組み合わせて導き出してください。ファーストネームまたは GitHub ユーザー名を使い、@記号は付けないでください。

コントリビューターの一覧からボットアカウントを除外してください — ユーザー名が [bot] で終わるアカウント（例：factory-droid[bot]、dependabot[bot]、github-actions[bot]）を除外します。ボットは質問をして連絡を取る相手ではありません。これは、ページごとのアクティブなコントリビューターのクレジット行とメンテナーのページの両方に適用されます。

コントリビューターのデータにはデフォルトブランチを使用してください。 git blame または git log からコントリビューターを導き出す際は、必ず現在のブランチではなく、デフォルトブランチ（main または dev）を参照してください。フィーチャーブランチでは、そのブランチで作業している人にコントリビューターのデータが偏る可能性があります。正確なコントリビューターの履歴を取得するには、git log origin/main -- <path> または git log origin/dev -- <path> を使用してください。

最下部のセクション

これらはすべての wiki の末尾に表示されます。

• reference/ — 設定、データモデル、外部依存関係
• maintainers.md — サブシステムの所有者一覧（条件付き。個人プロジェクトでは省略し、必ず最後のページにする）

ページの順序

サイドバーの順序は、ナビゲーションにとって非常に重要です。すべてのページを定義された位置に配置してください。子ページのないページを上部または下部にまとめてはいけません。

Wiki の全体的な順序は次のとおりです。

1. overview/（index、architecture、getting-started、glossary）
2. by-the-numbers.md（存在する場合）
3. lore.md（存在する場合）
4. fun-facts.md（存在する場合）
5. how-to-contribute/
6. ［組織的な視点。適切な順序で配置］
7. ［条件付きセクション：api、deployment、security、how-to-monitor、background、cleanup-opportunities］
8. reference/
9. maintainers.md（該当する場合は常に最後）

順序のルール：

• 各ページは、子ページの有無にかかわらず、定義された位置に配置します。子ページのない他のページと一緒に先頭に置くのではなく、by-the-numbers.md は overview/ の後に配置します。
• .wiki-meta.json の pageOrder 配列は、この順序に正確に従う必要があります。サイドバーの表示順はこの配列で制御されます。
• 視点ごとのセクション（例：apps/）では、重要度の高いページから低いページの順に並べます。index.md は常に最初に配置します。
• 条件付きセクションは、アルファベット順ではなく、上記の順序（api → deployment → security → how-to-monitor → background → cleanup-opportunities）で配置します。

ネストのルール

• overview/ 内の4つのページ（index.md、architecture.md、getting-started.md、glossary.md）を除き、どのページもサブページを持つディレクトリにできます。これら4つのページは常に単一ファイルにします。
• 深さの上限：各視点のルートから2階層まで（例：apps/cli.md、または apps/cli/index.md + apps/cli/tui-rendering.md）。それより深くしてはいけません。
• すべてのディレクトリに index.md を含めます。
• 大規模なリポジトリ（ソースディレクトリが50以上、または独立したサブシステムが10以上）では、ページに詰め込むよりも分割する方を優先します。サブシステム全体を説明する3000語のページよりも、それぞれ異なる側面に焦点を当てた3つのページの方が有用です。重要なサブエージェントは、コードから得られた情報に基づいてサブページを作成するかどうかを判断します。
• 小規模なリポジトリでは、原則として単一ページにし、トピックに明確な下位領域がある場合にのみ分割します。
• deployment と security は単一ページから始め、リポジトリに十分な内容がある場合にのみディレクトリに展開します。

命名のルール

• ファイル名には小文字とハイフンを使用します。GettingStarted.md ではなく、getting-started.md のようにします。
• ファイル名には小文字とハイフンを使用します。スペースや大文字は使用しません。

ページタイトルのルール

ページタイトル（各 .md ファイルの先頭にある # Heading）には、簡潔な名詞句を使用し、チームでの呼び方に合わせます。セクション階層で文脈はすでに示されているため、タイトルでそれを繰り返す必要はありません。

• ディレクトリパスを先頭に付けないでください。 タイトルは「CLI」であり、「apps/cli — CLI Architecture」ではありません。
• 汎用的な接尾辞を付けないでください。 タイトルは「Apps」であり、「Apps Overview」ではありません。タイトルは「Packages」であり、「Packages — Overview」ではありません。例外は overview/index.md のみで、プロジェクト名を含めてもかまいません（例：「Factory platform overview」）。
• 親セクション名を繰り返さないでください。 features/sessions.md のタイトルは「Features — Sessions」ではなく、「Sessions」です。
• チームの用語に合わせてください。 チームが「the daemon」と呼んでいる場合、タイトルは「Background Service Process」ではなく「Daemon」です。
• 短くしてください。 1～3語を目安にします。タイトルがそれ以上になる場合は、ページの内容が広すぎる可能性があるため、分割を検討してください。

3. ページの生成（サブエージェントへの委任）

ページの生成では、トップレベルエージェントがオーケストレーションと基盤ページを担当し、その後、ドメインページをサブエージェントに委任して、内容の充実と並列処理を実現します。

実行 DAG

1. SURVEY (top-level)
   Structural scan + deep code scan
   Produce: survey_context
        │
        ▼
2. PLAN (top-level)
   Decide lens sections, list all pages, mark criticality
   Produce: page_plan (JSON with per-page briefs)
        │
        ▼
3. FOUNDATION PAGES (top-level, sequential)
   Write: overview/*, how-to-contribute/patterns-and-conventions
   These establish shared vocabulary and conventions
        │
        ├────────────────────────────────────────┐
        ▼                                        ▼
4a. LENS PAGES (sub-agents, parallel)     4b. DATA PAGES (sub-agents, parallel)
    Critical pages: 1 agent each               by-the-numbers
    Normal pages: batched 3-5                  lore
    Each agent writes its page(s)              fun-facts
    + sub-pages if warranted
        │                                        │
        ├────────────────────────────────────────┘
        ▼
5. REMAINING PAGES (sub-agents, parallel)
   how-to-contribute/ (remaining pages)
   Conditional sections: api, deployment, security,
     how-to-monitor, background, cleanup-opportunities
   reference/ + maintainers.md
        │
        ▼
6. ASSEMBLY (top-level)
   Cross-link audit, .wiki-meta.json
        │
        ▼
7. UPLOAD

ステップ 2：計画と委任

調査の後、トップレベルエージェントはページ計画を作成します。これは、Wiki に含めるすべてのページを構造化して列挙したものです。各ページの計画には、次の項目が含まれます。

• パス — ファイルパス（例：apps/cli/index.md）
• タイトル — ページの見出し
• 重要度 — critical（専任のサブエージェントを割り当てる）または normal（関連ページとまとめて処理する）
• 内容の概要 — ページで扱う内容と、読み込むコードパスを説明する 2～3 文
• 関連するソースパス — サブエージェントが読むべき具体的なファイル／ディレクトリ
• 関連ページ — 作成する他のページのタイトル、パス、一文での要約。エージェントが内容を説明する代わりに、どのページへリンクすべきかを把握できます

重要度のガイドライン： 大規模なコードベース、高い変更頻度、または中心的なアーキテクチャ上の役割を持つアプリ、パッケージ、機能を扱うページは、専任エージェントを割り当てる有力な候補です。例：ソースファイルが 50 個以上ある CLI、ほとんどの他のパッケージからインポートされるコアライブラリ、5 つ以上のディレクトリにまたがる機能などです。エージェントは調査結果に基づいて判断します。これらはガイドラインであり、厳格なルールではありません。

サブエージェントの深さに関するガイドライン： 1 つのページで複雑なサブシステム全体を扱おうとすべきではありません。次の場合、サブエージェントはサブページを作成します。

• サブシステムに、明確に区別できる内部領域が 3 つ以上ある場合（例：CLI に TUI レンダリング、exec モード、スキルシステム、セッション管理がある場合は、それぞれにページを作成する価値があります）
• トピックを十分に説明するために、1 ページが約 2000 語を超える場合
• サブシステムに複数のエントリーポイントや、ユーザー向けの明確に異なるモードがある場合

分割するケースの例：

• ソースファイルが 50 個以上あり、エントリーポイントが 4000 行を超える CLI アプリ → 主要なサブシステムごとにサブページを作成（例：cli/tui-rendering.md、cli/exec-mode.md、cli/skills.md、cli/session-management.md）
• 明確に異なる API グループ、認証システム、ジョブランナーを持つバックエンド → それぞれにサブページを作成
• 10 個以上の機能モジュールを持つフロントエンドパッケージ → 最も複雑な機能モジュールにサブページを作成

分割しないケースの例：

• ファイルが 5 つで目的が 1 つのユーティリティパッケージ → 1 ページ
• ハンドラーが 1 つのシンプルなマイクロサービス → 1 ページ
• 設定または定数のパッケージ → 1 ページ

ステップ 3：基盤となるページ

トップレベルエージェントは、サブエージェントの実行開始前に、次のページを順番に作成します。

1. overview/index.md — プロジェクトの概要
2. overview/architecture.md — Mermaid 図を含むシステムアーキテクチャ
3. overview/getting-started.md — 前提条件、インストール、ビルド、テスト、実行
4. overview/glossary.md — プロジェクト固有の用語
5. how-to-contribute/patterns-and-conventions.md — コーディングパターンと規約

これらのページでは、サブエージェントが参照する共通の用語とアーキテクチャ上の背景を定めます。委任を開始する前に、完成させておく必要があります。

ステップ 4：サブエージェントへの委任（並列実行）

サブエージェントは、2 つのグループに分かれて並列実行します。

4a. レンズページ — すべての組織的な視点のページ（アプリ、システム、機能、パッケージ、プリミティブ）：

• 重要度が高いページには、それぞれ専任のサブエージェントを割り当てます。サブエージェントは関連するコードを読み、ページを作成し、サブページが必要かどうかを自律的に判断します。トピックに明確に区別できるサブ領域がある場合、エージェントはサブページを作成します（最大 2 階層：section/page.md）。トップレベルエージェントは、重要度が高いページのサブページを事前に計画しません。サブエージェントが調査して判断します。
• 重要度が通常のページは、関連性に基づいてグループ化し、サブエージェントごとに 3～5 ページをまとめて処理します（例：小規模なパッケージを 3 つまとめる、または関連する機能を 2 つまとめる）。まとめて処理するページは通常、サブページを作らず、単一ファイルで作成します。

4b. データページ — Git の履歴とソースファイルの構成のみを必要とするため、レンズページと並行して作成します。

• by-the-numbers.md
• lore.md
• fun-facts.md

ステップ 5：残りのページ（並列）

すべてのレンズページが完成したら、次の作業をサブエージェントに割り当てます。

• how-to-contribute/ の残りのページ（development-workflow、testing、debugging、tooling）をひとまとまりとして処理
• 条件付きセクションごとに、個別のサブエージェントまたは小規模なバッチを割り当てる：api、deployment、security、how-to-monitor、background、cleanup-opportunities
• reference/ と maintainers.md をひとまとまりとして処理

これらのページでは、レンズページが完成しているため、相互に参照できます。

ステップ 6：組み立て

トップレベルのエージェントが最終確認を行います。

• ページ間の相互リンクを監査する（壊れた参照を修正し、足りないリンクを追加する）
• 最終的なページ一覧と順序を含む .wiki-meta.json を作成する
• すべてのディレクトリに index.md ファイルがあることを確認する

サブエージェントのプロンプトテンプレート

各サブエージェントには、次の構成のプロンプトを渡します。

You are writing wiki page(s) for [repo].

## Shared Context
[The survey_context document from Step 1 — compact repo overview,
architecture, key patterns, glossary terms. Same for all agents.]

## Your Assignment
Pages: [list of pages this agent is responsible for]
Criticality: [critical or normal]
Content brief: [2-3 sentences per page describing what to cover]
Relevant source paths: [specific files/directories to read]

## Related Pages (link to these, don't duplicate their content)
- apps/cli (apps/cli/index.md): "CLI architecture, entry points, and TUI rendering"
- features/llm-integration (features/llm-integration.md): "LLM provider abstraction and streaming"
- ...

## Rules
- Follow the page template (sections 3a-3e in the skill)
- Maximum nesting: 2 levels (section/page.md)
- For critical pages: explore the code and create sub-pages if the topic
  has clearly distinct sub-areas. Write both the index.md and sub-pages.
- For normal pages: write single-file pages unless complexity demands splitting
- Use Mermaid diagrams when they help explain data flows or component relationships
- Cross-link to related pages listed above instead of re-explaining their topics
- Write output to [wiki_dir path]

共通コンテキストはすべてのエージェントで同じです。コンパクトな調査ドキュメントを使用します。ページごとの概要は、計画時にトップレベルのエージェントが個別に作成します。これにより、サブエージェントが調査済みの内容を再調査したり、別のページで扱う内容を説明したりすることを防ぎます。

各ページについて：

3a. 関連するコードを読む

執筆するセクションの実際のソースファイルを開いて読みます。ファイルの内容を推測したり、幻覚したりしないでください。ファイルが大きすぎる場合は、現在のセクションに関係する部分を読んでください。

3b. 説明文を書く

コードの内容を平易な言葉で説明します。まず全体的な目的を説明し、次に詳細を掘り下げます。すべての記述は、特定のファイルまたは関数を根拠として示せるようにしてください。

各ドメインページには、次のセクションを含めてください（サブシステムに該当しないものは省略します）。

0. 主なコントリビューター — 見出しの直後に置く1行の執筆者表記（セクション 2 の「ページごとの主なコントリビューター」を参照）
1. 目的 — このサブシステムが何をするかを2〜3文で説明
2. ディレクトリ構成 — 主要なファイルとフォルダーを示すファイルツリー
3. 主要な抽象化 — 重要な型（クラス、インターフェース、トレイト、構造体、関数）のうち最も重要なものを、ファイルパスと1行の説明を添えた表にまとめる
4. 仕組み — 主なデータフロー／制御フロー。3つ以上のコンポーネントが関わる場合は Mermaid 図を使用
5. 統合ポイント — このサブシステムが他のサブシステムとどう接続するか（インポートするもの、呼び出すもの、発行またはリッスンするイベント）
6. 変更の開始点 — このサブシステムを変更または拡張する必要がある場合に、開発者がどこから始めるべきかを2〜3文で説明

ページの長さは、サブシステムの複雑さに応じて決めてください。薄いラッパーであれば、セクション 1、3、5 だけで十分な場合もあります。複雑なサブシステムであれば、複数の図を含めて6つすべてのセクションが必要になる場合もあります。

3c. Mermaid 図を追加する

次の内容を説明するには Mermaid 図を使用します。

• アーキテクチャ — システムのコンポーネントとその接続方法
• データフロー — リクエストのライフサイクル、イベントパイプライン、処理段階
• 状態機械 — 認証フロー、注文の状態、ビルドパイプライン

Mermaid 図のガイドライン：

• アーキテクチャ図とフロー図には graph TD または graph LR を使用します
• サービス間のリクエスト／レスポンスフローには sequenceDiagram を使用します
• 状態機械には stateDiagram-v2 を使用します
• 図は5〜15個のノードを目安に簡潔にまとめます。大きな図は、複数の小さな図に分割してください
• エッジには、渡されるアクションまたはデータをラベルとして付けます
• 関連するコンポーネントをまとめるには、サブグラフを使用します

例：

```mermaid
graph LR
    Client -->|HTTP request| APIGateway
    APIGateway -->|validate + route| Handler
    Handler -->|query| Database
    Database -->|rows| Handler
    Handler -->|JSON response| Client
```

文章だけで説明できる単純な関係には Mermaid を使用しないでください。図は、言葉では説明しにくい内容を示す場合にのみ使います。

3d. ファイル参照を追加する

各ドメインページには、そのサブシステムで最も重要なファイルを一覧にした**「主なソースファイル」**テーブルを含めてください。

| File | Purpose |
|---|---|
| `src/auth/middleware.ts` | Validates JWT tokens, attaches user to request |
| `src/auth/token-service.ts` | Token creation, refresh, and revocation |

テーブルには重要なファイルを適切に含めてください。些細なファイルで埋めたり、数が少ないという理由だけでファイルを省いたりしないでください。

説明文で触れるすべてのファイルを参照してください。クラス、インターフェース、関数、型に初めて言及するときは、ファイルパスをバッククォートで囲んで記載してください。読者がドキュメントからコードへすぐにたどり着けるようにしてください。

3e. ページ間の相互リンク

相対 Markdown リンクを使用して、ページ間をリンクします。

For details on how the auth middleware integrates with the API layer,
see [API authentication](../api/authentication.md).

各ページから、少なくとも1つの別のページにリンクしてください。読者がサイドバーを使わずに Wiki 内を移動できるようにします。

3f. 面白い豆知識のコンテンツ

fun-facts.md ページは任意ですが、作成をおすすめします。次のリストから、対象のリポジトリに関する特に興味深いトピックを3～5個選びます。

• 現存する最古のコード — git blame で最も古いファイルや関数を探します。どれくらい古いでしょうか？大きく変更されていますか？
• 依存関係の考古学 — 現在も使用されている最古の依存関係、またはメジャーバージョンの更新回数が最も多い依存関係
• 名前の由来 — プロジェクトや内部ツールの名前の由来は何でしょうか？エンジニアは変わった名前を付けることがあり、たいていそこには由来があります
• TODO／FIXME の数 — TODO／FIXME／HACK コメントはいくつありますか？最も古いものはどれでしょうか？
• 最長のファイル — ソースファイルのうち、行数が最も多いのはどれでしょうか？リファクタリングのヒントも兼ねた、やさしい指摘です

どの Wiki にもこれらすべてを無理に盛り込む必要はありません。リポジトリに本当に興味深い情報があるものだけを選んでください。特に取り上げるものがなければ、fun-facts は省略します。

4. メタファイルを書く

すべてのページを生成した後、Wiki ディレクトリのルートに .wiki-meta.json を作成します。pageOrder 配列は重要です。Wiki サイドバーでのページの表示順を制御します。生成したすべてのファイルパスを、表示したい順に正確に並べてください。これがない場合、ページはアルファベット順に並びます。

{
  "generatedAt": "2025-01-15T10:30:00Z",
  "pageCount": 42,
  "topLevelSections": ["overview", "by-the-numbers", "lore", "fun-facts", "how-to-contribute", "apps", "systems", "features", "packages", "primitives", "api", "deployment", "security", "how-to-monitor", "background", "cleanup-opportunities", "reference", "maintainers"],
  "pageOrder": [
    "overview/index.md",
    "overview/architecture.md",
    "overview/getting-started.md",
    "overview/glossary.md",
    "by-the-numbers.md",
    "lore.md",
    "fun-facts.md",
    "how-to-contribute/index.md",
    "how-to-contribute/development-workflow.md",
    "how-to-contribute/testing.md",
    "how-to-contribute/debugging.md",
    "how-to-contribute/patterns-and-conventions.md",
    "how-to-contribute/tooling.md",
    "apps/index.md",
    "apps/cli/index.md",
    "apps/cli/command-structure.md",
    "apps/cli/tui-rendering.md",
    "apps/daemon.md",
    "systems/index.md",
    "systems/auth.md",
    "features/index.md",
    "features/wiki-generation.md",
    "packages/index.md",
    "packages/common.md",
    "primitives/index.md",
    "primitives/session.md",
    "api/index.md",
    "api/rest-endpoints.md",
    "deployment.md",
    "security.md",
    "how-to-monitor/index.md",
    "how-to-monitor/logging.md",
    "how-to-monitor/metrics.md",
    "how-to-monitor/tracing.md",
    "how-to-monitor/alerting.md",
    "background/index.md",
    "background/design-decisions.md",
    "background/pitfalls.md",
    "background/migration-context.md",
    "cleanup-opportunities/index.md",
    "cleanup-opportunities/dead-ends.md",
    "cleanup-opportunities/todos-and-fixmes.md",
    "cleanup-opportunities/complexity-hotspots.md",
    "cleanup-opportunities/dependency-freshness.md",
    "reference/index.md",
    "reference/configuration.md",
    "reference/data-models.md",
    "reference/dependencies.md",
    "maintainers.md"
  ]
}

上記の例は省略されています。実際には、Wiki ディレクトリ内のすべての .md ファイルを記載してください。順序はセクション2で定義したページの順序（overview → by-the-numbers → lore → fun-facts → how-to-contribute → lenses → conditional → reference → maintainers）に合わせます。

5. アップロード

標準アップロード（ローカル Wiki ディレクトリ）

ユーザーがローカルコピーを保持する場合（デフォルト）：

droid wiki-upload \
  --repo-url "$REPO_URL" \
  --wiki-dir ./droid-wiki

引数：

• --repo-url — リポジトリの URL（リモート origin。例：https://github.com/org/repo）
• --wiki-dir — 生成した Markdown ファイルを含むディレクトリへのパス
• --cleanup — （任意）アップロード成功後に Wiki ディレクトリを削除します

リモートのみのアップロード（--no-local の処理）

ユーザーがディスク上にファイルを残さずに Wiki を生成するよう求めた場合（例：「ローカルにファイルを残さない」と指定した場合や、--no-local フラグを渡した場合）：

# Create a temporary directory
WIKI_TMPDIR=$(mktemp -d)

# Write all wiki files to the temporary directory instead of ./droid-wiki
# ... generate pages into $WIKI_TMPDIR ...

# Upload with --cleanup to remove the temp directory after success
droid wiki-upload \
  --repo-url "$REPO_URL" \
  --wiki-dir "$WIKI_TMPDIR" \
  --cleanup

--cleanup フラグを指定すると、アップロード成功後に CLI が --wiki-dir ディレクトリを削除します。アップロードに失敗した場合は、ユーザーが再試行できるようにディレクトリが保持されます。

コンテンツの原則

段階的な情報開示

各ページの冒頭に、そのページの内容を説明する1～3文の要約を記載します。続いて、主な概念を説明する概要セクションを設けます。実装の詳細、例外的なケース、設定オプションはページの後半に記載します。

各ページの最初の段落に目を通すだけで、読者がシステム全体の概要を把握できるようにします。

ページサイズの上限

各ページのサイズは500KB未満に抑えます。上限に近づく場合は、サブページに分割します。たとえば、大きな API リファレンスページは、エンドポイントのグループごとに1ページを設けたディレクトリにできます。

人間が書くためのルール

人が書いたように読めるドキュメントを書いてください。技術ドキュメントは内容が堅いため、AI が書いたようなパターンに陥りがちです。その傾向を避けてください。

具体的に守るルール：

1. 大げさな意義付けをやめる。「〜の証しとなる」「進化する状況において重要な役割を果たす」「〜の土台を築く」「〜の重要性を強調する」といった表現は使わないでください。対象が何をするのかをそのまま述べてください。

   悪い例：「認証モジュールは、アプリケーションのセキュリティを支える重要な柱です。」 良い例：「認証モジュールは JWT トークンを検証し、ユーザーコンテキストをリクエストに追加します。」

2. 宣伝文句をやめる。「誇る」「活気に満ちた」「豊かな」「深遠な」「披露する」「体現する」「取り組み」「画期的な」「著名な」「息をのむような」といった表現は使わないでください。技術ドキュメントは説明するものであり、売り込むものではありません。

   悪い例：「このコードベースには、開発者体験へのチームの取り組みを示す、活気に満ちた豊富なユーティリティがそろっています。」 良い例：「utils/ ディレクトリには、文字列の書式設定、日付の解析、再試行ロジックのヘルパーがあります。」

3. 表面的な「〜しながら」の分析をなくす。「〜を強調しながら」「〜を確実にしながら」「〜を反映しながら」「〜を象徴しながら」「〜を披露しながら」「〜に貢献しながら」といった言葉を文末に付けて、見せかけの深みを加えないでください。

   悪い例：「このサービスはイベントを非同期で処理し、スケーラビリティを確保しながら、システムの堅牢なアーキテクチャを示しています。」 良い例：「このサービスはイベントを非同期で処理します。SQS キューからイベントを取得し、インスタンスあたり約 500 件/秒を処理できます。」

4. **AI がよく使う語彙を避ける。**次の語は AI 生成テキストに頻出します。さらに、極めて重要な、掘り下げる、強調する、永続的な、高める、促進する、獲得する、相互作用、複雑な／複雑さ、状況（抽象的な意味）、重要な、披露する、タペストリー（抽象的な意味）、証し、強調する（動詞）、活気に満ちた。より平易な表現に置き換えてください。

5. **「3 つ並べる」型を避ける。**網羅的に見せるために、無理に 3 つの項目を並べないでください（例：「革新、ひらめき、業界の知見」）。2 つなら 2 つ、4 つなら 4 つを挙げてください。

6. 繋辞を避けない。「X は Y です」「X は Y を持ちます」と書き、「X は Y として機能します」「X は Y として立ちます」「X は Y を表します」「X は Y を誇ります」「X は Y を備えています」「X は Y を提供します」といった表現は避けてください。

   悪い例：「config モジュールは、環境変数管理の中心的な拠点として機能します。」 良い例：「config モジュールは環境変数を読み取り、型付き定数をエクスポートします。」

7. 否定の対句を使わない。「X だけでなく Y でもある」「X にとどまらず Y でもある」といった構文は避けてください。

8. 見出しはセンテンスケースにする。「認証を始める」と書き、「認証を始める方法」のように各語の先頭を大文字にしないでください。

9. 埋め草の表現を削る。「〜するために」は「〜する」に、「〜という事実により」は「〜なので」に置き換え、「重要なのは〜ということです」は削除して、事実をそのまま述べてください。

10. 曖昧にせず、具体的に書く。「業界の専門家は信じています」を具体的な出典に置き換えてください。「複数のコンポーネント」は実際のコンポーネント名に、「さまざまな設定」は実際の設定オプションに置き換えてください。

11. **em ダッシュを多用しない。**多くの場合、em ダッシュ（—）の代わりにコンマやピリオドを使ってください。1 ページに 1 つなら問題ありませんが、3 つ以上は多すぎます。

12. チャットボット特有の表現を使わない。「お役に立てば幸いです」「お気軽にお知らせください」「概要をご紹介します」「もちろんです！」「良い質問です！」などは使わないでください。これらは会話で使う表現であり、ドキュメントには適しません。

具体的なファイル参照

コードに関する事実を述べる場合は、必ず該当するソースファイルを示してください。ファイルを示さずに「システムが認証を処理します」と書いたり、「データベーススキーマには users テーブルがあります」と書いたりしないでください。後者の場合は、マイグレーションまたはモデルのファイルを示してください。

機能を実装するファイルが見つからない場合は、その旨を伝えてください。「再試行ロジックは config.ts で参照されていますが、現在のコードベースでは実装が見つかりません。」のように書いてください。

Mermaid 図の使用

アーキテクチャページには、Mermaid 図を少なくとも 1 つ含めてください。データフローやコンポーネント間の関係を説明するのに役立つ場合は、ドメインページにも図を含めてください。すべてのページに図を追加しないでください。設定オプションや環境変数を扱うページには、おそらく図は必要ありません。

ファイル構成の仕様

生成される Wiki は、次のレイアウトに従います。

droid-wiki/
├── .wiki-meta.json

# Always present (in this order)
├── overview/                             # Introductory material
│   ├── index.md                          # Project overview
│   ├── architecture.md                   # System architecture with Mermaid diagrams
│   ├── getting-started.md                # Prerequisites, install, build, test, run
│   └── glossary.md                       # Project-specific terms and vocabulary
├── by-the-numbers.md                     # Codebase statistics snapshot
├── lore.md                      # Timeline, eras, deprecated features, rewrites
├── fun-facts.md                          # Easter eggs, origin stories, oldest code
├── how-to-contribute/                    # How to work in this codebase
│   ├── index.md
│   ├── development-workflow.md
│   ├── testing.md
│   ├── debugging.md
│   ├── patterns-and-conventions.md
│   └── tooling.md

# Organizational lenses (use any combination, at least one required)
# Labels mirror the repo's own vocabulary
├── <apps|services|applications>/         # Deployable units
│   ├── index.md
│   ├── <simple-app>.md                   # Single page for simple apps
│   └── <complex-app>/                    # Directory for complex apps
│       ├── index.md
│       └── <sub-topic>.md
├── <systems|modules|subsystems>/         # Internal building blocks
│   ├── index.md
│   ├── <simple-system>.md
│   └── <complex-system>/                 # 3rd level for complex subsystems
│       ├── index.md
│       └── <sub-topic>.md
├── <features|capabilities|workflows>/    # Cross-cutting capabilities
│   ├── index.md
│   ├── <simple-feature>.md
│   └── <complex-feature>/                # Features that span many systems deserve sub-pages
│       ├── index.md
│       └── <sub-topic>.md
├── <packages|libraries|crates>/          # Workspace packages
│   ├── index.md
│   ├── <simple-package>.md
│   └── <complex-package>/
│       ├── index.md
│       └── <sub-topic>.md
├── <primitives|core-concepts|entities>/  # Foundational domain objects
│   ├── index.md
│   └── *.md

# Conditional sections (LLM judgment)
├── api/                                  # If the repo exposes APIs
│   ├── index.md
│   └── *.md
├── deployment.md                         # Single page or directory
├── security.md                           # Single page or directory
├── how-to-monitor/                        # Logging, metrics, tracing, alerting (services only)
│   ├── index.md
│   ├── logging.md                        # Where logs go, how to query, log levels
│   ├── metrics.md                        # What's tracked, dashboards, SLIs
│   ├── tracing.md                        # Distributed tracing, request tracing
│   └── alerting.md                       # Alerts, thresholds, escalation, noisy alerts
├── background/                           # Design decisions, pitfalls, migration context
│   ├── index.md
│   └── *.md
├── cleanup-opportunities/                # Dead code, TODOs, complexity hotspots, stale deps
│   ├── index.md
│   ├── dead-ends.md                      # Unused files, exports, modules
│   ├── todos-and-fixmes.md               # Accumulated TODO/FIXME/HACK comments
│   ├── complexity-hotspots.md            # Largest files, deepest nesting
│   └── dependency-freshness.md           # Outdated or unmaintained dependencies

# Always present (bottom)
├── reference/
│   ├── index.md
│   ├── configuration.md
│   ├── data-models.md
│   └── dependencies.md
└── maintainers.md                        # Subsystem ownership table (conditional, always last)

ルール：

• すべての .md ファイルは、レベル 1 の見出し（# Title）で始める必要があります。アップロードツールはこの見出しからタイトルを取得します。
• すべてのディレクトリに index.md を含める必要があります。
• ファイル名には小文字とハイフンを使用します。スペースや大文字は使用しないでください。
• .wiki-meta.json ファイルは追跡用であり、ページとしてアップロードされません。
• overview/ 内の 4 つのページ（index.md、architecture.md、getting-started.md、glossary.md）は、常に単一のファイルです。それ以外のページは、サブページを含むディレクトリに展開できます。
• 最大階層数：各レンズのルートから 2 階層まで（例：apps/cli/command-structure.md）。それより深くしてはいけません。
• 大規模なリポジトリでは、重要なサブエージェントがページをサブページに分割するかどうかを判断します。エディターコアや拡張機能ホストのような複雑なサブシステムは、単一の巨大なページではなく、内容を絞ったサブページを含む専用ディレクトリにしてください。
• 1 回の Wiki 生成で作成できるページは最大 200 ページです。プロジェクトでそれ以上必要な場合は、最も重要なサブシステムを優先してください。