AIエージェント設定をコードレビューへ：Claude Managed Agentsで始めるant apply

Claude Managed Agentsには、2026年9月3日に実運用を大きく変えるアップデートが加わりました。ant applyを使うと、リポジトリ内のファイルからエージェント、環境、スキル、メモリストア、デプロイメントを実環境へ反映できます。重要なのはコマンドが増えたことではありません。AIエージェントの設定を本番へ届ける前に、コードと同じ手順でレビューできるようになったことです。

CLIの小技ではなく、設定そのものをレビューできる

Claude Managed Agentsは、長時間または非同期の処理を担うAnthropicのホステッド型エージェント基盤です。エージェントではモデル、プロンプト、ツール、スキルを定義し、環境では実行場所を定めます。デプロイメントを使えば、そのエージェントをスケジュール実行できます。

これは、.claude/agents/に置くClaude Codeのサブエージェントとは別の仕組みです。今回の変更が対象とするのは、Claude APIのマネージドエージェントサービスを構成するリソースです。

Consoleや単発のAPI呼び出しでリソースを作成すると、運用に必要な状態は2か所に分かれます。実体はリモートサービスにあり、作成の経緯はスクリプトや文書、あるいは担当者の記憶に残ります。引き継ぐ際には、この2つをもう一度ひも付けなければなりません。

ant applyは、その役割をリポジトリに持たせます。リソースをMarkdown、YAML、JSONのいずれかで記述すると、CLIがファイルとリモートリソースを比較してプランを表示し、承認を求めたうえで変更を適用します。

システムプロンプト、ツールへのアクセス、環境、スキル一式、メモリストア、スケジュールを、1つのプルリクエストにまとめられるわけです。デプロイ権限を持つ担当者やCIジョブが変更を反映する前に、レビュアーが差分を確認できます。

この記事は、すでにManaged Agentsの導入を検討しているチーム向けの実践ガイドです。Claudeアプリ、Claude Code、またはMessages API上に構築した独自ループだけを使っている場合、ant applyを導入しても現在の構成は変わりません。

引き継ぎの要はロックファイル

重要なのはエージェントの定義ファイルだけではありません。鍵を握るのはclaude-lock.jsonです。

最初のapplyが成功すると、コマンドを実行したディレクトリにこのロックファイルが作られます。リポジトリのルートから実行し、リソースファイルと一緒にロックファイルもコミットします。

ロックファイルには、APIのオリジン、組織、ワークスペースに加え、各ローカルファイルから作成されたリモートIDが記録されます。さらに、ローカルハッシュとリモートハッシュも保存されます。ローカルハッシュが検知するのはファイルの変更、リモートハッシュが検知するのはConsoleや別のAPI経由で加えられたリソースの変更です。

住所録と受領書を組み合わせたもの、と考えると分かりやすいでしょう。リソースファイルは実現したい状態を示し、ロックファイルはそのファイルが管理する実オブジェクトと、直前のapply後に双方がどの状態だったかを記録します。

これにより、引き継ぎは明快になります。次の担当者やCIランナーは、agents/reviewer.mdに対応するエージェントIDを推測する必要がありません。マッピングを読み、別のコピーを作らずに同じリソースを更新できます。

通常ならAPIでIDを指定する箇所でも、リソース同士は相対パスで参照できます。applyが依存関係の順序を解決し、各リソースを作成または更新して、実際のIDを補完します。エージェントからスキルのディレクトリを参照し、デプロイメントからエージェント、環境、メモリストアを参照することも可能です。

エージェントとスキルへの参照は、その実行で適用されたバージョンに固定されます。GitHub URLから取得したスキルも、--upgradeを使うまでは解決済みのコミットに固定されます。そのため、動き続けるブランチの先端ではなく、具体的な対象をレビューできます。

AIエージェント管理の採算は、引き継ぎ工数で決まる

ant applyを導入しても、エージェント運用のコストがなくなるわけではありません。予算の置き場所が変わります。

従来のコストは、設定、検証、引き継ぎを繰り返す作業でした。新たに必要になるのは、リポジトリの準備、プルリクエストのレビュー、CIの管理、ロックファイルの保守です。どちらが安いかは、設定を変更する頻度と、同じ変更を反映する環境の数で決まります。

