Living Docs
ドキュメントを、一度書いたら腐っていくアーティファクトではなく、コードと同期し続ける生きたシステムとして扱います。この規律の背骨は**「すべての知識はただ一つの場所にあり、その場所はインデックス化されており、構造的な変更はドキュメントなしには出荷されない」**という原則と、そこからぶら下がるいくつかのドキュメントタイプ（憲法、ADR、BDR、PRD、課題、調査、アーキテクチャ図、セマンティックコンテキストインデックス）から成ります。
このスキルはスタック非依存です。ドキュメントの整理と保守の方法を統治し、プロジェクトが使用する技術には一切関与しません。
コア不変条件（背骨）
これらはすべてのドキュメントタイプにわたって保持されます。それ以外はすべて詳細です。
- ドキュメント優先。 外部（トラッカー、Wiki）に公開する前に、リポジトリ内（
docs/）に本文を作成します。リポジトリファイルがソース・オブ・トゥルースであり、外部コピーはミラーです。 - 事実ごとに一つの保管場所。 各概念、決定、要件は、正確に1つのファイルに存在します。重複は禁止 — コピーせずに相互参照します。重複した散文は、ドリフトの原因となります。
- インデックス化されていなければ存在しないも同然。 すべてのドキュメントは、インデックス（そのディレクトリ内の
index.mdリスト、およびプロジェクトガイドがリンクするバンドルルートのdocs/index.md）から到達可能でなければなりません。孤立ファイルは禁止です。 - 上書き禁止、過去は書き換えない。 決定と要件は追加専用記録です。何かが変更された場合、古い記録を「廃止」とマークし、新しい記録を書きます — 過去を黙って編集してはいけません。
- 構造変更には必ずドキュメントを伴う。 新しいモジュール、ファイル移動、スキーマ変更、新しいデータフロー → 同じ変更の中で、関連するドキュメントとその図を更新します。「後でドキュメント化する」は禁止です。
疑問がある場合は、これらの5つから正しいアクションを導き出してください。以下のルールファイルは、これらの不変条件を各ドキュメントタイプに適用したものです。
形式: OKF準拠
5つの不変条件は編成とライフサイクルを統治し、Open Knowledge Format (OKF) はファイル形式を統治し、コーパスをポータブルかつエージェントが解析可能に保ちます。システム内のすべてのドキュメントは、OKFの概念でもあります。作成または形式チェックを行う際には、okf-knowledge-formatスキル（仕様をベンダリングしています）をロードしてください。
OKFは薄く、交換可能な依存関係であり — 基盤ではありません（バージョンリスク）。OKFは単一ベンダーによるv0.1です。後方互換性のないv0.2がリリースされる可能性は現実的にあります。上記の不変条件はOKFに依存しません — それらは少数のフロントマターフィールドにのみ依存するため、OKFの破壊的変更によってガバナンス層がダウンすることはありません。境界を明確に保ちましょう:
- Living Docsに必須（
scripts/lint-docs.shが強制する事実契約）：空でないtype、および廃止されたレコードのstatus+superseded_by。これらは私たちのものであり、OKFに関係なく存続します。- OKFから継承（形式規則）：予約済みの
index.md/log.md、バンドルルートのokf_version、バンドル相対リンク、# References見出し（§8）。OKFが変更された場合、この行のみが移動します —okf-knowledge-formatスキルでバージョンを再ピンし、調整します。
すべての概念ファイルに適用される2つのルール:
- 必須の
typeを持つフロントマター。 予約済みではないすべての.mdドキュメントは、typeがドキュメントの種類（Constitution、PRD、ADR、BDR、Issue、Context、Architecture View、Research、Reference）を指定するYAMLフロントマターブロックで始まります。推奨:title、description、tags、timestamp。Living Docsはプロデューサーキーを追加します:status、supersedes、superseded_by。ステータスはフロントマターに移動され — 本文に**Status:**行はありません。 - 予約済みファイル + バンドル相対リンク。 バンドルルートは
docs/です。ディレクトリリストはindex.md（OKF §6、フロントマターなし — バンドルルートのdocs/index.mdは除き、okf_version: "0.1"を保持します）。オプションのlog.mdはディレクトリ履歴を記録します（§7）。/で始まるバンドル相対パス（/adr/0007-slug.md）で相互リンクします。# References見出し（§8）の下にソースをリストし、各エントリはrules/citation-conventions.mdに従ってフォーマットします — 常にリンクを伴うABNT NBR 6023構造で、接続ラベルはプロジェクトのドキュメント言語（デフォルト英語:Available at: <URL>. Accessed on: <date>）に従い、rules/doc-language.mdに準拠します。
ドキュメントトレイル
すべての変更は、基礎的なソース・オブ・トゥルースからコードに至るまで、このチェーンに従います:
flowchart LR
C[constitution] --> P[PRD]
P --> A[ADR]
P --> B[BDR]
A --> I[issues]
B --> I
I --> K[code]
| アーティファクト | 役割 |
|---|---|
| constitution | 基礎的なソース・オブ・トゥルース: プロダクトとは何か、コアデータモデル、非妥協条件。他のすべてのドキュメントはこの下に位置します。 |
| PRD | システムが何をすべきか、そしてその理由 — 機能/プロダクト要件仕様。 |
| ADR | システムがどのように構造化されているか — アーキテクチャ/実装の決定とその根拠。 |
| BDR | システムが何を観察可能に行うべきか — 入力、出力、副作用、Given/When/Thenシナリオ — およびそれぞれがどのようにテストされるか（テスト設計マトリックス; 「テスト方法」の単一の保管場所、実行課題がそれをリンクします）。 |
| issues | 実行スライス — ADR/BDRにトレースバックする個別の作業単位。 |
| code | 実装 — 上記で指定されたすべての動作、構造、インターフェースを実現します。 |
呼び出しタイミング
- プロジェクトのドキュメントを立ち上げる場合（
docs/構造、ドキュメントインデックス、ADR/課題/BDR/憲法ディレクトリの作成）。 - プロジェクトで初めてliving-docsを実行する場合（プロジェクトガイドに
## Living Docsブロックがない）→ 強制モードの質問をし、回答を保持 → 強制モードを参照。 - 既存/ブラウンフィールドプロジェクトにliving-docsを導入する場合（決定は行われたが文書化されていない）→ 手順 → 既存プロジェクトへのLiving Docs導入に従う: 決定を棚卸しし、ADRを記録する前にそれぞれをユーザーと確認し、推測のみでバックフィルしない。
- ADR（アーキテクチャ/実装の決定）を作成または編集する場合 →
rules/adr-conventions.md+templates/adr.mdをロード。 - PRD（プロダクト/機能要件仕様）を作成または編集する場合 →
rules/prd-conventions.md+templates/prd.mdをロード。 - BDR（観察可能な動作 — 入力、出力、Given/When/Thenシナリオ、およびそれぞれのテスト方法のテスト設計マトリックス）を作成または編集する場合 →
rules/bdr-conventions.md+templates/bdr.mdをロード。テスト戦略の決定（非デフォルトレベル/手法、バー偏差）はADRtags: [testing]であり、新しいレコードタイプではありません（「TDR」はありません）。 - 非機能要件（パフォーマンス、可用性、セキュリティ、スケール）を指定する場合 → PRD内のインスツルメントにバインドされた品質属性シナリオ（
rules/prd-conventions.mdルール9 +templates/prd.md）; 決定 + フィットネス関数はADRに記述。新しいドキュメントタイプではありません。 - constitution（基礎的なスコープ、データモデル、非妥協条件）を確立または修正する場合 →
rules/constitution-conventions.md+templates/constitution.mdをロード。 - 課題/チケットを作成または編集する場合 →
rules/issue-workflow.md+templates/issue.mdをロード。 - 研究（技術評価、外部トレードオフ）を記録する場合 → **
research-artifacts**スキルをロード。これがOKF調査ノート形式（ノートごとに単一ファイル、研究ごとのサブフォルダなし）、ソース規律、および研究 → 決定 → 課題のトレーサブルチェーンを所有し、ADR/BDR/課題アーティファクトのためにここにリンクバックします。deep-researchスキルとペアリング。 - アーキテクチャ、データフロー、またはツール呼び出し図を描画または更新する場合 →
rules/architecture-diagrams.md+templates/architecture-index.mdをロード。 - ドキュメントで使用する用語または頭字語を定義する場合 → 用語集（
docs/context/glossary.md）に追加、用語ごとに一つの保管場所 →rules/glossary-conventions.md+templates/glossary.mdをロード。 - ドキュメントが大きくなりすぎたり、関心事が混在している場合 → セマンティックインデックスに分割 →
rules/semantic-index.md+templates/context-index.mdをロード。 - 構造変更後に無ドリフト保守ルールを強制する場合 →
rules/maintenance-invariant.mdをロード。 - 任意のドキュメントのOKF形式（フロントマター
type、予約済みindex.md/log.md、バンドル相対リンク、# References）を作成またはチェックする場合 → **okf-knowledge-format**スキルをロード。 - ドキュメントが書かれている言語を決定する場合（デフォルト英語; ユーザーはセッション開始時にオーバーライドして固定可能） →
rules/doc-language.mdをロード。
ドキュメントマップ
| タイプ | 保存場所 | 目的 | 可変性 |
|---|---|---|---|
| プロジェクトガイド | CLAUDE.md / README.md（ルート） | エントリポイント: スコープ、スタック、ドキュメントインデックス、必須ワークフロー | ライブ — 自由に編集可 |
| 憲法 | docs/constitution.md | 基礎的なソース・オブ・トゥルース: プロダクトスコープ、データモデル、非妥協条件 | 一度承認されると追加専用（修正ログ） |
| コンテキストインデックス | docs/context/index.md + グループファイル | ドメインとモジュールの語彙、意味論的にグループ化 | ライブ — 自由に編集可 |
| 用語集 | docs/context/glossary.md | 一度定義された用語と頭字語、ドキュメント言語で（頭字語の見出し語はそのまま） | ライブ — 自由に編集可 |
| アーキテクチャ | docs/architecture.md または docs/architecture/ + インデックス | 生きたMermaid図: 構造、データモデル、フロー、ツール呼び出し | ライブ — コードと一致する必要あり |
| ADR | docs/adr/NNNN-slug.md | 一つのアーキテクチャ/実装決定 | 追加専用（廃止） |
| BDR | docs/bdr/NNNN-slug.md | 一つの観察可能動作決定 | 追加専用（廃止または修正） |
| PRD | docs/prd/NNNN-slug.md | 一つの機能/プロダクト要件仕様 | 一度承認されると追加専用 |
| 課題 | docs/issues/NNNN-slug.md | トラッカーミラー（本文）、チケットごとに一つ | 本文は編集可能; 公開コピーは追従 |
| 研究 | docs/research/NNNN-<slug>.md（単一ファイル、サブフォルダなし; 先頭に連番、日付はフロントマターtimestamp; # Referencesで終了） | 出典のある主張を含む外部証拠 | 追加専用（証拠は日付付き） |
各ディレクトリは独自のindex.mdリスト（OKF §6、フロントマターなし）を持ちます。プロジェクトガイドの「ドキュメントインデックス」は、バンドルルートのdocs/index.mdにリンクします。インデックス契約についてはrules/semantic-index.mdを参照してください。
手順
新規プロジェクトでのLiving Docsセットアップ
- 強制モードの質問をする（強制モード → 初回実行時の質問を参照）、設定がまだ保持されていないため、他のすべてよりも優先して行います。回答をプロジェクトガイドの
## Living Docsブロックとして記録します。ユーザーに好みがない場合はデフォルトでstrictとします。 - プロジェクトガイド（
CLAUDE.mdまたは同等のもの）を作成し、ドキュメントインデックスセクションと保守ルールセクション（rules/maintenance-invariant.mdの文言をコピー）を含めます。プロジェクトガイドのハードルールセクションの出発点としてtemplates/claude-hard-rules.mdを使用します — すでに## Living Docs強制ブロックが含まれています。コミット前にプレースホルダーを埋めてください。 docs/を、プロジェクトが必要とするディレクトリ（adr/、bdr/、issues/、prd/、research/、context/）とともに作成します。templates/constitution.mdからdocs/constitution.mdをシードします。バンドルルートのdocs/index.md（okf_version: "0.1"を保持）を追加し、各ディレクトリに初日から独自のindex.mdリストを追加します — ほぼ空でも構いません。- 存在するドメイン語彙でコンテキストインデックス（
docs/context/index.md）をシードし、ドキュメントがすでに前提としている用語と頭字語で用語集（docs/context/glossary.md）をシードします（rules/glossary-conventions.md）。概念が命名されるにつれて両方を成長させます。 - システムがすでに持っている高レベルのMermaidビューでアーキテクチャドキュメント（
docs/architecture.md）をシードします。成長したらdocs/architecture/ディレクトリ＋インデックスに昇格させます（rules/architecture-diagrams.md）。 - すでに行われた決定をADRとして記録し、再議論されないようにします — ただし、記録する前にそれぞれをユーザーと確認します（既存プロジェクトへのLiving Docs導入、手順3–5を参照）。推測のみでADRをバックフィルしないでください。
既存プロジェクト（ブラウンフィールド）へのLiving Docs導入
既存のコードベースは、決して文書化されなかった決定を具体化しています。ここでの失敗モードは、エージェントが推測によってADRをバックフィルし、確定済みとして提示することです — つまり、ユーザーに確認を求めることなく決定を記録することです。したがって、導入は転写作業ではなく、引き出し作業です。
- 強制モードの質問をする（初回実行）し、
## Living Docsブロックを保持します。新しいプロジェクトとまったく同じです。 - 決定せずにスキャフォールディング。
docs/+ 各ディレクトリのindex.md、バンドルルートのdocs/index.mdを作成し、**コード、README、およびエージェントガイド（CLAUDE.md/AGENTS.md）**にすでに存在する語彙から用語集/コンテキストインデックスをシードします。これは機械的な作業です — ここでは決定は行われません。 - まず既存のコンテキストを読み、次に決定を棚卸し — 記録ではなく候補として。 プロジェクトがすでに持っているものを収穫します: コード自体、さらに
README、エージェントガイド（CLAUDE.md/AGENTS.md）、パッケージマニフェスト、およびデザインノートやコメント。そこから、プロジェクトが具現化していると思われる重要な決定（スタック、境界、データモデル、主要なトレードオフ）のリストを作成します。まだADRは書かないでください。 - 棚卸しリストをユーザーに提示し、それぞれを確認します。 各候補について、推測される決定と、それが排除したと思われる代替案を述べ、ユーザーに確認、修正、または破棄を求めます — 重要なものは徹底的に詰めます（
grill-meがインストールされていれば使用）。決定を所有するのはユーザーです。エージェントはコードが示唆するものを表面化するだけです。 - 確認された決定のみをADRとして記録します。 これらは原初記録であり、何も廃止しません。選択されたオプションとユーザーが確認した却下された代替案をキャプチャします。ユーザーが破棄した候補、またはその根拠を誰も実際には知らない候補は、ADRとして発明されません。
- アーキテクチャドキュメントをシードし、システムがすでに持っている高レベルのMermaidビュー（
rules/architecture-diagrams.md）を追加し、その後以下の保守ループを再開します。
Living Docsの保守（すべてのタスク）
- コーディング前: プロジェクトガイドから
## Living Docs強制モードを読みます（ブロックがない場合は初回実行です — 初回実行の質問をし、回答を保持します）。次に、該当する憲法、ADR、BDR、およびコンテキストインデックスを読みます。変更する予定の領域に言及しているものを特定します。
…
[一部省略]