役割: 継続開発時の設計判断基準となる正本
対象読者: 新しい Brain（Codex / Claude Code / 後継モデル）
更新条件: 設計原則・責務境界・配置ルールが変わった時のみ
この文書は、butler2 のソースや検討ログを毎回深掘りしなくても、
新しい Brain が同じ設計思想・責務分離・実装配置ルールに従って継続開発できるようにするための基準書である。
この文書に書くもの:
設計原則・責務境界・配置ルール・不変条件・採用判断の基準
この文書に書かないもの:
直近 TODO・設定値・進捗・試験ログ・一時判断
理想的な理解順序:
STARTUP_CONTEXT.mdBrain のトークン消費を低レベル作業から切り離し、判断・設計・会話に集中させること。
この目的自体は旧 ButlerLayer から継承する。
ただし実現手段は見直し、butler2 では Butler を単なる provider 接続層ではなく、
複数の内部 worker 群を束ねる執事長として再定義する。
そのために以下を実現する。
Brain は要求、成功条件、制約を定義する。
反復実行、再試行、検証、経過監視は Butler 側へ寄せる。
Butler の下に直接ぶら下がるのは provider ではなく Maid 群である。
Butler の責務は routing / supervision / verification / approval にある。
Maid は Goose、script、将来の CLI/ACP worker を含む内部 worker 抽象である。
モデル名や接続先は Maid の属性であり、Butler の主語ではない。
OpenRouter、Ollama、local script などの差は registry と route へ寄せる。
Butler 本体へ provider 固有の判断ロジックを増やしすぎない。
Goose、Gemini CLI など AI を内部で使う Maid 実体は、完全自走前提では置かない。
補助あり部分成功を Butler supervisor で回復できるかを重視する。
Butler は implement 系 intent を受けたからといって、常に AI Maid へ委譲するとは限らない。
小さすぎるタスク、説明コストに比べて実行コストが軽いタスク、委譲失敗時の再作業コストが高すぎるタスクは、
Brain 直実行または別経路を許容する。
成功可否はモデルの完了宣言ではなく、検証結果と証跡で判定する。
Butler は verifier を持ち、Brain へ evidence を返す。
責務境界、Maid 抽象、routing、verification の変更は、関連文書まで同じ作業で更新する。
コードだけ先に進めて文書を放置しない。
最終承認や破壊的操作の判断は Brain 側に残す。
Maid に承認突破を持たせない。
Brain
│ 要求定義、成功条件、制約、最終判断
↓
Butler
│ contract / policy / routing / prompt building /
│ launcher / supervisor / verifier / approval
↓
Maid 群
Goose(OpenRouter)
Goose(Ollama)
Gemini CLI (Google AI Pro) ← 研究枠
Script worker
Future worker
| 責務 | 内容 |
|---|---|
| 要求の定義 | intent、spec、success criteria、制約を定義する |
| リスク許容判断 | 承認が必要な操作かを判断する |
| 結果の最終解釈 | Butler から返る evidence を読んで妥当性を判断する |
| 設計更新 | 必要な正本文書の更新を伴う意思決定を行う |
Brain がやってはいけないこと:
provider や model を主語にして逐次実装フローを組み立てること。
低レベルの再試行を自分で回すこと。
補足:
レビュー関連では、観測事実の収集や機械的確認は Butler / Maid に委譲できる。
ただし、evidence の最終解釈、重大度判断、承認可否判断は Brain が担う。
| 責務 | 内容 |
|---|---|
| 契約受理 | Brain の要求を解釈し制約を確認する |
| 委譲判断 | その task を委譲すべきか、Brain 直実行や別経路を許容すべきか判断する |
| ルーティング | 委譲する場合に intent に応じて適切な Maid を選ぶ |
| 実行準備 | prompt builder や launcher を通して実行を準備する |
| 監督 | 失敗や逸脱時に再依頼し、再試行を管理する |
| 検証 | verifier により結果を確認する |
| 承認連携 | 必要時のみ Brain 側へ承認判断を返す |
| 責務 | 内容 |
|---|---|
| 実務実行 | repo 探索、編集、テスト、定型処理など |
| 局所的判断 | 実装上の細部判断、修正、再試行への応答 |
Maid が持たないもの:
Maid が担ってよいレビュー関連作業:
Maid が担わないもの:
Butler 全体で再利用される基盤。
契約、routing、launcher、supervisor、verifier、approval のような全体責務を担うもの。
特定の Maid や特定領域に閉じた仕様。
たとえば Goose 固有の制約、formatter script の入出力仕様、個別 verification profile など。
人間がレビューしやすく、差分で追いたいものは初期段階では設定ファイルで持つ。
初期方針:
maid_registryintent_maid_routesverification_profileこれらはまず YAML ベースで管理する前提で考える。
docs/マスタードキュメント.mddocs/黒執事アーキテクチャ_v2.mddocs/capabilities/maid/仕様書_v3.mdSTARTUP_CONTEXT.mdMaid 実体の採用は、完全自走できるかどうかだけで決めない。
次を総合評価する。
Goose は現時点では limited_adoption 候補として扱うのが妥当であり、
supervision を前提に評価する。
Gemini CLI は現時点では research 枠として導入済みであり、execution_profile: gemini_cli_trial を明示した時だけ起動する。
実装系 Maid への委譲は、初期段階では無条件既定にしない。
少なくとも次のいずれかに当てはまる task を委譲候補とする。
逆に、次のような task は Brain 直実行または deterministic capability を優先してよい。
AI Maid への委譲が既定回数で失敗した場合、即座に「Brain が必ず直接やる」とは決めない。
Butler は失敗 evidence を返し、Brain は少なくとも次を見て次経路を判断する。
この方針により、委譲失敗後の最悪ケースを常態化させない。
1. その変更は全体原則に触れるか？
→ 触れるならマスタードキュメントと関連正本を更新する
2. その変更は Butler の責務追加か、Maid 個別仕様か？
→ Butler 全体なら上位文書へ
→ 個別仕様なら capabilities へ
3. provider 差を Butler 本体に埋め込もうとしていないか？
→ Maid 抽象へ戻せないか再確認する
4. AI Maid の不足を人間運用で吸収していないか？
→ Butler supervision へ寄せられないか考える
5. 成功判定を自己申告に頼っていないか？
→ verifier と evidence に戻す
以下のいずれかが起きたら本書を更新する。
docs/ドキュメント構成.mddocs/黒執事アーキテクチャ_v2.mddocs/capabilities/maid/仕様書_v3.mdSTARTUP_CONTEXT.md