作成日: 2026-04-01
ステータス: Draft
対象: implement
関連文書:
本仕様は、butler2 における implement capability の初期仕様を定義する。
implement の目的は、
Brain が実装仕様を渡した時に、Butler が適切な AI Maid へ委譲し、可能ならコード変更・関連文書更新・検証まで完了させて evidence を返す
ことである。
理想状態は次の通り。
session_log summarize では、既に Goose 系 Worker Instance を Butler 配下の AI Maid として起動する最小経路が成立している。
implement はこの仕組みを一般化し、要約ではなく repo 変更を伴う実務委譲へ広げる capability である。
ただし、実装系 task は session_log summarize より難易度が高い。
そのため初期段階では次を明示的に前提とする。
implement は、実装仕様を受けて AI Maid に repo 作業を委譲する domain capability である。
担当範囲:
Brain は「何を達成したいか」「何を成功とみなすか」「どこまで触れてよいか」を渡す。
Butler は「どの Maid に委譲するか」「何回まで再試行するか」「何で成功判定するか」を管理する。
Brain が主に渡すもの:
Brain が直接管理しないもの:
MCP facade を経由する場合も、この境界は変えない。
MCP は TaskContract を Butler core に渡す入口であり、
実際の watchdog / verification / retry は ImplementMaid と runtime 側で扱う。
初期版 implement が目指す標準完了状態は次の通り。
AI Maid の能力不足により、常に上記を満たせるとは限らない。
そのため Butler は次を許容する。
MCP 経由では、implement は長時間 tool call になりうる。
そのため facade 側では少なくとも開始・dispatch・終了の progress を返し、
細かい実行監視は core の watchdog に委ねる。
implement はコードに限定しない。
必要なら次も含めてよい。
ただし、広すぎる task は成功率を下げる。
初期段階では「1 つの明確な目的に収まる実装 task」を推奨する。
基本 contract:
intent: implementtarget.service: localdelegation_mode: known_only初期版では known_only のみを使用する。
known_only は Butler が既知の Maid にのみ route することを意味する。
agent モード（未知 worker の学習・外部委任を含む動的選択）は現時点では未実装であり、将来拡張として予約する。
現行実装では implement は次の入口から呼び出せる。
execute_task())butler2)butler2-mcp の run_implement tool)いずれの入口でも、最終的には同じ Butler core と ImplementMaid を通る。
したがって watchdog、verification、scope_check、supervision の意味は入口によって変わらない。
implement では次を受け取れるようにする。
| 項目 | 必須 | 内容 |
|---|---|---|
goal |
必須 | 何を実現したいかの短い要約 |
spec |
必須 | 実装仕様本文。仕様書パス、要約、あるいはその両方 |
target_paths |
任意 | 主対象として編集・探索してほしいパス群 |
context_files |
任意 | 先に読むべき文書やコード |
acceptance_tests |
任意 | 実装完了とみなす検証コマンドや確認項目 |
deliverables |
任意 | 期待成果物。コード、テスト、文書など |
notes |
任意 | 補足指示 |
execution_profile |
任意 | モデル特性に合わせた task shaping profile。既定は default |
ただし初期版では、「受け取れる」と「そのまま受理する」は同義ではない。
implement は preflight validation を通過した contract のみを受理する。
file_checks を使う場合、contains は単一文字列のみを受け付ける。
複数キーワードを確認したい場合は、file_checks を複数行に分けて書く。
spec の扱いspec は最低でも次のいずれかを含む。
理想的には、Brain が capability 仕様書や issue 本文を渡し、
Butler がそれを prompt に埋め込んで Maid に渡せる形にする。
ただし、長い仕様をそのまま Maid に渡すと、低性能寄りの worker では実装精度が下がる可能性がある。
初期方針としては、長い仕様を Butler が自由要約するより、Brain が task を分割して短い spec にすることを優先する。
Butler は task 分割器や要約器ではなく、contract を定型 prompt に写像する整形器として振る舞う。
必要に応じて次を構造化して prompt に載せる。
execution_profileexecution_profile は、Brain 側がモデル特性を踏まえて task を加減するための入口指定である。
現在利用可能な profile:
defaultgrok_fast_safegemini_cli_trialgrok_fast_safe は、Grok 4.1 Fast の implement worker を重すぎる task から守るための保守的 profile であり、
少なくとも次を小さめに制限する。
target_pathscontext_filesacceptance_testsfile_checksverification 条件数spec 長success_criteria 数gemini_cli_trial は、Gemini CLI Maid（gemini_cli_implement）向けの制約 profile である。
gemini_cli_implement が既定 route になったため、routing のための明示指定は不要になった。
ただし制約値（max_target_paths=3 等）は gemini_cli_trial profile として引き続き有効であり、
task が小さい場合はこの profile を指定して constraint を明示的に適用してもよい。
制約（preflight で強制される上限値）:
| 項目 | 上限 |
|---|---|
target_paths |
3 |
deliverables |
4 |
success_criteria |
5 |
spec 長 |
6,000 文字 |
context_files |
4 |
acceptance_tests |
2 |
file_checks |
4 |
verification essential 条件 |
2 |
verification evidence 条件 |
2 |
verification soft 条件 |
2 |
task がこの制約を超える場合は preflight で need_input が返る。制約を超える場合は task を分割して再送する。
いずれの profile も fixed rule ではなく、実タスク観測を通じて調整する前提とする。
長文仕様の全文参照は補助的なものとし、Maid へ渡す主入力はできるだけ短く保つ。
deliverables の初期例codetestsdocsconfigdeliverables は必須ではないが、明示されている方が成功率は上がる。
implement は Brain へのプロンプト指示だけで運用を守らせない。
初期版では、Butler が contract の受理条件を機械的に検査し、条件を満たさない依頼は Maid に渡さない。
最低限の受理条件:
goal が空でないspec が空でないsuccess_criteria が 1 件以上あるconstraints.implicit_scope が 1 件以上あるtarget_paths が 1 件以上ある補足:
deliverables は推奨だが、初期版では必須にしないacceptance_tests は推奨だが、未指定でも verification_profile で補える限り受理可能Butler は Maid 起動前に preflight validation を行う。
これは Brain の善意や注意力ではなく、仕組みとして task 品質を強制するための入口検査である。
初期版で検査する項目:
target_paths が implicit_scope の範囲内に収まっているかspec が空や極端に短い曖昧記述でないかsuccess_criteria が検証可能な形になっているかexecution_profile が既知で、その profile 制約を超えていないかButler は preflight 時に task の複雑さを概算し、少なくとも次を集計する。
target_paths 数context_files 数acceptance_tests 数file_checks 数deliverables 数success_criteria 数verification 条件数spec_lengthこれを complexity_score と band (small / medium / heavy) に要約し、
preflight reject の根拠や execution_profile 違反時の guidance に使う。
初期段階では Brain がこの score を見て task を再分割し、
Butler は score 自体で route を変えるまでは行わない。
success_criteria の最低品質初期版では、success_criteria は少なくとも 1 件以上あり、
人間または verifier が確認可能な記述でなければならない。
望ましい例:
uv run pytest tests/test_runtime.py -q が通るimplement intent が route される仕様書とコードの責務境界が一致している避けるべき例:
いい感じに実装する必要なら直すうまく動くようにする初期版では、task 分割を Butler が代行しない。
そのため、委譲単位が大きすぎる依頼は preflight で reject する。
代表的な reject 条件:
spec が長大で、1 回の implement task として扱うには広すぎるtarget_paths が広すぎて主対象が定まっていないdeliverables が多すぎて 1 task の成果物として収まりにくいsuccess_criteria が複数の独立 task を内包しているこの場合、Butler は task を自動分割せず、
「task が大きすぎるため分割が必要」という need_input を返す。
次の場合、Butler は implement を受理せず need_input を返してよい。
target_paths が空であるimplicit_scope が空であるtarget_paths と implicit_scope が矛盾しているsuccess_criteria が検証不能であるconstraints.implicit_scopeconstraints.implicit_scope は、
この task で触れてよい領域の上限境界を表す。
例:
repo:akira/butler2path:docs/capabilities/implementpath:butlerこれは安全境界であり、
「この範囲の外へ勝手に広げない」という意味を持つ。
implicit_scope の強制手段Goose は subprocess として起動される外部プロセスであるため、
Butler が implicit_scope をファイルシステムレベルで完全強制する手段は現時点では持たない。
初期版における強制手段は次の 2 層構成とする。
Butler は prompt に implicit_scope を明示し、Maid に範囲外を操作してはならないことを通知する。
そのうえで、実行後は Butler 自身が Git 差分から changed_files を算出し、
implicit_scope 外の変更がないかを確認する。
違反が検出された場合は failed として evidence を返す。
scope 違反による失敗は再試行しない（再試行しても同じ違反が繰り返されるだけのため）。
payload.target_pathstarget_paths は、
今回の task で優先的に見てほしい作業対象を表す。
例:
butler/runtime.pybutler/maids/config/intent_maid_routes.ymlimplicit_scope との違い:
implicit_scope は触ってよい範囲の上限（ガードレール）target_paths はその中でまず狙うべき対象（作業フォーカス）初期方針として、両方を併用できるようにする。
implement は少なくとも次の task を委譲候補とする。
次の task は非委譲でもよい。
implement は intent_maid_routes.yml の記述順と conditions_json で route する。
優先度数値は持たず、条件に一致した最初のエントリが選ばれる。
既定 Worker（条件なし・先着）:
gemini_cli_implement（Gemini CLI 直接起動）明示指定 Worker（execution_profile: grok_fast_safe 指定時）:
goose_openrouter_grok41fast_implementその他の model 候補（研究枠・常設しない）:
qwen/qwen3-coder-nextqwen/qwen3-coder-30b-a3b-instructgoogle/gemma-4-27b-it（OpenRouter）gemma4:27b（Ollama）候補から外す model:
deepseek/deepseek-v3.2（成果物は成立しても worker_timeout になりやすい）route 方針:
gemini_cli_implement（Google AI Pro 枠、Goose + OpenRouter への従量課金を抑える）execution_profile: grok_fast_safe を明示して goose_openrouter_grok41fast_implement に route する設定ファイルとの対応:
config/intent_maid_routes.yml に記載するconfig/maid_registry.yml に記載するconfig/maid_registry.yml に追加し、必要なら config/intent_maid_routes.yml で一時的に route するGeminiCliImplementMaid（butler/maids/gemini_cli_implement_maid.py）は、Goose を経由せず Gemini CLI を直接 subprocess として起動する実装 Maid である。
位置づけ:
execution_profile を省略した場合（default）に route されるexecution_profile: grok_fast_safe を明示する既存 Maid との違い:
| 項目 | GooseImplementMaid | GeminiCliImplementMaid |
|---|---|---|
| 起動方法 | goose run --instructions ... |
gemini --approval-mode auto_edit --output-format json -p ... |
| provider | OpenRouter | Google AI Pro（GOOGLE_GENAI_USE_GCA=true） |
| 認証 | OpenRouter API key | Google アカウント事前ログイン済みキャッシュ |
| JSON 出力 | Goose 固有形式 | {"session_id", "response", "stats"} |
| Goose 固有 evidence | あり | なし（gemini.stats として返す） |
前提条件（事前に人間が対応）:
gemini CLI が PATH 上にインストール済み（npm install -g @google/gemini-cli）gemini 対話モードで Sign in with Google 認証済みGOOGLE_GENAI_USE_GCA=true、GEMINI_CLI_TRUST_WORKSPACE=true が環境変数として設定済み設計の詳細は docs/検討用/61_Gemini CLI専用Maid実装案.md を参照する。
1. Brain -> Butler: implement contract を送る
2. Butler: route を解決する
3. Butler: baseline を記録する
4. Butler: prompt を構築する
5. Butler: AI Maid を起動する
6. Maid: 探索、編集、テスト、文書更新を行う
7. Butler: Git 差分から changed_files を算出する
8. Butler: verifier を実行する
9. 成功なら evidence を返す
10. 失敗なら supervision で再依頼する
11. 既定回数超過で failed を返す
implement は初期版から supervision 前提とする。
既定値:
各再依頼では少なくとも次を Maid に返せるようにする。
implement の成功判定は「実装しました」という自己申告で完了させない。
Butler は少なくとも次のいずれかで確認する。
test_commandsfile_checksexact_outputimplicit_scope 外への変更がないことの確認Verifier は、可能な限り実装の本質を確認する。
本質とは、要求された振る舞い、route / registry / import の整合、テスト通過、制約順守などを指す。
一方で、次は原則として本質ではない。
ただし、名前の違いが route / import / registry の不整合を引き起こす場合は本質的問題として扱う。
初期版では、可能なら最低でも次を evidence に含める。
acceptance_tests が与えられた場合は、それを優先する。
未指定の場合は、Maid 定義の verification_profile と repo 慣習に従って Butler が既定の検証を選ぶ。
Verifier は、必要以上に特定の命名を固定しない。
たとえば特定ファイル名そのものより、entrypoint・route・registry・import が整合して実際に動くことを優先して確認する。
命名固定が必要なのは、その名前が外部設定や import path の一部として契約化されている場合に限る。
acceptance_tests の初期形式初期段階では次のどちらかを許容する。
ただし自動 verifier で実行できるのは、Butler 側 allowlist に入ったコマンドだけである。
allowlist 外のコマンドは evidence に「未実行」として残し、Brain の判断に委ねる。
初期方針として、allowlist は config/verifier_allowlist.yml のような独立設定で管理する。
ただし、この設定ファイル自体は implement 実装時に新設する。
Maid は作業中に退避コピーや補助ファイルを作ってよい。
例:
*.bakただし、これらは最終成果物として残さないことを原則とする。
Butler は「一時的に作られたか」ではなく、「最終状態に不要物が残っているか」を検査する。
初期方針:
.bak を途中で作ること自体では fail にしない.bak や不要生成物が残っていれば fail にしてよいButler が Maid に渡す prompt には少なくとも次を含める。
再試行時（2 回目以降）は、コンパクト形式のプロンプトを使用する。
これは長い仕様を再度全文載せず、前回失敗の要点と修正指示に絞ることで、トークン消費を抑えるためである。
初期方針として、prompt には次も明示する。
implement の返却 evidence は、Brain が次経路を判断できる粒度を持つ必要がある。
最低限返すべき項目:
maid_idattempt_countchanged_filesbaseline_refscope_violationtest_resultssummarystdout_tailstderr_tailchanged_files は Maid の自己申告ではなく、Butler が Git 差分から算出する。
初期方針として、差分基準は task 開始時に記録した baseline 参照とする。
baseline の取り方:
need_input を返す（ImplementMaid は起動しない）Butler は未承認で git clean、reset --hard、自動 stash を行わない。
任意で返してよい項目:
verification_plan — Butler が実行した検証の構造（acceptance_tests と file_checks の内容）成功時はさらに次を含めるとよい。
verification_passeddeliverables_completed失敗時はさらに次を含める。
failed_stagefailure_reasonnext_recommendation初期版では次を必須にしない。
implicit_scope の技術的完全強制agent モードによる動的 Maid 選択implement intent を新設するmaid_registry / intent_maid_routes で既存 Goose Maid に route できるようにするimplicit_scope 確認を入れるbaseline_ref / scope_violation / test_results を返すGemini CLI を Butler 配下の研究枠 Maid として追加した。
GeminiCliImplementMaid（butler/maids/gemini_cli_implement_maid.py）を新規実装config/maid_registry.yml に gemini_cli_implement を追加（enabled: true）config/intent_maid_routes.yml に execution_profile: gemini_cli_trial 条件付き route を追加butler/maids/implement_common.py へ抽出（Goose 版・Gemini 版双方で使用）GeminiCliImplementMaid を task branch 方式・Butler 側 commit に移行（Goose 版と同じ監督意味論）work_branch を主役にし、成功時の next_required_action を work_publish に統一work_publish() の upstream なし branch 対応を追加execution_profile: gemini_cli_trial の preflight 制約を設定（§6.2.1 参照）Phase 2 以降の詳細は、実際に implement task を複数回流し、失敗パターンを観測してから固める。
初期段階では Phase 1 を成立させることを優先する。
特に次は、実測前に決め打ちしない。
implement capability の核心は、
Brain が仕様と成功条件を渡し、Butler が AI Maid を選択・監督・検証して、可能なら実装とテストまで完了させる
ことにある。
初期版では万能性を狙わず、
「仕様書を元に、限定された範囲で、検証付きの実装を完了させる」
ことを最初の成立条件とする。