Opus4.7が心配だったので実装を矯正するツールを作ったはなし
こんにちは、かがわ（@shinpr_p）です。
私は去年からAIコーディングエージェントになるべく自律して開発をしてもらえるよう環境を整備してきました。おかげでかなり任せられるようになったのですが、 Opus 4.7 のリリース以降、最後の実動作確認などをする前に「ちょっと Codex に見てもらう」ようになってしまいました。
それを 3 回以上やったので、仕組み化（ツール）しました。ローカルで Claude Code（以下 CC ）に実装させ、別のエージェント（ Claude もしくは Codex ）が実装を読んで合否を出し、承認されたら PR が提出される小さなランタイムです。
このツールを作った背景
私は直近、プロダクト 3 本の開発案件と自作 OSS のメンテナンスをしています。プロダクトはフェーズも規模も様々です。
大規模タスクは、設計をしてもらい、作業計画を作り、E2E/結合テストの概要（スケルトン）を作成してから、価値の届く単位での動作確認ができるよう実行してもらっています。
中規模タスクでは対話で目的と受け入れ条件を明らかにし、簡易設計兼作業計画書を作り、スキル（コンテキスト）に沿って開発をしてもらいます。これらを3並列でこなしています。
この状況の中 Claude Opus 4.7 が登場しました。使い込み、スキルの適応も行なったものの、設計と異なる実装や手抜きが散見されるようになりました。こうなるとyoloで任せることは難しく、3並列の開発に若干の支障が生じました。そこで、CC の実装が完了するたびに、Codex を別ターミナルで開き実装と設計の乖離、実装不備の検査をさせるようになりました。モデル特性もあるのかもしれませんが、 CC の不備を Codex は本当によく見つけてくれます。 Codex レビューを経て、従来の完成と同等もしくは少しいい状態にまで持っていけるようになりました。
とはいえ、完了を検知してレビューを依頼し、レビュー結果のフィードバックを伝え直してもらうという作業は避けられません。
「3 回やったらツールにする」
「同じ作業を 3 回やったら自動化を考えよう」という話は有名です。私も流石にずっと CC と Codex の間を取り持ちたくありません。そこで、これはもうツールを作るしかないと思い、開発を始めました。
ここはずっと改善してきた Workflowツールの知見が活きます。ただ実装をして、ただ評価をさせるだけではいけません。それでは結果の品質の揺れ幅が大きいです。実行者にも評価者にも、同じ基準を渡すことが重要です。また、実行者・評価者それぞれの目的に沿った作業ステップと作業品質の基準を定めることも重要です。
実行者と同じ原則と受け入れ条件を見て評価する。指摘を人間（私）に伝えるのではなく改善項目として実行者に差し戻す。このループを繰り返し、品質を収束させる。このループを経たPRであれば、人間がフィードバックする余地はあまりなくなります。
実際にやっていること
ツールの名前はGalleyにしました。ローカルで動く Go バイナリです。リポジトリと task YAML 、基準ファイル（quality.yaml）や環境定義ファイル（environment.yaml）を渡すと、こう動きます。
タスク自体はキューで状態遷移し、ステータスはタスクファイルで管理されます。スーパーバイザー（評価者）の verdict によって行き先が決まる作りです。
ローカルで動き、変更は worktree 内で行われ、attempt ごとの証拠がファイルとして残ります。
タスクファイルは「構造化されたタスク条件」です。ゴール、受け入れ条件、許可パスと禁止パス、ループ回数上限などが記載されています。実行者が途中で合格条件を書き換えることはできません。満たすか、満たせず終わるかのどちらかです。
工夫したポイント
ループ自体はよく見る手法です。みなさんもレビュー指摘が出なくなるまでエージェント同士でレビューをさせることはあると思います。
このループを意味のあるものにするために、いくつかの工夫を入れています。この工夫により、ただのレビューループではない、このツール固有の価値が生まれます。
Skill で Galley を制御する
セットアップ
Galley は Agent Skill も配布しています。Claude Code, Codex それぞれのプラグインがあります。まず Skill をインストールし、あとは自然文で「このリポジトリにGalleyをセットアップして」と頼んでみてください。
エージェントは Skill に沿って galley バイナリを入れ、リポジトリを分析し、quality.yaml と environment.yaml のドラフトを作ります。
後述しますが、品質の基準の言語化はこのツールに限らず Agentic Coding においてとても重要です。いい実装をしてもらうためにどうしても事前準備が重くなるのですが、スキルにすることでこの手間を低減できています。
タスクファイルの作成
タスクファイルも情報量が多くなっています。そこで、ユーザーと対話し必要な情報を収集し、有効なタスクファイルを書く支援をします。
事前に設計書や作業計画書を渡すこともできます。その場合はドキュメントから受け入れ条件を推測してくれます。受け入れ条件は後述するテストが書きやすいように、明示的で判断可能な記述になるようスキルに書き方の観点を設定しています。こうすることで、ある程度曖昧な要望でも、実装がブレにくいタスクファイルを作成することができます。
受け入れ条件を検証するためのテストスケルトンを実装前に配置する
これはオプションで切り替えることができます。大規模タスクでは作成を推奨します。
Workflowツールの知見がまさにここで活きるのですが、エージェントに開発させる上でテストは非常に重要です。エージェントは結合が苦手です。「結合したら動かない」問題を回避するために、受け入れ条件を検証するE2E、結合テストを実装に取り込んでもらう必要があります。
同時に、テストが意味のあるものでなくてはいけません。つまり、専用の観点が必要になります。自然言語の受け入れ条件や設計書から、テストとして何を保証するかを選別し、テストに落とし込まなくてはいけません。 Galley にはこのテスト作成を専門で行うエージェントを配置しています。エージェントはテストのスケルトンファイルを生成し、テストコメントに何を保証するテストかを記載します。
// イメージ
func TestAC1_RunAgentOverridesTimeoutPerCall(t *testing.T) {
t.Skip("AC1: run_agent callers can override execution timeout per call")
// executor がここを埋める
}
テストファイルのパスは task に記載されます。かつ t.Skip のような未実装のままでは合格判定が出ないようになっています。つまり、エージェントがコードを見て分析評価をする非決定論的な評価と、テストという決定論的な評価の両方によって、完了条件が保証される環境を実現できます。
また、実装者もテストを書かないといけないので、単純な要件の理解漏れなどを実装の中で見つけ、自己修復することができます。
品質基準を育てる
リポジトリごとに quality.yaml プロファイルを持ちます。リポジトリ内の実装として守るべき基準です。このファイルは実装時にもレビュー時にも参照されるため、「要件は満たしているが実装がリポの基準に沿ってない」という事態を防ぐことができます。
エージェントは、言われていないことは何もしないか、あるいはよしなに考えてそれっぽい生成をします。
そのため、守ってほしいことは言語化しなくてはいけません。書いてあれば守ってくれます。スキルで作成を支援しているので、例えばPRが思っていたものと違った時は、エージェントと振り返りをしてみてください。そこで「この基準が足りなかったよね？」「この基準の書き方が悪かったよね？」といった改善点を見つけ、追記してください。地味ですがこの繰り返しがエージェントの精度向上にとって重要です。
そして、基準はもちろんコンテキストなので、プロンプトの書き方と同じ工夫が必要です。
いい基準を作りたい場合は、以前私が書いた記事を参照ください。役に立つはずです。
CC の実装を別のモデルにレビューさせる
私はもうCC/Codex両方を使う生活に慣れましたが、皆さんがそうではないと考え、評価者のデフォルトは CCにしています。
ただ、冒頭でも触れたように、同一モデルでのレビューより特性の異なるモデルでレビューした方が、両者の観点が加味された固い実装になりやすいです（ここは定量的な評価はなく、私の体感値です）。これを実現するために、評価者（supervisor）は CC, Codex どちらかを選べるように設計しました。
Galley では実装者・評価者それぞれの実行ログも残しているのですが、中を覗くと CC が十分だと宣言しても Codex は差し戻しをするというケースが度々あります。内部でループをする設計なので、異なるモデルの観点が両方反映された実装に収束しやすくなります。
Opus 4.7 の振る舞いの矯正
きっかけが Opus 4.7 に対する不安だったため、 Galley では CC のシステムプロンプト自体を置き換えるという選択をしました。 Codex のプロンプトと Workflowツールの知見をベースにした実装と評価の実行プロンプトを claude -p で渡しています。
期待する挙動を願うより、プロンプトで固定する方が確実だと考えての判断です。今のところ意図通りの生成結果が出ているので、しばらくこの形で運用してみる予定です。
おまけ: Galley が Galley を作る
私は、この手の AI 系ツールは試行回数がとても重要だと考えています。色々なケースでの実行を経て、システムもコンテキストも磨かれていくものです。ポンだしでいきなりいいコンテキストが出来上がることはありません。
そういった背景もあり、 Galley リリース後は直さないと挙動しないものやプロンプトチューニング以外のタスクは極力 Galley 自身に開発をしてもらうようにしています（もし興味のある方はリポの PR 履歴をみていただくと、該当の実装を見つけられます）。
実装をさせていく中でバグも見つかりましたし、プロンプトのチューニング余地も見つかりました。また品質基準の書き方の問題や不足・過多（ worktree 環境では実行できないテストを要求していた）も見つかっています。やはり実践に勝るものなしです。
試してみませんか？
Galley は Claude Code CLI と git が入っていれば動かすことができます。PR を自動で開きたい場合は gh コマンドも必要です。レビュアーに Codex を使いたい場合は Codex CLI も必要です。
セットアップは途中でも書いた Skill に任せることを推奨します。ちょっと面倒な初期設定もエージェントがよしなにやってくれます。
Claude Code の場合
claude
/plugin marketplace add shinpr/galley
/plugin install galley@galley-tools
/reload-plugins
/galley:galley このリポジトリにGalleyをセットアップして
Codex の場合
codex plugin marketplace add shinpr/galley
codex
Codex CLI には Claude Code のような /plugin install がまだないので、対話式でインストールします。Codex を起動したら /plugins でプラグイン一覧を表示し、Galley を選んでスペース・エンターでインストールしてください。そのあと $galley でスキルを呼びます。
$galley このリポジトリにGalleyをセットアップして
CLI を手で入れたければ curl -fsSL https://raw.githubusercontent.com/shinpr/galley/main/scripts/install.sh | sh の 1 行で入ります。
実装を参照したい方はこちらをご覧ください。
Discussion