ant applyでリソースをコードとして管理する

ant applyは、ファイルからClaude APIリソース（エージェント、環境、スキル、メモリストア、デプロイメント）を作成および更新します。これらのファイルはリポジトリ内に置かれ、コードと同じレビューを経て変更されます。各リソースをファイルに記述してant applyを実行し、表示されるプランを承認します。その後、書き込まれたclaude-lock.jsonをコミットします。これにより、次回の実行では新しいリソースが作成されず、同じリソースが更新されます。

CLIのインストールと認証については、CLIクイックスタートを参照してください。ant applyにはCLIバージョン1.30.0以降が必要です。

最初のエージェントを適用する

エージェントをagents/配下のMarkdownファイルとして記述し、適用します：

ant apply agents/summarizer.md

---
name: Summarizer
model: claude-opus-5
tools:
  - type: agent_toolset_20260401
---

You are a helpful assistant that writes concise summaries.

「frontmatter」（フロントマター）にはエージェントの設定（エージェントを定義するで説明しているフィールド）を記述し、本文はそのシステムプロンプトになります。ant applyは、ファイルのパス（ここではagents/ディレクトリ）から、そのファイルがエージェントであることを推論します。

インタラクティブなターミナルでは、ant applyはプランを出力し、承認を待ちます：

First apply  ./claude-lock.json does not exist yet and will be created

Resources will be created with
  credentials   API key (--api-key / ANTHROPIC_API_KEY)
  host          api.anthropic.com
  organization  1b0c2a4d-6c1f-4f0e-9a57-2e8d1c3b4a5f
  workspace     wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ

Preview  ./claude-lock.json (new)

± Name                    Plan
+ ./agents/summarizer.md  create

Resources  + 1 to create

Apply these changes? (y)es / (n)o / (d)etails y

Apply  ./claude-lock.json

± Name                    Status
+ ./agents/summarizer.md  created    agent_011CYm1BLqPXpQRk5khsSXrs

Resources  + 1 created

State written to ./claude-lock.json

先に詳細を確認するにはdと回答します。各新規リソースのフィールド、または各更新のフィールドごとの差分が表示されます。--dry-runを指定すると、その詳細なプランを出力し、何も変更せずに終了します。

エージェントを変更するには、ファイルを編集して再度ant applyを実行します。すると、プランには作成ではなく更新が表示されます。

claude-lock.jsonをコミットする

最初のant applyは、実行したディレクトリに「lockfile」（ロックファイル）であるclaude-lock.jsonを書き込みます。そのため、リポジトリのルートから実行してください。このファイルには、各ファイルから作成されたリソースのIDと、リソースが属する組織およびワークスペースが記録されます：

{
  "version": 1,
  "origin": {
    "base_url": "https://api.anthropic.com",
    "organization_id": "1b0c2a4d-6c1f-4f0e-9a57-2e8d1c3b4a5f",
    "workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"
  },
  "resources": {
    "./agents/summarizer.md": {
      "kind": "agent",
      "id": "agent_011CYm1BLqPXpQRk5khsSXrs",
      "version": "1",
      "hash": "d23251c8d99b3613a64f3f8d87f5fad4",
      "remote_hash": "1b771bee5bdbf600a5ad972fdac32d94"
    }
  }
}

このファイルは、リソースのファイルと一緒にコミットしてください。次回の実行時（自分のマシン上でもCI上でも）には、このファイルを使ってリソースを再作成せずに既存のリソースを見つけます。また、セッションを開始する際には、このファイルからエージェントのIDを読み取ります。2つのハッシュは、最後に送信した内容とAPIが返した内容のフィンガープリントです。後の実行では、これらのハッシュを使って、編集されたファイルや、これらのファイル以外の場所で変更されたリソースを検出します。

プロジェクトに拡張する

他のリソースもファイルとして宣言的に定義できます。ファイルには、その種類の作成エンドポイントに送信するリクエストボディを記述します：

• 環境は、environments/内のYAMLファイルです。
• メモリストアは、memory_stores/内のYAMLファイルです。
• デプロイメントは、deployments/内のMarkdownファイルです。フロントマターがリクエストボディとなり、本文が各セッションを開始するメッセージになります。
• スキルは、ルートにSKILL.mdを持つディレクトリです。慣例的にskills/配下に置かれ、1つのバンドルとしてアップロードされます。

スキル以外のリソースは、YAML、JSON、Markdownのいずれでも記述できます。Markdownでは、フロントマターがリクエストボディとなり、本文がその種類のテキストフィールドに入ります。具体的には、エージェントのsystem、環境またはメモリストアのdescription、デプロイメントの最初のメッセージです。

リソースはパスで互いを参照します。APIが別のリソースのIDを必要とする箇所には、IDの代わりにそのリソースのファイルへの相対パスを記述します。このプロジェクトでは、reviewerエージェントがskillsに../skills/pr-summaryを指定し、leadエージェントがロスターに./reviewer.mdを指定しています。また、デプロイメントはエージェント、環境、メモリストアをパスで指定しています。ant applyはこれらを依存関係の順序で作成し、実際のIDを埋め込みます。このプロジェクトは6つのファイルで構成されています：

---
name: Code reviewer
model: claude-opus-5
tools:
  - type: agent_toolset_20260401
skills:
  - ../skills/pr-summary
---

You review pull requests for correctness, security, and readability.

---
name: Engineering lead
model: claude-opus-5
multiagent:
  type: coordinator
  agents:
    - ./reviewer.md
---

You coordinate engineering work. Delegate code review to the reviewer.

---
name: pr-summary
description: Summarize a pull request's changes and risks in the team's review format.
---

# PR summary

