⭐️ant apply

https://platform.claude.com/docs/en/cli-sdks-libraries/cli/apply

一言でいうと Claude API リソースの Terraform。agent / environment / skill / memory store / deployment をリポジトリ内のファイルとして書き、ant apply で API 側の実体と同期する。Console で手でポチポチ作る代わりに、レビューと git 履歴が効く形にする道具。CLI v1.30.0 以降。

最小の例

<!-- agents/summarizer.md -->
---
name: Summarizer
model: claude-opus-5
tools:
  - type: agent_toolset_20260401
---

You are a helpful assistant that writes concise summaries.

ant apply agents/summarizer.md

frontmatter が設定、本文が system prompt。terraform の plan → apply と同じ流れで、いきなり適用せず「何を作る／変えるか」の一覧を出して y（適用）/ n（中止）/ d（フィールド単位の詳細・差分）を聞いてくる。--dry-run なら詳細を出して適用せず終了。

肝は claude-lock.json

初回 apply がカレントディレクトリに吐くのでリポジトリルートで実行する。中身は「どのファイルがどのリソース ID になったか」＋ organization / workspace。

"./agents/summarizer.md": {
  "kind": "agent",
  "id": "agent_011CYm1BLqPXpQRk5khsSXrs",
  "hash": "d232...",        // 最後に送った内容
  "remote_hash": "1b77..."  // API が返した内容
}

これを commit しないと、次の実行が同じリソースを見つけられずもう1個作る。役割は terraform.tfstate と同じ（ファイルと実体の対応表）だが、扱いは逆で、こちらは commit する。

「lock」ファイルなのにロックが無い

名前が紛らわしいが、claude-lock.json の lock は package-lock.json と同じ**「バージョンを固定する」の lock** で、排他制御の lock ではない。terraform の state lock（実行中は他を弾く仕組み）に当たるものが ant apply には無い。

無いと何が困るか。ファイル更新は read → modify → write の3ステップなので、その隙間に別プロセスが割り込める:

A: lockfile 読む（summarizer は未作成）
B: lockfile 読む（同上）        ← A がまだ書いてないので B にも見えない
A: agent 作成 → agent_AAA / lockfile 書く
B: agent 作成 → agent_BBB / lockfile 書く   ← A の記録を上書き

結果、API 側に agent が 2 つでき、agent_AAA はどのファイルからも参照されない孤児になる。lockfile を消してしまったときと同じ壊れ方。terraform ならここで 2 本目が Error acquiring the state lock で即失敗するが、ant apply は黙って通る。

つまり同時実行しない責任は運用側にある。GitHub Actions なら concurrency で直列化する:

concurrency:
  group: ant-apply
  cancel-in-progress: false   # 適用の途中で殺すと中途半端に作られる

リソース同士は相対パスで参照する

API が ID を要求する場所に、そのリソースのファイルへの相対パスを書く。ant apply が依存順に作って実 ID を埋める。

# agents/reviewer.md
skills:
  - ../skills/pr-summary

# deployments/nightly.md
agent: ../agents/reviewer.md
environment_id: ../environments/cloud.yaml
resources:
  - path: ../memory_stores/review-notes.yaml
    access: read_write

ハマりどころ

• Console や ant beta:agents create で作ったものは取り込めない。lockfile にあるものだけが管理対象で、既存 agent と同じ内容のファイルを apply すると2個目ができる。Console の Export as code は lockfile 付きで落ちてくるのでそれなら繋がる
• ファイル名の変更＝新しいリソースの宣言。旧リソースは --prune するまで残る
• ファイルを消しても消えない（警告だけ）。--prune でアーカイブ（skill は削除）

フラグ