黒執事（Butler Layer)

設計検討記録（2026-03-21）¶

参考モデル: Serena の initial_instructions パターン¶

MCP サーバーである Serena が mcp__serena__initial_instructions というツールを提供しており、「まずこれを呼べ」と MCP Server Instructions に書かれている。このパターンを Butler にも採用する。
今後設計に迷ったら Serena の実装を調べると良い。

ツール形態: 直接ツール¶

submit_task 経由の intent ではなく、butler__get_session_guidance のような直接ツールとする。
理由: セッション開始の最初に呼ぶものなので、コントラクトを組み立てるのは重すぎる。get_skill_usage や list_skills と同じ位置付け。

入力パラメータ¶

• phase: "start" / "end" — セッションのどのタイミングか
• project_path: 作業ディレクトリ — どのプロジェクトか判定
• client: "claude_code" / "codex" — LLM 種別（指示ファイルの書き込み先を変えるため）

出力（phase: start）¶

• 読むべきファイル一覧
• 前回セッションのスナップショットへのパス
• 初参加の場合: 指示ファイルへの書き込み内容
• 開発手順の変更があれば通知

出力（phase: end）¶

• やるべきこと（session_log summarize の具体的な呼び方）
• 更新すべきファイル

ガイダンスの管理: グローバル + ローカルの 2 層 YAML¶

配置:

• グローバル: C:\Users\akira\Develop\00_開発共通\.butler\guidance.yaml
• ローカル: <プロジェクト>/.butler/guidance.yaml

マージ戦略:

• ローカルに inherit: true があれば、グローバル + ローカル（追加）
• inherit: false または省略 → ローカルのみ（置き換え）
• ローカルファイル自体が無い → グローバルのみ

これにより、プロジェクト固有の手順がある場合は完全置き換えも、グローバルに追加だけもどちらも可能。

Butler がグローバルパスを知る方法: butler/config.yaml¶

Butler のコードの隣に設定ファイルを置く。

ButlerLayer/butler/config.yaml

内容は今必要なものだけ:

global_guidance_dir: C:\Users\akira\Develop\00_開発共通\.butler

Butler は Path(__file__).parent / "config.yaml" で見つける。
設定が複雑化して「設定ファイルのせいで動かない」にならないよう、最小限に保つ。

設計検討記録続き（2026-03-21）¶

論点 3: 手順変更通知 → 不要¶

Butler は毎回 guidance.yaml を読んで、書いてある通りに返すだけ。
前回との差分検知は不要。常に最新が返るので、変更通知の仕組みは要らない。

論点 2: 初参加判定 → Butler はやらない¶

LLM は毎セッション記憶がリセットされるので、「初参加かどうか」はセッション単位では判定できない。
Butler は初参加判定をしない。毎回同じガイダンスを返す。
Brain 側が自分の指示ファイルを見て、既に書き込み済みならスキップするだけ。

論点 1 と 4: guidance.yaml スキーマと MCP Server Instructions → 02 が先¶

guidance.yaml に何を書けるかも、MCP Server Instructions に何と書くかも、02_開発ワークフロー.md の内容が決まらないと決まらない。
02 の検討が先。

進め方の方針¶

get_session_guidance を先に実装して動かしてみる。
そこで色々出てきた問題を踏まえて、guidance.yaml のスキーマと 02 の内容を決める。

docs/capabilities/session_guidance/仕様書.md として実装仕様書を作成しコミット済み（6d403c8 refs #143）。

Codex はこの仕様書を見て実装すること。

実装完了メモ

• butler__get_session_guidance を直接ツールとして追加
• MCP Server Instructions に start/end 時の呼び出し手順を追加
• butler/guidance.py で global + local guidance.yaml の読込、inherit マージ、{{client}} / {{project_path}} 置換を実装
• butler/config.yaml を追加し、共通ガイダンス参照先を設定
• tests/test_guidance.py を追加し、global only / local only / inherit true/false / guidance 不在 / invalid phase を検証

検証:

• python -m pytest tests/test_guidance.py tests/test_main_submit_sync.py tests/test_mcp_tools.py tests/test_smoke.py
• butler__get_session_guidance(start/end) を ButlerLayer で live 実行し、start で STARTUP_CONTEXT.md、end で session_log summarize アクションが返ることを確認

コミット:

• c2918a1 feat: add session guidance tool refs #143

補足:

• 共有ガイダンス定義を 00_開発共通/.butler/guidance.yaml にもコミットしました
• commit: e1c936a chore: add shared butler guidance refs #143

get_session_guidance 動作確認結果

VS Code 再起動後、MCP 経由でツールが正常に認識・呼び出しできることを確認した。

確認環境¶

• client: claude_code
• project_path: c:\Users\akira\Develop\ButlerLayer

テスト内容¶

ローカル .butler/guidance.yaml（テスト用）を作成し、グローバル（00_開発共通/.butler/guidance.yaml）とのマージ動作を検証。

# テスト用ローカル guidance.yaml
on_start:
  inherit: true
  read_files:
    - docs/マスタードキュメント.md
  messages:
    - "【テスト】ローカルガイダンスが正常に読み込まれました (client={{client}})"
on_end:
  inherit: true
  actions:
    - type: log
      description: "【テスト】セッション終了アクション"
  messages:
    - "【テスト】セッション終了ガイダンスです (project={{project_path}})"

結果: 全項目 OK¶

テスト用 .butler/guidance.yaml は確認後削除済み。