愛称: 黒執事
作成日: 2026-03-08
ステータス: 正本
| 用語 | 定義 |
|---|---|
| Brain | 高性能AIコーディングツールの総称。Claude Code / Codex / antigravity / Cursor 等、その時点で利用可能なものを指す。特定のツールに固定されない |
| Butler（執事） | BrainからTask Contractを受け取り、タスクを実行して結果を返すPythonサービス全体。MCPサーバーとして動作し、内部にOrchestrator・Executor・Agent Executorを含む。ローカルLLM（Qwen）はButlerそのものではなく、Butlerが必要に応じて使う道具。愛称「セバスチャン」 |
| Orchestrator | Butler内部の実行制御エンジン（orchestrator.py）。Task Contractを受け取り、SOPを探して実行するか、Agentに自律実行を任せるかを制御する。Brainからは直接見えない |
| Executor | Orchestratorの配下でSOPの各ステップを実際に実行するモジュール群。cmd（シェルコマンド）/ check（検証）/ wait（待機）/ mcp_call（外部MCP呼び出し）の4種を処理する |
| Agent Executor | SOPが存在しない場合にOrchestrator が呼び出す自律実行モジュール。ローカルLLM（Qwen/Ollama）を使って、与えられた指示から自分でツール呼び出し手順を考えて実行する |
| SOP | Standard Operating Procedure。SQLiteのDBに保存されたステップリスト（JSONの配列）。Pythonコードではない。intent × target で照合され、Executorが順番に実行する。Brainが butler__teach で教えた手順が自動登録される |
| Task Contract | BrainからButlerへの依頼仕様（機械可読なJSON）。「何を達成したいか」を記述し、「どうやるか」は含まない |
| HITL | Human-in-the-Loop。破壊的操作など重要なステップで人間の承認を挟む仕組み |
| Trilium | 自己ホスト型のノート管理システム。個人の一時メモ・作業中の下書き置き場として使用する |
| Wiki.js | Git バックエンド対応のセルフホスト型 Wiki。プロジェクト横断の知識基盤として使用する。Gitea リポジトリと双方向同期し、タブレットからもブラウザで快適に読み書きできる |
| Redmine | プロジェクト管理・Issue 追跡システム。Butler 経由で Issue ライフサイクル管理（起票・担当・進捗・コメント・完了）を行う共同作業基盤 |
Brainが呼ぶのは常に Butler（MCPサーバー） である。OrchestratorやQwenをBrainが直接呼ぶことはない。
Brain（Claude Code / Codex / antigravity 等）
│
│ MCPツール経由（butler__submit_task / butler__get_status 等）
↓
Butler MCPサーバー / セバスチャン（butler/main.py）
│
└─ Orchestrator（butler/orchestrator.py）
│
├─ SOPあり → Executor が cmd/check/mcp_call を順番に実行
│
└─ SOPなし / agentモード → Agent Executor が Qwen（Ollama）を呼んで自律実行
│
└─ 外部MCPサーバー（Trilium等）を呼び出す
よくある混同：
Butler ≠ Qwen/Ollama — QwenはButlerが使う道具。ButlerはPythonサービス全体Brain → Butler であり Brain → Orchestrator ではない。OrchestratorはButlerの内部実装SOP = Pythonコード ではない。cmd/check/wait/mcp_call の4種のステップを並べたJSONリスト高性能AIコーディングツール（Claude Code / Codex / antigravity 等）は強力だが、
トークン消費が激しい。
探索・実行・確認・記録といった「雑務」をBrainにやらせると、
あっという間に制限に達し、作業が中断される。
制限にかかるたびに文脈が切れ、再開コストがかかる。
これは「AIと長時間・深く作業する」という体験を根本から壊す。
開発は、高性能なWindowsデスクトップだけでなく、
非力なLinuxノートPCやタブレットでも行う。
Git リポジトリはファイル数が多く、非力なデバイスでの全取得は現実的でない。
しかし「仕様を検討する」「方針を決める」「実装を振り返る」といった
軽量だが本質的な思考作業 は、どのデバイスでも行いたい。
思考はBrainに、実行はButlerに。作業はRedmineに。知識はWiki.jsに。
Brainのトークンを「判断・設計・会話」だけに使い、
定形作業・記録・確認は安価なローカルLLM（Butler）に委任する。
共同作業の履歴は Redmine の Issue に残し、
プロジェクト横断の知識は Wiki.js（Git バックエンド）に集約する。
どのデバイスからでもブラウザでアクセスできる。目指すのは「どこからでも、持続可能なペースで、AIと深く協働できる個人開発インフラ」。
1回のセッションで「設計→実装→テスト→記録」まで完結できること。
途中でトークン制限に引っかかって文脈が切れない作業体験。
どうやって: 実行・確認・記録の雑務を Butler（Qwen/Ollama）に委任し、
Brainのコンテキストを消費しない。
タブレットや非力なLinuxノートPCから、
「前回どこまで進んだか」「この設計の意図は何か」を参照できること。
また、そこで考えた変更方針が次のセッションに引き継がれること。
どうやって: 情報の性質ごとに適切な場所に置き、すべてブラウザからアクセスできる構成にする。
| 情報の性質 | 置き場所 | アクセス方法 |
|---|---|---|
| プロジェクト固有の設計・仕様 | プロジェクト内 docs/ |
Gitea Web UI / ローカルファイル |
| プロジェクト横断の知識 | Wiki.js（Git バックエンド） | ブラウザ（タブレット対応） |
| 共同作業の履歴・進捗 | Redmine Issue | ブラウザ（タブレット対応） |
| 一時的なメモ・下書き | Trilium | ブラウザ（タブレット対応） |
同じ作業を繰り返すたびに、手順（SOP）が蓄積され、
次回からの委任がよりスムーズになること。
「初回は教える、次回からは任せる」サイクルの確立。
Butler Layer には2つの層がある。混同しないこと。
Butlerが「動く」ための基盤。特定の用途に依存しない。
Butlerが「習得した」能力。コアの上に積み上げられる。
record_to_trilium / read_from_trilium）read_from_redmine / record_to_redmine）git_commit / git_push / git_pull）read_from_wiki / record_to_wiki）スキルの実体は SOP + 必要なツール設定 である。
コアに手を入れることなく、スキルを追加・変更・削除できることが理想。
butler/capabilities/<スキル名>/tools.py を作成し、以下を export する：
TOOL_DEFS: list[dict] # Ollama function calling 形式のツール定義
INTENT_REQUIRED_TOOLS: dict[str, list[str]] # intent 検証用ツール名セット
async def run_tool(name, args, timeout_sec, **kwargs) -> str # 実行ハンドラ
agent_executor.py は起動時に capabilities/*/tools.py を自動スキャンしてロードする。
コアに手を入れる必要はない。
agent_executor.py からTrilium関連コードを分離済み → butler/capabilities/trilium/tools.pytrilium_structure_ops.py は orchestrator から直接呼ばれる構造運用モジュール。| やらないこと | 理由 |
|---|---|
| Brainによる設計・判断の代替 | アーキテクチャ決定・実装方針・問題の診断はBrainの仕事 |
| 汎用AIエージェントの構築 | n8n / Windmill / LangChain の代替ではない。Brainのトークン節約に特化 |
| 最初から全手順を定義する | SOPは事後に学習・蓄積する設計。事前定義型フローではない |
| 複数ユーザーへの対応 | 個人開発インフラとして設計。チーム運用は想定外 |
| すべてを1つのツールに集約すること | 情報の性質ごとに最適な場所がある。集約先の能力が落ちると本末転倒になる |
注意: Butlerの能力を高めることはNOTリストではない。
Butlerが自律的に複数ステップをこなせなければ、Brainがループを回すことになり、
トークン節約という目的に逆行する。
最も重要な原則。
BrainがステップA→B→Cを繰り返し実行しているなら、
そのループはButlerの中にあるべきである。
悪い例（Brainがループを回す）:
Brain: Triliumの現状ノード構成を取得する
Brain: ファイル1を配置場所を決めてTriliumに登録する
Brain: ファイル2を配置場所を決めてTriliumに登録する
Brain: ファイル3を... （繰り返し）
良い例（Butlerがループを処理する）:
Brain: 「これらのファイルをTriliumに登録して」とButlerに委任する（1回）
Butler: ノード構成を取得し、配置を判断し、全ファイルを登録する
Brainの仕事は「何を達成したいか」を伝えることだけ。
「どうやるか」の手順・ループ・判断はButlerの中で完結させる。
Brainが細かい作業単位でButlerを呼ぶのではなく、
できるだけ大きな作業単位をまとめて委任する。
Butlerのローカルモデルには、その指示の範囲内で自律的に動く能力がある。
その能力を使わないことはトークンの無駄遣いである。
Brainは Claude Code であることもあれば、Codex・antigravity・Cursor であることもある。
現在使えるAIが変わっても、Butler Layer は同じように機能しなければならない。
Butler との接点（Task Contract）は特定のAIツールに依存しない設計である。
文書・SOP・Triliumのノートもツール非依存で書く。
Butlerを賢くすること自体は目的ではない。
しかし、Butlerが賢くなることでBrainの委任粒度を大きくできるなら、
それはトークン節約という主目的に直結する投資である。
Butlerのモデル選定・能力強化は「Brainのトークン消費を減らせるか」を判断基準とする。
Butlerが蓄積するSOPは、単なる手順書ではない。
「次回のBrainが考え直さなくて済む」トークン節約の蓄積物である。
過去の判断が未来のコストを下げる。
すべてを1箇所に集約するのではなく、情報の性質に応じた最適な場所に置く。
docs/（AI が直接読める、コードと一体）分散ではなく 役割分担 である。Butler がこれらを横断的に参照・記録することで、
人間も AI も「どこを見ればいいか」を意識しなくて済む状態を目指す。
問題が出たとき、症状を薄める対策ではなく根本原因を直す。
「なぜ？」を連鎖させ、原因の原因まで追ってから対策を考える。
これはButlerへの要件であり、このプロジェクト自体の開発方針でもある。
Brain（高コスト）= 判断・設計・会話・方針決定
Butler/Qwen（低コスト）= 実行・確認・記録・ループ処理
Redmine（ゼロコスト）= 共同作業の追跡・可視化
Wiki.js（ゼロコスト）= 知識の構造化・持ち歩き
Trilium（ゼロコスト）= 個人メモ・下書き
この役割分担を守ることが、システム全体の持続性を保つ。
向いている:
向いていない:
docs/reference/01_アーキテクチャ定義書.mddocs/reference/05_Brain動作原則.mddocs/roadmap/Phase6以降_実装計画.md