--- title: ant applyでリソースをコードとして管理する url: https://platform.claude.com/docs/ja/cli-sdks-libraries/cli/apply description: エージェント、環境、スキル、メモリストア、デプロイメント、ボールトをリポジトリ内のファイルとして宣言し、ant applyを使用してAPIのリソースをそれらと同期させます。 --- `ant apply`は、ファイルからClaude APIリソース（エージェント、環境、スキル、メモリストア、デプロイメント、ボールト）を作成および更新します。これらはリポジトリ内に置かれ、コードと同じレビューを経て変更されます。各リソースをファイルに記述し、`ant apply`を実行して、表示されるプランを承認します。その後、書き出された`claude-lock.json`をコミットすることで、次回の実行では新しいリソースを作成するのではなく、同じリソースが更新されます。 CLIのインストールと認証については、[CLIクイックスタート](https://platform.claude.com/docs/ja/cli-sdks-libraries/cli/quickstart)を参照してください。`ant apply`にはCLIバージョン1.30.0以降が必要です。 ## 最初のエージェントを適用する エージェントを`agents/`配下のMarkdownファイルとして記述し、適用します： ```bash CLI ant apply agents/summarizer.md ``` ```markdown --- name: Summarizer model: claude-opus-5-5 tools: - type: agent_toolset_20260401 --- You are a helpful assistant that writes concise summaries. ``` 「frontmatter」（フロントマター）にはエージェントの設定（[エージェントを定義する](https://platform.claude.com/docs/ja/managed-agents/agent-setup)で説明しているフィールド）を記述し、本文はそのシステムプロンプトになります。`ant apply`は、ファイルのパス（ここでは`agents/`ディレクトリ）から、そのファイルがエージェントであることを[推論](https://platform.claude.com/docs/ja/cli-sdks-libraries/cli/apply#kind-inference)します。 インタラクティブなターミナルでは、`ant apply`はプランを出力し、承認を待ちます： ```text Output wrap 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と、リソースが属する組織およびワークスペースが記録されます： ```json claude-lock.json { "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上でも）には、このファイルを使ってリソースを再作成せずに既存のリソースを見つけます。また、[セッションを開始する](https://platform.claude.com/docs/ja/managed-agents/sessions)際には、このファイルからエージェントのIDを読み取ります。2つのハッシュは、最後に送信した内容とAPIが返した内容のフィンガープリントです。後の実行では、これらのハッシュを使って、編集されたファイルや、これらのファイル以外の場所で変更されたリソースを検出します。 ## プロジェクトに拡張する 他のリソースもファイルとして宣言的に定義できます。ファイルには、その種類の作成エンドポイントに送信するリクエストボディを記述します： * [環境](https://platform.claude.com/docs/ja/managed-agents/environments)は、`environments/`内のYAMLファイルです。 * [メモリストア](https://platform.claude.com/docs/ja/managed-agents/memory)は、`memory_stores/`内のYAMLファイルです。 * [デプロイメント](https://platform.claude.com/docs/ja/managed-agents/scheduled-deployments)は、`deployments/`内のMarkdownファイルです。フロントマターがリクエストボディとなり、本文が各セッションを開始するメッセージになります。 * [スキル](https://platform.claude.com/docs/ja/managed-agents/skills)は、ルートに`SKILL.md`を持つディレクトリです。慣例的に`skills/`配下に置かれ、1つのバンドルとしてアップロードされます。 * [ボールト](https://platform.claude.com/docs/ja/managed-agents/vaults)は`vaults/`内のYAMLファイルで、フィールドは`display_name`と、オプションの`metadata`のみです。ボールトファイルにはCLIバージョン1.34.0以降が必要です。 スキル以外のリソースは、YAML、JSON、またはMarkdownで記述できます。Markdownでは、フロントマターがボディとなり、本文がその種類のテキストフィールドを埋めます。エージェントの場合は`system`、環境やメモリストアの場合は`description`、デプロイメントの場合は最初のメッセージです。ボールトにはテキストフィールドがないため、`ant apply`は本文を含むボールトのMarkdownファイルを拒否します。 リソースはパスで互いを参照します。APIが別のリソースのIDを必要とする箇所には、IDの代わりにそのリソースのファイルへの相対パスを記述します。このプロジェクトでは、reviewerエージェントが`skills`に`../skills/pr-summary`を指定し、leadエージェントがロスターに`./reviewer.md`を指定しています。また、デプロイメントはエージェント、環境、メモリストアをパスで指定しています。`ant apply`はこれらを依存関係の順序で作成し、実際のIDを埋め込みます。このプロジェクトは6つのファイルで構成されています： ```markdown --- name: Code reviewer model: claude-opus-5-5 tools: - type: agent_toolset_20260401 skills: - ../skills/pr-summary --- You review pull requests for correctness, security, and readability. ``` ```markdown --- name: Engineering lead model: claude-opus-5-5 multiagent: type: coordinator agents: - ./reviewer.md --- You coordinate engineering work. Delegate code review to the reviewer. ``` ```markdown --- 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. ``` ```yaml # yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/environment.json name: review-env description: Cloud container with limited networking for review sessions. config: type: cloud networking: type: limited allow_package_managers: true ``` ```yaml # yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/memory_store.json name: Review notes description: Recurring issues and house-style decisions the reviewer has recorded between runs. ``` ```markdown --- 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. ``` ディレクトリ全体を適用します： ```bash CLI ant apply . ``` 適用後、`claude-lock.json`にはプロジェクト内のすべてのファイルのエントリが含まれます。 これらのファイルは、相対パスを使って互いを参照します。`ant apply`はエージェントとスキルへの参照を直前に適用したバージョンに固定します。そのため、`reviewer.md`やスキルを編集すると、それらを参照しているすべてのリソースが同じ実行内で更新されます。パスはオブジェクト内でも使用できます。たとえばデプロイメントの`resources`エントリでは、パスが解決されたうえで、`access`などの他のキーはそのまま保持されます。 これらのファイルで管理していないリソースを参照するには、パスの代わりにそのID（`agent_...`、`skill_...`）を記述します。`{type: anthropic, skill_id: xlsx}`のように、パスでもIDでもない値は、記述したとおりにAPIへ送信されます。スキルの参照には、`https://github.com///tree//`形式のGitHub URLも使用できます。たとえば、Anthropicのオープンソースの[スキルリポジトリ](https://github.com/anthropics/skills)内のディレクトリを指定できます。`ant apply`はそのディレクトリをダウンロードしてアップロードし、`--upgrade`を付けて実行するまで、解決されたコミットに固定します（プライベートリポジトリの場合は`GITHUB_TOKEN`を設定してください）。 ### ant applyがファイルの種類を推論する方法 `ant apply`はディレクトリを走査する際、次の条件を上から順に確認し、最初に一致したものに基づいて各ファイルの種類を判定します： 1. ファイル内のトップレベルの`type`フィールド。 2. ファイルが直接置かれているディレクトリ：`agents/`、`environments/`、`memory_stores/`、`deployments/`、または`vaults/`。 3. `environment_staging.md`のように、種類名で始まるファイル名。 * ボールトは例外です。他のツールがシークレットファイルを`vault.yml`と命名するため、`ant apply`は`vault_staging.yaml`のような名前から種類を判断しません。ボールトファイルは`vaults/`に置くか、`type: vault`を指定してください。 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](https://platform.claude.com/docs/ja/manage-claude/workload-identity-federation)で認証してください。その際、`claude-lock.json`に記録された組織とワークスペースにアクセスできるIDを使用します。`ant apply`は、それ以外の組織やワークスペースに対応する認証情報を拒否します。 GitHub Actionsワークフローの完全な例については、[CLI READMEのCIの例](https://github.com/anthropics/anthropic-cli#in-ci)を参照してください。 ## フラグ | フラグ | 効果 | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `--dry-run` | プランを出力し、適用やロックファイルの書き込みを行わずに終了します。プランがブロックされている場合でも終了コード0で終了します。 | | `--yes` | 確認を求めずに適用します。ターミナルがない場合は必須です。 | | `--force` | これらのファイル以外の場所でリソースが変更、アーカイブ、または削除されている場合でも適用します。 | | `--prune` | ロックファイルには記録されているものの、どのファイルでも宣言されなくなったリソースを削除します。 | | `--upgrade` | GitHub URLで参照しているスキルを再解決します。このフラグを指定しない場合、スキルはロックファイルに記録されたコミットに固定されたままです。 | | `--lock-file ` | 現在のディレクトリから上位に向かって検索する代わりに、指定したロックファイルを使用します。ロックファイルは組織またはワークスペースごとに1つずつ用意してください。`ant apply`は、組織またはワークスペースが認証情報と一致しないロックファイルを拒否します。 | | `--verbose`, `-v` | 変更のないリソースと、フィールドの値全体をプランに表示します。 | ## 次のステップ 適用したエージェントをCLIまたはSDKから実行します デプロイメントのフィールド、実行履歴、一時停止 スクリプトのパターンとClaude Codeからの使用