codebase-wiki

コードベース Wiki パック — ここでの作業方法

このプロジェクトには、コードベースについてエージェントが作成する Wiki（DeepWiki をリポジトリ内で運用するもの）が含まれています。コーディングエージェントがソースを読み、wiki/ 配下に、ナビゲーションしやすく、図が豊富で、ソースに基づいた Wiki を Markdown で作成します。バージョン管理され、差分を確認でき、デフォルトで非公開で、人とエージェントが共同編集でき、OK のライブプレビューで表示され、今後のエージェントセッションに永続的な根拠情報を提供します。独立した Q&A 機能はありません。Q&A は「OK に根拠付けられたエージェント + search」です。

このスキルはパックのガイダンスです。プラットフォームの /open-knowledge スキル（読み取り／書き込み／プレビュー／リンク／根拠付けのルール）は、すべての Markdown 操作に引き続き適用されます。このガイダンスは、その上に Wiki のワークフローを重ねるものです。

構成

wiki/
  OVERVIEW.md     hub: what it is, a big-picture architecture diagram, a nav map to every section.
                  Frontmatter carries `profile` (audience/depth) + `source_commit` (freshness anchor).
  log.md          append-only generation / refresh audit trail
  architecture/   system boundaries, layers, subsystems, cross-cutting concerns + diagrams
  modules/        one page per package / module: purpose, entry points, key files, deps
  flows/          key end-to-end flows as sequence / flow diagrams + narrative
  concepts/       glossary: atomic pages for domain terms / core abstractions
  guides/         task-oriented "how / where do I change X" (filled at depth >= standard)

生成と更新

手作業で進めないでください。references/generate-and-refresh.md を読み、フェーズごとに STOP ゲートを設けた手順に従ってください。モードは自動検出されます。source_commit が空のスタブ状態の OVERVIEW.md の場合は 生成（調査 → 概要 → アーキテクチャ → モジュール → フロー → 概念 → リンクグラフ監査）、source_commit が記録済みの場合は 更新（source_commit..HEAD の差分を確認し、影響を受けるページのみ更新して再記録）します。

2 つのツールセット。 NATIVE ツール（Read／Grep／Glob／Bash）でソースコードを読みます。OK MCP は Markdown 以外のソースをインデックス化しません。OK MCP の動詞（ページには write／edit、グラフには links／search）で Wiki を作成し、監査します。NATIVE の Write／Edit を使って Wiki の Markdown を直接書かないでください。

2 つの調整項目

ユーザーの依頼から読み取る自然言語の調整項目が 2 つあります（例：「Wiki を作成して。公開向けで網羅的に」）。更新時も一貫性が保たれるよう、OVERVIEW.md のフロントマターに profile: <audience>/<depth> として記録します。

• audience — internal（デフォルト）または public。public は、文章を洗練し、秘密情報／内部インフラ／チケット番号を含めず、ソース参照に GitHub URL を使うことを意味します。
• depth — tour | standard（デフォルト）| exhaustive。網羅範囲を、OVERVIEW + アーキテクチャ + 主要なフローから、パッケージごとのモジュールページ、概念、タスクガイドまで広げます。

各調整項目が出力にどう反映されるかの正式な説明は、references/generate-and-refresh.md にあります。生成前に必ず読んでください。

ソース参照の規約

• Wiki 内のナビゲーション → OK のドキュメントリンクを使います。これにより、バックリンク／ハブ／孤立ページのグラフが構築されるため、積極的にリンクしてください。リンク密度によって Wiki のナビゲーション性が保たれます。
• コード参照 → 相対リンク + シンボルのコードスパン（internal）、または GitHub の blob URL（public）を使います。ソースファイルへのリンクはナビゲーショングラフの対象外です（links が追跡するのは .md／.mdx のエッジのみなので、グラフ上でデッドリンクや孤立ページとして表示されることはありません）。ただし、階層の深さを誤ったパスは、write/edit の brokenLinks レスポンス（no-such-file、またはコンテンツルートを越えた場合は unresolvable）に表示されるため、ページのフォルダーから ../ の数を数えてください。パスを創作しないでください。実際に読んだファイルのみを参照してください。

GitHub URL／相対パスの使い分け、#Lxx に関する注意点、コードスパンの正確な形式を含むすべてのルールは、references/generate-and-refresh.md に記載されています。

フォルダーごとのルール

architecture/ — アーキテクチャ領域（境界、レイヤー、サブシステム、横断的な関心事）ごとに1ページを作成します。各ページには、mermaid のシステムコンテキスト図またはコンポーネント図、主要なコンポーネント（ソースへの参照付き）、およびそれらを支える設計上の決定を記載します。architecture-page テンプレートを使用します。depth: tour では、モジュールはここに統合されます。

modules/ — パッケージ／モジュールごとに1ページを作成します。目的、責務、公開 API／エントリーポイント、主要ファイル（規約に従ってリンク）、依存関係、関与するフローを記載します。module-page テンプレートを使用します。tour では省略され、サブモジュールの深さはノブに応じて変わります。

flows/ — エンドツーエンドの主要なシーケンスを、mermaid のシーケンス図／フロー図と説明文で記載します。flow-page テンプレートを使用します。exhaustive では 障害モード セクションを追加します。フローが通過するすべてのモジュールと概念にリンクします。

concepts/ — 用語ごとに1ページの独立した用語集ページを作成します。定義、重要である理由、コード内での所在を記載します。concept-page テンプレートを使用します。各概念がハブとなるよう、簡潔にまとめ、相互リンクを密にします。

guides/ — タスク指向の「X を変更するには／どこを変更するには」という手順ガイドを作成します。目的、手順、関連コード、注意点を記載します。guide-page テンプレートを使用します。standard では内容を追加し、exhaustive では充実させ、tour では簡素にするか空にします。

鮮度の管理（必須）

OVERVIEW.md のフロントマターには、Wiki の最終生成／更新時点の git HEAD を示す source_commit が含まれます。これが鮮度の基準です。更新モードでは source_commit..HEAD の差分を確認して、影響を受けるページのみを更新し、その後に値を再設定します。生成または更新を実行した後は、必ず source_commit を再設定してください。基準が古いままだと、差分更新が気付かれないまま機能しなくなります。

ログの管理（必須）

wiki/log.md は追記のみの監査記録です。生成または更新を実行するたびに、日付入りのエントリーを1件追記してください。ページごとではなく、実行ごとに1件です。変更したページは Markdown リンク（[Server](./modules/server.md)）で参照し、バックリンクグラフに反映されるようにします。エントリーの形式：

## YYYY-MM-DD: <generate | refresh>

- Profile: <audience>/<depth>
- source_commit: <short-sha> (was <prev-sha> on refresh)
- Coverage: <sections / packages written or updated>
- Pages: [Overview](./OVERVIEW.md), [Server](./modules/server.md), ...

テンプレート

各フォルダーにはスターターテンプレート（architecture-page、module-page、flow-page、concept-page、guide-page）が用意されています。write({ document: { path, template: "<name>" } }) で作成します。テンプレートに含まれるのは構成のみ（見出しとフロントマターのひな形）です。各セクションの目的は上記および references/generate-and-refresh.md に記載されており、ドキュメント本文では繰り返しません。