使用 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」（前置資料）包含代理的設定（即定義您的代理中的欄位），主體則是代理的「system prompt」（系統提示）。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 時，會在您執行命令的目錄中寫入 claude-lock.json，也就是「lockfile」（鎖定檔），因此請從儲存庫根目錄執行。它會記錄每個檔案所建立資源的 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 來啟動工作階段。其中的兩個雜湊值分別是上次傳送內容與 API 回傳內容的指紋。後續執行就是藉此察覺檔案已被編輯，或資源已在這些檔案之外遭到變更。

擴展為專案

您也可以用宣告方式將其他資源定義為檔案。檔案的內容就是您會傳送到該類型建立端點的請求主體：

• 環境是 environments/ 中的 YAML 檔案。
• 記憶儲存區是 memory_stores/ 中的 YAML 檔案。
• 部署是 deployments/ 中的 Markdown 檔案：frontmatter 是請求主體，內文則成為啟動每個工作階段的訊息。
• 技能是根目錄含有 SKILL.md 的目錄，慣例上放在 skills/ 下，並以單一套件上傳。

除了技能之外，任何資源都可以用 YAML、JSON 或 Markdown 撰寫。在 Markdown 中，frontmatter 是請求主體，內文則填入該類型的文字欄位，例如代理的 system、環境或記憶儲存區的 description，或部署的第一則訊息。

資源之間透過路徑互相參照。凡是 API 需要另一個資源 ID 的地方，請改為填寫該資源檔案的相對路徑。在此專案中，reviewer 代理在 skills 下列出 ../skills/pr-summary，lead 代理在其成員名單中列出 ./reviewer.md，部署則透過路徑指定其代理、環境和記憶儲存區。ant apply 會依相依順序建立這些資源，並填入實際的 ID。此專案共有六個檔案：

---
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}，都會原樣傳送到 API。技能參照也可以是 https://github.com/<owner>/<repo>/tree/<branch>/<dir> 形式的 GitHub URL，例如 Anthropic 開源技能儲存庫中的某個目錄。ant apply 會下載並上傳該目錄，並將其固定在解析出的 commit，直到您使用 --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 時，會同步 lockfile 所追蹤的每個檔案。在終端機中，它也會列出 lockfile 所在目錄下尚未追蹤的資源檔案，並詢問是否要加入。若您從檔案中刪除某個欄位，且 API 允許清除該欄位，資源上的該欄位就會被清除。您從未設定過的欄位，或 API 無法清除的欄位，則會保留目前的值。

如果資源在這些檔案之外（例如在 Claude Console 中）遭到編輯、封存或刪除，計畫的結尾會顯示 This plan cannot be applied: 及原因，接著命令會以 refusing to apply 結束。傳入 --force 可覆寫該編輯，或建立替代資源。

刪除檔案時，其資源會保留下來並顯示警告，使用 --prune 則會移除該資源（一般資源會被封存，技能則會被刪除）。因此，重新命名檔案等同於宣告一個新資源，舊資源會一直保留，直到您執行 prune 為止。

ant apply 無法接管您在 Console 中或使用 ant beta:agents create 建立的資源。只有 lockfile 中記錄的資源才會受到管理，因此套用一個描述現有代理的檔案，會建立出第二個代理。如果您是透過 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，則只會同步 lockfile 已追蹤的檔案，新加入的檔案會被略過。
• 在 pull request 上執行 ant apply --dry-run .，為審查者印出計畫。此步驟僅供參考，即使計畫遭到阻擋，也會以 0 結束。
• 在工作結束時提交更新後的 claude-lock.json，即使套用步驟中途失敗也要提交，因為部分完成的套用仍會記錄已建立的資源。
• 一次只執行一個套用作業，因為沒有任何機制會鎖定 lockfile。
• 使用「Workload Identity Federation」（工作負載身分聯合）進行驗證，而非使用儲存的 API 金鑰，且所用身分必須能存取 claude-lock.json 中記錄的組織和工作區。詳情請參閱 Workload Identity Federation。ant apply 會拒絕解析到其他組織或工作區的憑證。

如需完整的 GitHub Actions 工作流程，請參閱 CLI README 中的 CI 範例。

旗標

後續步驟