役割: 文書を作成・更新・配置する際の判断基準
対象読者: Brain（新機能追加・文書更新を行う時）/ 実装者
Butler Layer の文書は以下の2つを明確に分離することが最重要。
設計哲学を継承する正本 と 前回セッションを再開するキャッシュ は別物である。
これを混ぜると、時間が経つほど正本が陳腐化し、新しい AI が進捗に引っ張られて設計原則を見失う。
| 文書 | 役割 |
|---|---|
docs/マスタードキュメント.md |
継続開発の判断基準（設計原則・責務境界・配置ルール・不変条件） |
docs/vision/00_ビジョン定義書.md |
最上位目的・思想・価値判断・長期方向性 |
docs/reference/01_アーキテクチャ定義書.md |
コンポーネント構成・ガバナンス |
docs/reference/02_契約通信仕様書.md |
Task/Result Contract の完全仕様 |
docs/reference/03_実行SOP仕様書.md |
SOP実行・Step kind・teach フォーマット |
docs/reference/04_データ運用仕様書.md |
SQLite スキーマ・冪等性・KPI |
docs/reference/05_Brain動作原則.md |
Brain が守るルールの詳細 |
正本セットの条件: 数週間後・別モデルが読んでも意味が変わらない内容のみ。
| 文書 | 役割 |
|---|---|
docs/README.md |
読者（Brain / 実装者）別の読む順序と文書の区分案内 |
docs/ドキュメント構成.md（本書） |
文書構成のメタ定義。4区分の定義・各文書の責任・更新ルール・読む順序 |
B区分の特性: 設計実装の正本ではなく、文書群をどう扱うかを定義する案内層。
内容が変わっても Butler の動作には直接影響しないが、文書の一貫性維持に影響する。
| 文書群 | 役割 |
|---|---|
docs/capabilities/ |
個別スキルの実装仕様・残タスク |
butler/skills_registry.py |
Brain 向けコントラクト公開インターフェース（全 Intent を網羅しない） |
docs/roadmap/ |
将来計画・優先順位（現在の設計正本ではない） |
docs/history/ |
実施記録・検討経緯（過去の記録であり現行ルールの正本ではない） |
docs/archive/ |
旧版保管（参照専用） |
| 文書 | 役割 |
|---|---|
STARTUP_CONTEXT.md |
前回セッションの直近進捗・TODO・設定値・未解決課題の再開用キャッシュ |
| 文書 | 書いてよい | 書いてはいけない |
|---|---|---|
マスタードキュメント.md |
設計原則、責務境界、配置ルール、不変条件、Intent 実装状態 | 直近 TODO、設定値、セッション固有の作業メモ |
ビジョン定義書.md |
なぜ作るか、思想、価値判断、長期方向性 | 実装詳細、直近進捗 |
reference/*.md |
アーキテクチャ・契約・SOP・DB・行動規約の詳細仕様 | 一時的な進捗メモ、試験結果 |
capabilities/*/仕様書.md |
スキル固有の実装仕様・フロー | 全体設計の原則 |
STARTUP_CONTEXT.md |
直近完了、次回 TODO、設定値、外部依存の未解決事項 | 設計原則、責務境界の定義 |
| 文書 | 更新契機 |
|---|---|
ドキュメント構成.md（本書） |
4区分の定義・各文書の役割・更新ルール・読む順序が変わった時 |
マスタードキュメント.md |
設計原則・責務境界・配置ルール・不変条件・Intent 実装状態が変わった時 |
ビジョン定義書.md |
最上位目的・思想・価値判断が変わった時 |
reference/*.md |
実装仕様・契約・SOP 仕様・DB スキーマが変わった時 |
capabilities/ |
個別スキルの実装ルールが変わった時 |
README.md |
本書（ドキュメント構成.md）の内容が変わった時、または入口導線が変わった時 |
CLAUDE.md などのツール固有起動ファイル |
起動順序・必読文書・委任ルールが変わった時。正本セットや README と矛盾させない |
STARTUP_CONTEXT.md |
セッション終了時（毎回更新） |
原則: コードを変更したら、影響する正本文書も同じ作業で更新する。文書の陳腐化はここで防ぐ。
設計哲学を先に理解し、そのあとで実務再開する順序を守ること。
再開キャッシュを先に読むと、設計原則より進捗に意識が引っ張られやすい。
ツール固有の起動ファイル（CLAUDE.md など）が存在する場合も、この順序と矛盾させない。
以下は理想的な理解順序である。
ただし、ツール固有起動ファイルでは「セッション開始に必要な最低限必読」を別途定義してよい。
その場合も、最低限必読はこの順序の思想と矛盾させない。
1. docs/README.md — 全体の地図を把握する
2. docs/マスタードキュメント.md — 何を守るべきかを理解する
3. docs/vision/00_ビジョン定義書.md — なぜそのルールがあるかを理解する
4. docs/reference/ 群 — どう実装されるかを確認する（必要な文書だけ）
5. docs/capabilities/ — スキル固有の詳細（必要な場合のみ）
6. STARTUP_CONTEXT.md — 今どこで止まっているかを確認する（実務再開時）
| 混在パターン | 対処 |
|---|---|
マスタードキュメント.md に直近 TODO が紛れ込む |
STARTUP_CONTEXT.md に移す |
STARTUP_CONTEXT.md に設計原則が書かれている |
マスタードキュメント.md または reference/ に移す |
reference/ に一時的な試験結果が混ざる |
history/ に移す |
capabilities/ に全体設計の原則が書かれている |
マスタードキュメント.md に移す |
skills_registry.py が Intent の唯一の正本になっている |
handler の HANDLED_INTENTS と sops テーブルが正本であることを明記する |
ButlerLayer/
├─ STARTUP_CONTEXT.md # D. 再開キャッシュ
├─ CLAUDE.md # ツール固有設定（Claude Code の動作ルール）
│ # ※ 4区分外。AI ツール依存のため正本セットに含めない
│ # ※ ただし内容は README / マスタードキュメント / 本書と矛盾させない
│
└─ docs/
├─ README.md # B. 利用ガイド（入口案内）
├─ ドキュメント構成.md # B. 利用ガイド（文書構成のメタ定義）
│
├─ マスタードキュメント.md # A. 正本セット（継続開発の判断基準）
│
├─ vision/ # A. 正本セット（思想層）
│ └─ 00_ビジョン定義書.md
│
├─ reference/ # A. 正本セット（詳細仕様層）
│ ├─ 01_アーキテクチャ定義書.md
│ ├─ 02_契約通信仕様書.md
│ ├─ 03_実行SOP仕様書.md
│ ├─ 04_データ運用仕様書.md
│ └─ 05_Brain動作原則.md
│
├─ capabilities/ # C. 補助資料（スキル別仕様）
│ ├─ trilium/
│ ├─ git/
│ └─ session_log/
│
├─ roadmap/ # C. 補助資料（将来計画）
├─ history/ # C. 補助資料（過去記録）
└─ archive/ # C. 補助資料（旧版保管）