Wiki
プロジェクトWikiは、プロジェクトを説明するMarkdownページのフォルダです：各部分の役割、なぜそのように動作するのか、その証拠はどこにあるのか。人が読み、エージェントが保守します。新しいソース、質問、コード変更のたびに、Wikiはより完全で正確になっていくべきです。
これは「LLM Wiki」パターンに従います：生のソースを保持し、それらを要約・接続するページを書き、インデックスとログを維持して全体がナビゲーション可能になるようにします。
リポジトリルールが優先
リポジトリに既にWikiがある場合は、変更を加える前にそのスキーマやインストラクションファイル（多くの場合 wiki/README.md、wiki/AGENTS.md、wiki/schema.md）を読んでください。そのレイアウト、メタデータ、リンクスタイル、コマンドがここでのデフォルトよりも優先されます。リポジトリのWikiスクリプトが存在する場合はそれを使用し、それらが生成するファイルを手動で編集しないでください。
構成要素
| パート | 説明 | 編集者 |
|---|---|---|
| ソース | Issue、PR、記事、メモ、トランスクリプトなど、生の素材のコピー | 一度追加したら変更しない |
| ページ | トピックに関する文章による説明。ソースとコードを引用 | 事実が変わったら更新 |
| スキーマ | Wikiのルール（レイアウト、メタデータ、規約）を記述した1つのファイル | 意図的に変更 |
| インデックス | 各ページの1行サマリー付きリスト | 再生成、または完全な状態を維持 |
| ログ | Wikiへの変更を日付入りで追記専用として記録 | 操作ごとに1エントリ |
新しいWikiのデフォルトレイアウト：
wiki/
├── README.md # Wikiの説明と使い方
├── schema.md # ルール（ルールを書く唯一の場所）
├── index.md # 全ページ、1行ずつ
├── log.md # 変更履歴、最新が最後
├── pages/ # トピックページ
└── sources/ # 生の素材、追加後は変更しない
小さなプロジェクトはこれで十分です。ページが多くて人が見つけられなくなった場合にのみ、サブフォルダを追加してください。
ソース間で矛盾がある場合の優先順位
スキーマに、主張の種類ごとにどのソースが優先されるかを書き留めてください。ほとんどのソフトウェアプロジェクトでは：
- 現在のコードの動作： コードとそのテスト
- 決定内容とその理由： 決定記録、Issue、または決定されたPR
- 計画中または進行中のこと： Issueトラッカーまたはロードマップ
ページとその権威が矛盾する場合、ページを修正し、古い信念を覚えておく価値があるなら、何が変わったかの短いメモを残してください。ソースを一致させるために編集しないでください。
ページ
-
1ページ1トピック、明確なタイトルを付けます。ほぼ重複したページを追加するのではなく、既存のページを更新してください。
-
主張を引用します。 ソースへのリンクかファイル名を明記してください。読者は重要な記述を検証できる必要があります。
-
相対Markdownリンク（
[Parser](parser.md)）を使用します。ただし、Wikiがすでに別のスタイルを使用している場合は除きます。 -
フロントマターは最小限に。 有用な最小構成：
--- title: Parser summary: 入力ファイルがどのように読み取られ、検証されるか。 sources: [sources/issue-42.md] code: [src/parser.ts] updated: 2026-01-31 ---人またはスクリプトが使用する場合のみフィールドを追加してください。
-
すべてのページは、 インデックスと少なくとも1つの関連ページから到達可能でなければなりません。
操作
新しいWikiのセットアップ
- 既存のドキュメントと誰が読むかを確認します。機能しているドキュメントサイトを複製しないでください。
- レイアウトとスキーマをユーザーに提案し、ページを書く前に合意を得ます。
README.md、schema.md、index.md、log.mdを作成します。- プロジェクトの最も重要な部分について数ページ書き、残りを埋める前にユーザーに確認します。
- リポジトリのエージェントインストラクション（
AGENTS.md、CLAUDE.md）でスキーマを参照します。ルールをそれらにコピーしないでください。
ソースの追加
- 生の素材を
sources/に保存し、出典と日時を記録します。 - すべてを読みます。
- 影響を受ける既存のページをすべて見つけ、更新します。トピックが存在しない場合のみ新しいページを作成します。
- 現在のページと矛盾する点があればそれに注意し、権威ルールを使用して解決します。
- インデックスを更新し、ログエントリを追加します。
ソースを保存してもページを更新しなければ完了ではありません。ページこそが人が読むものです。
質問への回答
- インデックスから始め、ページタイトルとテキストを検索します。
- 関連するページを読み、重要な主張をそのソースまたはコードで検証します。
- 使用したページと証拠へのリンク付きで回答します。それらが矛盾する場合や、Wikiに回答がない場合も述べてください。
- 回答が新しく、再度聞かれる可能性が高い場合は、Wikiに追加することを提案します。
コード変更後の更新
変更によって何かの動作が変わった場合：
- 変更が触れたファイル、関数、用語についてWikiを検索します。
- 影響を受けるすべてのページを、コード変更と同じPRで更新します。
- タイトルやサマリーが変わった場合はインデックスを更新し、ログエントリを追加します。
Wikiの健全性チェック
以下を確認します：
- リンク切れ、存在しないコードパス
- インバウンドリンクがないページ
- 同じトピックの重複ページ
- どのページも引用していないソース
- 互いに、またはコードと矛盾するページ
- ページが欠けている、または削除されたものをリストしているインデックス
リンクやインデックスなどの機械的な問題は直接修正します。ページの統合やどちらの主張が正しいかの判断など、判断を要するものはユーザーに報告します。
ログエントリ
操作ごとに1エントリを log.md の末尾に追加します：
## 2026-01-31 14:05 UTC: 取り込み | Issue 42、空の入力行
Issueをソースとして追加し、パーサーページのバリデーションセクションを更新しました。
同じ日のエントリが順序を保てるよう、常に時刻とタイムゾーンを含めてください。
禁止事項
- ソースを追加した後に編集する。
- 許可なくWikiの大部分を再構成またはリネームする。
- 古くなったページを削除する。古いとマークし、置き換えたものにリンクする。
- 同じルールを複数の場所に書く。スキーマが唯一のコピーです。
- Wikiを、それが説明するコードよりも権威があると扱う。
- ユーザーの承認なしに外部システム（Confluence、Notion、Issueトラッカー）に書き込む。