List what changed, why, and anything a reviewer should look at closely, in three short sections.

name: review-env
description: Cloud container with unrestricted networking for review sessions.
config:
  type: cloud
  networking:
    type: unrestricted

name: Review notes
description: Recurring issues and house-style decisions the reviewer has recorded between runs.

---
name: Nightly review
agent: ../agents/reviewer.md # the API's agent field: sent as {type: agent, id, version}
environment_id: ../environments/cloud.yaml # sent as the environment's ID
resources:
  - path: ../memory_stores/review-notes.yaml
    access: read_write
schedule:
  type: cron
  expression: "0 3 * * *"
  timezone: America/Los_Angeles
---

Review any open pull requests. Start with the oldest.

ディレクトリ全体を適用します：

ant apply .

適用後、claude-lock.jsonにはプロジェクト内のすべてのファイルのエントリが含まれます。

これらのファイルは、相対パスを使って互いを参照します。ant applyはエージェントとスキルへの参照を直前に適用したバージョンに固定します。そのため、reviewer.mdやスキルを編集すると、それらを参照しているすべてのリソースが同じ実行内で更新されます。パスはオブジェクト内でも使用できます。たとえばデプロイメントのresourcesエントリでは、パスが解決されたうえで、accessなどの他のキーはそのまま保持されます。

これらのファイルで管理していないリソースを参照するには、パスの代わりにそのID（agent_...、skill_...）を記述します。{type: anthropic, skill_id: xlsx}のように、パスでもIDでもない値は、記述したとおりにAPIへ送信されます。スキルの参照には、https://github.com/<owner>/<repo>/tree/<branch>/<dir>形式のGitHub URLも使用できます。たとえば、Anthropicのオープンソースのスキルリポジトリ内のディレクトリを指定できます。ant applyはそのディレクトリをダウンロードしてアップロードし、--upgradeを付けて実行するまで、解決されたコミットに固定します（プライベートリポジトリの場合はGITHUB_TOKENを設定してください）。

ant applyがファイルの種類を推論する方法

ant applyはディレクトリを走査する際、次の条件を上から順に確認し、最初に一致したものに基づいて各ファイルの種類を判定します：

1. ファイル内のトップレベルのtypeフィールド。
2. ファイルを直接含むディレクトリ：agents/、environments/、memory_stores/、またはdeployments/。
3. environment_staging.mdのように、種類名で始まるファイル名。

READMEやCI設定など、いずれの条件にも一致しないファイルは、コマンドラインで明示的に指定しない限りスキップされます。いずれにも一致しないファイルを明示的に指定した場合、Markdownファイルはエージェントとして扱われ、YAMLまたはJSONファイルはエラーになります。

編集して再適用する

引数なしでant applyを実行すると、ロックファイルが追跡しているすべてのファイルについて、リソースをファイルの内容と一致させます。ターミナルで実行した場合は、ロックファイルのディレクトリ配下にある未追跡のリソースファイルも一覧表示し、追加するかどうかを確認します。ファイルからフィールドを削除すると、APIがそのフィールドのクリアを許可している場合は、リソース上のそのフィールドもクリアされます。一度も設定していないフィールドや、APIでクリアできないフィールドは、現在の値が保持されます。

これらのファイル以外の場所（たとえばClaude Console）でリソースが編集、アーカイブ、または削除された場合、プランの末尾にThis plan cannot be applied:とその理由が表示されます。その後、コマンドはrefusing to applyを出力して終了します。--forceを指定すると、その編集を上書きするか、代わりのリソースを作成します。

ファイルを削除しても、対応するリソースは警告とともにそのまま残ります。リソースを削除するには--pruneを使用します（通常はアーカイブされ、スキルの場合は削除されます）。そのため、ファイル名を変更すると新しいリソースとして宣言され、pruneするまで古いリソースはそのまま残ります。

ant applyは、Consoleやant beta:agents createで作成したリソースを管理対象に取り込むことはできません。管理されるのはロックファイルに記録されたリソースだけです。既存のエージェントと同じ内容のファイルを適用すると、2つ目のエージェントが作成されます。ConsoleのExport as codeでエージェントをダウンロードした場合は、ダウンロードに専用のclaude-lock.jsonが含まれています。そのため、それを適用すると、Consoleで構築したリソースが更新されます。

CIでant applyを実行する

ターミナルがない環境では、ant applyはプランを出力した後、cannot ask for confirmation without a terminal; re-run with --yes to apply, or --dry-run to see the plan onlyを表示して停止します。CIは次のように設定してください：

• マージ後にデフォルトブランチで、プロジェクトディレクトリを指定してant apply --yes .を実行します。ディレクトリを指定しないant apply --yesは、ロックファイルがすでに追跡しているファイルのみを対象とし、新しく追加されたファイルはスキップします。
• プルリクエストでは、ant apply --dry-run .を実行してレビュアー向けにプランを出力します。これは情報提供のみを目的としており、プランがブロックされている場合でも終了コード0で終了します。
• 適用ステップが途中で失敗した場合でも、ジョブの最後に更新されたclaude-lock.jsonをコミットしてください。適用が途中で終わっても、作成済みのリソースは記録されているためです。
• ロックファイルには排他制御の仕組みがないため、適用は一度に1つずつ実行してください。
• 保存されたAPIキーではなくWorkload Identity Federationで認証してください。その際、claude-lock.jsonに記録された組織とワークスペースにアクセスできるIDを使用します。ant applyは、それ以外の組織やワークスペースに対応する認証情報を拒否します。

GitHub Actionsワークフローの完全な例については、CLI READMEのCIの例を参照してください。

フラグ

次のステップ