以下は条件を明示した試算例であり、ベンチマークでもAnthropicによる削減効果の主張でもありません。

あるチームが、月4回の設定変更を3つの対象環境へ反映するとします。手作業による引き継ぎには、変更ごと、環境ごとに15分かかるものとします。

手作業にかかる月間工数は次のとおりです。

4 changes × 3 environments × 15 minutes = 180 minutes

一方、リポジトリを使う方法では、変更ごとのレビューに30分、各環境への適用と確認に10分かかるとします。

リポジトリ方式の月間工数は次のとおりです。

4 changes × (30 review minutes + 3 × 10 apply minutes) = 240 minutes

この条件では、リポジトリ方式のほうが毎月60分遅くなります。手作業の引き継ぎがすでに効率的なら、これが受け入れるべき結論です。

導入・保守の工数を除くと、損益分岐点は手作業1回あたり20分です。実測した引き継ぎ時間が30分なら、同じ手作業は360分になり、リポジトリ方式は240分のままです。差は120分ですが、チームが実際の作業を計測するまでは、あくまで表計算上の結果にすぎません。

その時間に、人件費を含めた労務単価を掛けてください。さらに、初期設定の工数と、失敗したプランのレビュー、ドリフトの解消、CIの保守に繰り返しかかるコストも加えます。デモが整って見えるかではなく、その総額が既存プロセスのコストを下回るときに、初めて導入価値が生まれます。

このワークフローで価値を得られるチーム

プラットフォームチーム：レビュー窓口を1つに集約

ソフトウェア企業のプラットフォーム責任者なら、エージェント、そのスキル、環境、メモリストア、スケジュール済みデプロイメントを1つのプルリクエストにまとめられます。レビュアーは、プロンプトファイルとリモートConsoleのスクリーンショットを見比べる代わりに、運用上の変更全体を一度に確認できます。

得られる価値はトレーサビリティです。マージ済みの変更からリソースプランへ、さらにその後のロックファイルの状態までを追跡できます。

受託開発会社：顧客への引き継ぎを明快に

受託開発会社の技術責任者は、顧客ごとのファイルを、その顧客の組織とワークスペースに対応するロックファイルと一緒に管理できます。別の担当者が作業を引き継ぐ際も、マッピングはリポジトリとともに移ります。

引き継ぎ時に、どのリソースかを推測する場面が減るのが利点です。ただし、1つのロックファイルを複数の顧客で使い回せるわけではありません。認証情報が別の組織またはワークスペースを指している場合、applyは処理を拒否します。これは、受託側が守るべき境界そのものです。

運用チーム：明示的なデプロイ手順を確立

運用責任者は、プルリクエスト上で変更をプレビューし、マージ後はデフォルトブランチ上のディレクトリをant apply --yes .で適用できます。最後のドットは省略できません。引数なしのapplyでは、ロックファイルですでに追跡しているリソースだけが同期対象になり、新しく追加したファイルを見落とす可能性があるためです。

得られるのは、再現可能なデプロイ手順です。ただし、applyはロックファイルをロックしないため、実行時の担当は1つに絞る必要があります。2つのジョブを同時に走らせると、同じ状態を巡って競合する可能性があります。

セキュリティ責任者：ドリフトを検知して停止

セキュリティ責任者はリモートハッシュを使い、リポジトリの状態で上書きする前に、Console上の編集を表面化できます。管理対象のリソースがファイル外で編集、アーカイブ、削除されていると、applyは処理を停止します。

その結果、判断が明示的になります。リモートの変更を調査して整合させるか、--forceを使って意図的に上書きするかを選べます。Zero Data RetentionまたはHIPAA Business Associate Agreementの対象であることが必須のチームは、Managed Agents自体の対応を待つ必要があります。現時点では、このサービスはどちらにも対応していません。

適用できる最小構成のリポジトリ

ant applyにはCLI 1.30.0以降が必要です。公式クイックスタートには、Homebrewでのインストール方法とブラウザを使ったログイン手順が記載されています。

1. 1

   インストールして認証する

   CLIをインストールし、バージョンを確認してからサインインします。

   brew install anthropics/tap/ant
   ant --version
   ant auth login

