Управление ресурсами как кодом с помощью ant apply

ant apply создаёт и обновляет ресурсы Claude API на основе файлов: агентов, окружения, навыки, хранилища памяти, развёртывания и хранилища секретов (vaults). Они находятся в вашем репозитории и изменяются через тот же процесс ревью, что и ваш код. Вы описываете каждый ресурс в файле, запускаете ant apply и одобряете показанный им план. Затем вы фиксируете в репозитории записанный им файл claude-lock.json, чтобы следующий запуск обновлял те же ресурсы, а не создавал новые.

Об установке «command-line interface» (интерфейса командной строки), или CLI, и аутентификации в нем см. краткое руководство по CLI. Для ant apply требуется CLI версии 1.30.0 или новее.

Примените своего первого агента

Опишите агента в файле Markdown в каталоге agents/ и примените его:

ant apply agents/summarizer.md

---
name: Summarizer
model: claude-opus-5-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"
    }
  }
}

Зафиксируйте его вместе с вашими файлами. По нему следующий запуск находит эти ресурсы и не создает их заново — как на вашей машине, так и в «continuous integration» (непрерывной интеграции), или CI. Кроме того, в нем можно найти ID агента, чтобы начать сессию. Два хэша служат отпечатками того, что было отправлено в последний раз, и того, что вернул API. По ним последующий запуск замечает отредактированный файл или ресурс, измененный вне этих файлов.

Расширьте до полноценного проекта

Другие ресурсы также можно декларативно определить в виде файлов. Файл содержит тело запроса, которое вы отправили бы в конечную точку создания ресурса соответствующего типа:

• Окружение — это файл YAML в каталоге environments/.
• Хранилище памяти — это файл YAML в каталоге memory_stores/.
• Развёртывание — это файл Markdown в каталоге deployments/: блок метаданных является телом запроса, а текст становится сообщением, с которого начинается каждая сессия.
• Навык — это каталог с файлом SKILL.md в корне, по соглашению расположенный в skills/ и загружаемый одним пакетом.
• Хранилище секретов — это YAML-файл в vaults/, единственными полями которого являются display_name и, необязательно, metadata. Для файлов хранилищ секретов требуется CLI версии 1.34.0 или новее.

Любой ресурс, кроме навыка, можно описать в формате YAML, JSON или Markdown. В Markdown блок метаданных является телом запроса, а текст заполняет текстовое поле данного типа: system агента, description окружения или хранилища памяти, первое сообщение развёртывания. У хранилища секретов нет текстового поля, поэтому ant apply отклоняет Markdown-файл хранилища секретов, содержащий текст.

Ресурсы ссылаются друг на друга по пути. Везде, где API ожидает ID другого ресурса, вместо него укажите относительный путь к файлу этого ресурса. В этом проекте агент-рецензент указывает ../skills/pr-summary в skills, ведущий агент указывает ./reviewer.md в своём составе, а развёртывание ссылается по пути на своего агента, окружение и хранилище памяти. ant apply создаёт их в порядке зависимостей и подставляет реальные ID. Проект состоит из шести файлов:

---
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.

---
name: Engineering lead
model: claude-opus-5-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.

# 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-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.

---
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 как есть. Ссылка на навык также может быть URL-адресом GitHub вида https://github.com/<owner>/<repo>/tree/<branch>/<dir>, например каталогом из открытого репозитория навыков Anthropic: ant apply скачивает и загружает этот каталог, закрепляя его за разрешённым коммитом, пока вы не выполните запуск с --upgrade (для приватного репозитория задайте GITHUB_TOKEN).

Как ant apply определяет тип файла

При обходе каталога ant apply определяет тип каждого файла по первому подходящему признаку из списка:

1. Поле type верхнего уровня в файле.
2. Каталог, в котором непосредственно находится файл: agents/, environments/, memory_stores/, deployments/ или vaults/.
3. Имя файла, начинающееся с названия типа, например environment_staging.md.
   • Исключение составляют хранилища секретов: ant apply не определяет тип по имени вроде vault_staging.yaml, потому что другие инструменты называют свои файлы секретов vault.yml. Храните файл хранилища секретов в vaults/ или укажите в нём type: vault.

Файлы, не подходящие ни под один признак (например, README и конфигурация CI), пропускаются, если вы не укажете их в командной строке явно. Явно указанный файл Markdown без подходящего признака считается агентом, а явно указанный файл YAML или JSON без подходящего признака вызывает ошибку.

Редактирование и повторное применение

При запуске без аргументов ant apply синхронизирует все файлы, отслеживаемые файлом блокировки. В терминале команда также выводит неотслеживаемые файлы ресурсов в каталоге файла блокировки и предлагает их добавить. Если удалить поле из файла, оно очищается и в ресурсе, если API позволяет очистить это поле. Поле, которое вы никогда не задавали или которое API не позволяет очистить, сохраняет текущее значение.

Если ресурс был отредактирован, архивирован или удален вне этих файлов (например, в Claude Console), план завершается строкой This plan cannot be applied: с указанием причины. Затем команда завершается с сообщением refusing to apply. Передайте флаг --force, чтобы перезаписать внешние изменения или создать ресурс заново.

Если удалить файл, его ресурс остается на месте, а команда выводит предупреждение. Флаг --prune удаляет такой ресурс: архивирует его, а навык удаляет полностью. Поэтому переименованный файл объявляет новый ресурс, а старый остается на месте, пока вы не выполните очистку.

ant apply не может взять под управление ресурс, созданный в Console или с помощью ant beta:agents create. Команда управляет только ресурсами из файла блокировки, поэтому применение файла с описанием существующего агента создаст второго агента. Если вы скачали агента из Console с помощью Export as code, архив содержит собственный claude-lock.json. Поэтому при его применении обновятся ресурсы, созданные вами в Console.

Запуск ant apply в CI

Без терминала 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 без аргументов синхронизирует только файлы, которые уже отслеживаются файлом блокировки, и пропускает новые.
• Для «pull request» (запросов на слияние) запускайте ant apply --dry-run ., чтобы показать план рецензентам. Этот запуск носит исключительно информационный характер и завершается с кодом 0, даже если план заблокирован.
• Фиксируйте обновленный claude-lock.json в конце задания, даже если шаг применения прервался с ошибкой: частичное применение все равно записывает созданные ресурсы.
• Не запускайте несколько применений одновременно: файл блокировки не защищен от параллельного доступа.
• Для аутентификации используйте Workload Identity Federation, а не сохраненный ключ API. Идентичность должна иметь доступ к организации и рабочему пространству, записанным в claude-lock.json. ant apply отклоняет учетные данные, относящиеся к любой другой организации или рабочему пространству.

Полный пример рабочего процесса GitHub Actions см. в разделе о CI в README CLI.

Флаги

Дальнейшие шаги