Handoff MCP v0.31–0.32 をリリースしました。AIによるコードレビューを実用的に回すための改善がまとまっています。

前提：session-loop の仕組み

Handoff MCP には /session-loop という自動開発ワークフローがあります。タスクを渡すと、AI エージェントが実装・テスト・レビューを人の手を借りずに一通り回す仕組みです。実装を担当するエージェント、テストを走らせるエージェント、コードをレビューするエージェントがそれぞれ独立に動き、問題が見つかれば実装側に差し戻して修正→再レビュー、というサイクルを繰り返します。

人間がやっていた開発フローをそのまま AI に任せる形ですが、自動で回るぶん、制御が甘いとすぐに非効率が膨らみます。

問題：レビューが終わらない

実際に運用してみると、こんな問題が出てきました。

指摘の後出し — 1ラウンド目の修正を終えたのに、2ラウンド目でレビューエージェントが突然別の観点から指摘を追加する。実装側はいつまでも修正が終わらない
全員やり直し — テストエージェントが問題を見つけると、原因が1つのタスクにあっても実装エージェント全員が最初からやり直しになる
些細な修正でフルラウンド — インデントの修正ひとつのために、テスト→レビューのサイクル全体がもう1周回る

AI エージェントの1ラウンドにはそれなりのトークンを消費するので、こうした無駄が積み重なるとコストが一気に膨らみます。

対策1：指摘は初回で全部出す

v0.31.1 から、レビューエージェントとテストエージェントは初回ラウンドですべての指摘を出し切ることが必須になりました。2ラウンド目以降にできるのは「前回の指摘が直っているかの確認」と「修正で新たに混入した問題の検出」だけです。

後から新しい観点の指摘が飛んでくることがなくなるので、実装エージェントは修正に集中できます。

対策2：やり直しは関係者だけ

テストエージェントやレビューエージェントが問題を見つけたとき、従来は実装エージェント全員が再起動されていました。v0.31.2 の Owner-limited rework で、問題に関係する実装エージェントだけが再起動されるようになりました。他の実装エージェントの成果はそのまま残るので、無関係な再実行がなくなります。

対策3：小さい修正はレビューエージェントがその場で直す

インデントや typo の修正で差し戻すのは過剰です。Reviewer micro-fix で、レビューエージェントがテスト証拠付きで軽微な修正をその場で適用できるようになりました。

ただし安全策として Micro-safe boundary があり、変更ファイル数に上限があるほか、マイグレーション・ロックファイル・CI設定・認証関連には手を出せません。

対策4：収束しなければ打ち切る

最大ラウンド数を超えても終わらないセッションは、未解決の finding をバックログタスクとして自動起票し、セッションを閉じます。問題の記録と次のアクションが残るので、無限ループにはなりません。

コード変更に連動するドキュメント更新

コードを変えたら仕様書やガイドの更新が必要になることがあります。Doc reconciler agent がコード変更から波及するドキュメント更新を検出し、audit モード（読み取り専用で差分を報告）または apply モード（直接適用）で対応します。コードに合わせて仕様を書き換える——いわゆる仕様の後追い正当化——は安全規則で禁止しています。

段階実装を欠陥扱いしない

機能を複数タスクに分けて段階的に実装する場合、途中のタスクに「まだ繋がっていない」部分があるのは想定内です。v0.31.0 で、レビューエージェントとテストエージェントは後続のタスクと設計ドキュメントの両方を確認してから判断するようになりました。意図的な段階実装であれば指摘の深刻度を下げ、確認が取れなければ欠陥扱いを維持します。

その他の変更

Finding closure states — fixed・accepted_in_session・observed_out_of_scope・deferred_blocked の4終了状態で指摘の結末を記録
Follow-up creation gate — ブロッキング finding の先送り防止、セッション2件上限、重複チェック
Session repairer agent — affected_paths にスコープを絞った targeted verification で個別修復
Stage telemetry — ラウンド・ステージ・ロール・モデル・判定・クラッシュ有無のメタデータをワークフロー結果に付与
Enhanced finding schema — affected_paths・repair_class・verification_commands・doc_impacts を追加
include_dependents フラグ — handoff_get_task で後続タスクの依存関係をオプション取得

インストール・アップデート

npx handoff-mcp-server@latest

Claude Code のプラグインとして使っている場合:

/plugin install alphaelements/handoff-mcp

Handoff の実績ページを見る