役割: 文書を作成・更新・配置する際の判断基準
対象読者: Brain（新機能追加・文書更新を行う時）/ 実装者
butler2 の文書は以下の 2 つを明確に分離することを最重要とする。
設計哲学を継承する正本と、前回セッションを再開するためのキャッシュは別物である。
これを混ぜると、時間が経つほど正本が陳腐化し、新しい Brain が直近進捗に引っ張られて設計原則を見失う。
butler2 は ButlerLayer の目的を継承しつつ、内部実装を大きく見直した再始動プロジェクトである。
そのため旧プロジェクトの文書思想は受け継ぐが、Maid の位置づけや worker routing のような再定義点は新しい正本としてここで管理する。
設計哲学の継承責任を持つ文書群。
数週間後・別モデルが読んでも意味が変わらない内容のみを書く。
| 文書 | 役割 |
|---|---|
| マスタードキュメント | 継続開発の判断基準。設計原則・責務境界・配置ルール・不変条件 |
| 黒執事アーキテクチャ v2 | Butler / Maid / routing / supervision を含む上位アーキテクチャ |
入口案内とメタ管理の文書群。
自分自身は正本ではないが、正本をどう読むかを定義する。
| 文書 | 役割 |
|---|---|
| README | 読者別の読む順序と文書群の案内 |
| ドキュメント構成 | 文書体系のメタ定義。本書 |
| Butler 利用ガイド | 新しく Butler を使う Brain 向けの入口案内。目的、使いどころ、呼び出し入口を説明する |
| Track Ledger 運用マニュアル | 探索・方針転換・やり直しを親 Issue と子 track で追跡するユーザー / Brain 向け手順 |
| 外部プロジェクト利用ガイド Ubuntu | 別プロジェクトから Butler を Ubuntu で呼ぶための導入手順 |
| 黒執事開発中用手順書 | 開発中の butler2 を Brain が実務で扱うための手順書 |
正本を補完するが、全体設計の正本にはしない文書群。
| 文書群 | 役割 |
|---|---|
| capabilities 一覧 | capability / Maid / skill ごとの個別仕様 |
docs/history/ |
検討経緯・試験結果・task contract 設計例などの過去判断記録 |
docs/archive/ |
旧版保管 |
正本ではない。
設計哲学の継承責任を持たせず、直近の再開に必要な情報だけを置く。
| 文書 | 役割 |
|---|---|
STARTUP_CONTEXT.md |
直近進捗・TODO・設定値・未解決課題の再開用キャッシュ |
| 文書 | 書いてよい | 書いてはいけない |
|---|---|---|
マスタードキュメント.md |
設計原則、責務境界、配置ルール、不変条件、採用方針 | 直近 TODO、セッション固有メモ、暫定作業ログ |
黒執事アーキテクチャ_v2.md |
Butler / Maid / routing / supervision の上位構造 | 直近の試験結果、生ログ、短期メモ |
capabilities/*/仕様書*.md |
capability 固有の仕様、実装方針、補助概念 | 全体設計の原則 |
黒執事開発中用手順書.md |
開始手順、読む順序、開発中の補正ルール | 設計原則そのもの、不変条件 |
Butler利用ガイド.md |
Butler の目的、向いている task、API/CLI/MCP の入口、初回疎通の勘所 | 全体設計の不変条件、直近 TODO、試験ログ |
STARTUP_CONTEXT.md |
直近完了、次回 TODO、設定値、外部依存の未解決事項 | 設計原則、責務境界の定義 |
| 文書 | 更新契機 |
|---|---|
ドキュメント構成.md |
文書区分、各文書の責務、読む順序が変わった時 |
マスタードキュメント.md |
設計原則、責務境界、配置ルール、不変条件が変わった時 |
黒執事アーキテクチャ_v2.md |
Butler / Maid / routing / supervision の上位構造が変わった時 |
外部プロジェクト利用ガイド_Ubuntu.md |
Ubuntu 向け外部利用時の導入手順、前提ファイル、起動方法が変わった時 |
capabilities/ |
個別 capability や Maid の仕様が変わった時 |
README.md |
本書または入口導線が変わった時 |
Butler利用ガイド.md |
新しい Brain が Butler を使い始める標準入口や注意点が変わった時 |
黒執事開発中用手順書.md |
Brain が開発中の butler2 を使い始める標準手順が変わった時 |
STARTUP_CONTEXT.md |
セッション終了時、または再開用情報を更新したい時 |
原則:
コードを変更したら、影響する正本文書も同じ作業で更新する。
butler2 は内部実装の再構築が前提のため、コードだけ先行して文書が追随しない状態を長く残さない。
設計哲学を先に理解し、そのあとで実務再開に入る順序を守る。
再開キャッシュを先に読むと、進捗に意識が引っ張られて責務境界を誤解しやすい。
理想的な理解順序:
1. [docs/README.md](/butler2)
2. [docs/Butler利用ガイド.md](/butler2/Butler利用ガイド)
3. [docs/マスタードキュメント.md](/butler2/マスタードキュメント)
4. [docs/黒執事アーキテクチャ_v2.md](/butler2/黒執事アーキテクチャ_v2)
5. [docs/外部プロジェクト利用ガイド_Ubuntu.md](/butler2/外部プロジェクト利用ガイド_Ubuntu)
6. [docs/黒執事開発中用手順書.md](/butler2/黒執事開発中用手順書)
6. [docs/capabilities/ 群](/butler2/capabilities)
7. STARTUP_CONTEXT.md
現時点で README.md が未整備でも、この順序思想は維持する。
不足している文書は今後追加し、既存文書の役割と矛盾させない。
| 混在パターン | 対処 |
|---|---|
マスタードキュメント.md に直近 TODO が紛れ込む |
STARTUP_CONTEXT.md に移す |
黒執事アーキテクチャ_v2.md に試験ログや一時判断が混ざる |
history/ に移す |
capabilities/ に全体設計の原則が書かれている |
マスタードキュメント.md またはアーキテクチャ文書へ移す |
STARTUP_CONTEXT.md に設計原則が書かれている |
マスタードキュメント.md に移す |
| capability 仕様が Butler 全体の真実源になっている | 上位原則は マスタードキュメント.md と 黒執事アーキテクチャ_v2.md に戻す |
butler2/
├─ STARTUP_CONTEXT.md
└─ docs/
├─ README.md
├─ ドキュメント構成.md
├─ Butler利用ガイド.md
├─ 外部プロジェクト利用ガイド_Ubuntu.md
├─ 黒執事開発中用手順書.md
├─ マスタードキュメント.md
├─ 黒執事アーキテクチャ_v2.md
├─ capabilities/
├─ history/
└─ archive/
butler2 はまだ文書再整備の途中だが、将来用の空ディレクトリは先に置かない。
必要な文書群は、必要が生じた時点で追加する。
ただし、新規文書はこの責務分離を意識して配置する。