2. 2

   エージェントファイルを1つ作る

   公式ドキュメントの最小定義を使い、agents/summarizer.mdを作成します。

   ---
   name: Summarizer
   model: claude-opus-5
   tools:
     - type: agent_toolset_20260401
   ---
   
   You are a helpful assistant that writes concise summaries.

3. 3

   リポジトリのルートから一度applyする

   ドキュメントに記載された単一ファイル用のコマンドを実行します。

   ant apply agents/summarizer.md

   プランを確認し、フィールド単位の差分が必要なら詳細を表示してから承認します。実行に成功するとリモートにエージェントが作成され、プロジェクト内にclaude-lock.jsonが書き込まれます。

4. 4

   プレビューと適用を別々のジョブに分ける

   プルリクエストでは、ドキュメントに記載されたプレビューコマンドを使います。

   ant apply --dry-run .

   マージ後はデプロイジョブを直列化し、対象ディレクトリを指定して適用します。

   ant apply --yes .

   最後に、更新されたロックファイルをコミットします。applyが途中で失敗した場合も同様です。処理の一部が完了した時点で、すでにリソースが作成され、その情報が記録されている可能性があります。

CIで見落としやすい終了コード

この点が重要なのは、リモートのドリフトが通常運用でも起こるためです。レビューからマージまでの間に、誰かがConsoleでエージェントを編集することもあります。プレビューの役割は、その変更を明示的な判断事項として示すことです。緑のチェックを付けたまま、後続のデプロイジョブで初めて発覚させることではありません。

applyジョブでは、保存したAPIキーではなくWorkload Identity Federationを使います。ジョブの接続先はロックファイルに記録された組織とワークスペースに固定し、同時に実行するapplyは1つだけにします。

導入前に把握すべき制約

設定をファイルで管理しても、すべてのリモートリソースを扱えるようになるわけではありません。

ant applyでは、Consoleまたはant beta:agents createで個別に作成したエージェントを後から管理対象に取り込めません。ConsoleのExport as codeでファイルとロックファイルを書き出した場合は、そのリソースをapplyで更新できます。それ以外の場合、同じ内容のファイルを適用すると別のリソースが作られます。

削除も慎重に扱われます。ファイルを削除してもリモートリソースは残り、警告が表示されます。--pruneを指定するとリモートリソースも削除されます。一方、ファイル名を変更すると新しいリソースとして扱われ、pruneするまで古いリソースが残ります。

つまり、--forceと--pruneは掃除のための便利なオプションではなく、本番環境を制御する機能です。どちらもレビュー対象にしてください。不適切なファイル名変更の直後に自動でpruneすると、デプロイメントがまだ参照しているリソースを削除しかねません。

ロックファイルも、チームで共有する運用状態になります。applyのたびにコミットし、対象ブランチを保護して、書き込み処理を直列化します。処理が途中で失敗した場合、ジョブが赤いという理由だけでロックファイルの変更を破棄してはいけません。

そして、これは今もベータ版のサービスです。Claude Managed AgentsはClaude APIアカウントでデフォルト有効になっています。ただし、Zero Data RetentionまたはHIPAA BAAが必須のチームにとっては、リポジトリでレビューできるようになっても解決しない、製品レベルの制約が残ります。

次の月曜日に始めること

同じManaged Agentsリソースを複数人で変更する、同じ設定を複数の環境へ展開する、またはスケジュール済みデプロイメントに担当者とレビュー履歴が必要なら、今週中に動き始める価値があります。

担当者が1人だけの安定した実験である、実測した引き継ぎコストが新しいレビューコストより低い、またはデータポリシーでZero Data RetentionかHIPAA BAAへの対応が必須なら、導入は待つべきです。

エージェントをClaude Code、Claudeアプリ、またはClaude Managed Agentsのリソースを使わない独自のMessages APIループだけで動かしている場合、今回の変更による影響はありません。

月曜日になったら、非本番環境のエージェントを1つ選びます。その定義とロックファイルを、実際のプルリクエストに通してください。現在の引き継ぎとレビュー方式の双方にかかった時間を記録します。次に、安全な環境でリモート側に編集を加え、ブロックされたプランをプルリクエストのチェックが正しくブロック扱いすることを確かめます。ant apply --yes .をマージ後の工程に組み込むのは、その確認が終わってからです。

実践的なAIワークフローの最新解説をニュースレターで受け取る。