ant apply makes agent configuration reviewable, not transactional

What Anthropic shipped on September 3

Version 1.30.0 of Anthropic's ant CLI added ant apply. The command reads resource definitions from a repository, displays a plan, creates or updates remote Claude Platform resources after approval, and writes a claude-lock.json file that binds local paths to remote IDs and versions.

The supported graph is wider than an agent prompt. It includes agents, execution environments, reusable skills, memory stores, and scheduled or one-shot deployments. Relative file paths can stand in for resource IDs. When a lead agent names a reviewer file, or a deployment names an agent, environment, and memory store, the CLI resolves the dependency order and substitutes the remote IDs during apply.

This is a meaningful operational change. Before it, teams could script create and update API calls, but the review unit was usually a mixture of request payloads, IDs copied from prior responses, console edits, and imperative shell. A repository now holds the intended graph in human-reviewable Markdown, YAML, or JSON. The same pull request can show a prompt edit, a new skill version, a tighter environment, and the deployment that consumes them.

The new workflow does not prove broad adoption. A focused last30days scan found the official CLI repository as the only strong exact-match developer artifact; it had 633 stars during the September 8 scan. Reddit and Hacker News activity was mostly about adjacent Anthropic and agent-infrastructure topics. Treat this as a fresh capability with a credible implementation surface, not a market-share event.

The unit of change is a resource graph

ant apply infers resource kind from a top-level type, a recognized directory, or a filename prefix. Agents and deployments can be Markdown: frontmatter carries API configuration while prose becomes the system prompt or first deployment message. Environments and memory stores commonly use YAML. A skill is a directory rooted at SKILL.md and is uploaded as a bundle.

agent-project/
├── agents/
│   ├── lead.md
│   └── reviewer.md
├── environments/
│   └── production.yaml
├── skills/
│   └── pr-summary/SKILL.md
├── memory_stores/
│   └── review-notes.yaml
├── deployments/
│   └── nightly-review.md
└── claude-lock.json

Path references create the edges. This is better than pasting IDs into every file because code review can follow the dependency in the same tree. Applying the directory creates dependencies first and pins agent and skill references to versions applied in that run. A GitHub-hosted skill reference is also supported and remains pinned to the resolved commit until --upgrade is used.

But path convenience creates lifecycle consequences. Renaming agents/reviewer.md is not necessarily an in-place rename of the remote object. Anthropic documents that it declares a new resource and leaves the old resource until prune. Deleting a file also leaves the remote resource in place with a warning unless --prune is supplied. Repository refactors therefore need the same impact review as schema migrations.

claude-lock.json is identity state, not a backup

The lockfile records the API base URL, organization, workspace, and a resource entry for each managed path. Each entry includes kind, remote ID, version, a hash of what was sent, and a hash of what the API returned. On the next run, this mapping tells the CLI to update the existing object instead of creating a duplicate. It also lets the CLI detect a file edit or a remote change.

Commit the lockfile, as Anthropic instructs. Without it, an apparently harmless reapply can create a second agent rather than adopt the first one. The tool cannot generally adopt a console-created resource unless the exported code includes the corresponding lockfile. A literal agent_... or skill_... ID can point to unmanaged resources, but that is a deliberate boundary: the file references the object without bringing its lifecycle under this state.

Do not treat the lockfile as a secret-free throwaway. IDs and workspace bindings are operational metadata. More importantly, it is mutable deployment state in a normal Git repository. Two apply jobs can race because Anthropic explicitly says to run one apply at a time and documents no lock around the file. A partial apply can create some resources and then fail; the CLI can still write the state it learned. Discarding that changed lockfile may make recovery harder or cause duplication.

Read the update, drift, and deletion semantics literally

Reapplying a changed agent creates a new agent version. New sessions use the updated configuration; running sessions do not become magically transactional. A model migration may be a one-field file edit, but its behavioral acceptance tests still belong outside apply. Configuration delivery and behavioral validation are different systems.

Remote edits, archives, or deletions are treated as drift. The plan refuses to apply and explains why. --force can overwrite the out-of-band edit or create a replacement, but it should be an incident-level tool: preserve the plan, name the remote editor and intent, decide which state is authoritative, and require review. “Make CI green” is not a sufficient reason to erase a console emergency change.

Field removal is nuanced. Anthropic says deleting a field clears it only if the API allows the field to be cleared. A field never set, or one the API cannot clear, can keep its current value. Absence in Git therefore does not universally mean absence remotely. Security-sensitive properties need an observed retrieve-and-compare check after apply.

--prune removes resources no longer declared: most are archived, while skills are deleted. That action deserves a separate reviewed change because references, scheduled deployments, forensic evidence, or rollback plans may still depend on the old object. Export or record what policy requires before prune, and verify all inbound references.

Build CI around the documented weak edges

In a non-interactive environment, apply prints the plan and stops unless --yes or --dry-run is supplied. Anthropic recommends ant apply --dry-run . on pull requests and ant apply --yes . after merge on the default branch. The directory argument matters: a bare apply reconciles only files already tracked in the lockfile and can skip a newly added resource.

Dry-run is review evidence, not a reliable pass/fail oracle. It exits zero even when the plan is blocked. If policy says a blocked plan, unexpected create, force, prune, workspace change, or permission expansion must fail CI, add a separate machine-readable validator or review gate. Do not scrape colored terminal prose with a fragile regular expression and call that a control.

name: Apply managed-agent resources
on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

concurrency:
  group: claude-agent-production
  cancel-in-progress: false

jobs:
  plan:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: ant apply --dry-run ./agent-project

  apply:
    if: github.event_name == 'push'
    runs-on: ubuntu-latest
    environment: claude-agent-production
    permissions:
      id-token: write
      contents: write
    steps:
      - uses: actions/checkout@v4
      - run: ant apply --yes ./agent-project
      - run: ./scripts/verify-agent-resources.sh
      - name: Preserve state update
        run: ./scripts/commit-lockfile.sh

The sketch is intentionally incomplete: pin action revisions, install a reviewed CLI version, and implement organization-specific validation. The important controls are a protected environment, short-lived identity, a single concurrency group, one default-branch writer, preservation of the lockfile even after partial failure, and an independent verification step. GitHub notes that environments and concurrency are separate; every workflow that can mutate the same workspace must use the same serialization rule.

Anthropic recommends Workload Identity Federation instead of stored API keys for CI. The identity must resolve to the organization and workspace recorded in the lockfile. This binding prevents one repository's state from being silently applied under credentials for another workspace. Restrict who can approve the environment and which branches can request its identity.

The Terraform analogy helps until it creates false guarantees

HashiCorp's documentation describes state locking and saved plans because concurrent writers and plan/apply gaps are foundational infrastructure risks. The comparison is not a criticism that ant apply should copy Terraform. Agent resources differ from networks and virtual machines. It is a boundary check: do not import guarantees from a familiar phrase unless Anthropic documents and tests them.

A reference project with explicit authority

---
name: Production reviewer
model:
  id: claude-opus-5
  inference_geo: us
tools:
  - type: agent_toolset_20260401
    default_config:
      permission_policy:
        type: always_ask
skills:
  - ../skills/pr-summary
---

Review pull requests for correctness and security.
Never merge. Report evidence and unresolved risk.

The file makes model, geography, toolset, permission default, skill dependency, and authority boundary reviewable. The permission setting is not cosmetic: Anthropic documents always_allow as the default when the toolset permission policy is omitted. A platform team that intends review-before-action should therefore make the policy explicit rather than depend on absence.

The environment file should separately define packages and network policy. The deployment should reference the agent and environment by path, mount only the required memory store with explicit access, and name the first task. Repository permissions, branch protection, deployment identity, and external-system authorization remain outside the prompt. A sentence saying “never merge” is useful behavioral guidance, not a security boundary.

After apply, retrieve each remote resource and compare its effective version and material fields with the approved manifest. Start a low-risk test session. Verify that the agent loads the intended skill, runs in the intended environment, respects the expected network and tool policies, writes only to permitted memory, and produces a trace tied to the deployed versions. Apply success is configuration evidence; the test session is behavior evidence.

Failure modes to rehearse

A safe adoption checklist

1. Inventory agents, environments, skills, memory stores, deployments, owners, schedules, IDs, versions, and external permissions.
2. Export existing console-built resources with their lockfile when supported; never assume apply will adopt them.
3. Separate desired files, identity state, credentials, plan evidence, apply logs, runtime tests, and recovery records.
4. Make models, inference geography, tools, permissions, network access, skill versions, memory access, and schedules explicit.
5. Review path moves as create-plus-orphan operations until the plan proves otherwise.
6. Run ant apply --dry-run . on pull requests, but add a real policy gate for forbidden changes.
7. Apply only after merge from a protected default branch and named production environment.
8. Use short-lived workload identity bound to the lockfile's organization and workspace.
9. Serialize every writer to that workspace and lockfile; do not rely on repository-local concurrency alone when several repositories apply the same graph.
10. Preserve and review lockfile changes after every attempt, including a partial failure.
11. Retrieve effective remote state and run version-bound acceptance sessions before promotion.
12. Document force, prune, partial-apply, duplicate, rollback, and incident procedures before the first production mutation.

Start with one non-critical agent and one environment. Add a skill only after the state, review, and verification loop is stable. Add memory and scheduled deployments last because they extend persistence and unattended execution. The goal is not the shortest apply command. It is a change record that another engineer can explain and recover six months later.

Frequently asked questions

Is ant apply Terraform for AI agents?

It is Terraform-like in its declarative files, visible plan, apply step, and local identity mapping. Do not infer remote locking, saved plans, atomicity, rollback, import, or mature provider semantics that Anthropic does not document.

Should claude-lock.json be committed?

Yes. It prevents accidental duplication by mapping files to resource IDs and versions. Treat it as deployment state: protect it, serialize writers, preserve partial updates, and review unexpected diffs.

Can dry-run block a pull request?

Not by its documented exit code alone. It is informational and exits zero even when the plan is blocked. Use it for reviewers, then add a separate policy validator or protected approval for machine enforcement.

When should a team use --force?

Only after establishing why remote drift exists, who owns it, which state should win, and what evidence must be preserved. Force is conflict resolution with consequences, not a routine CI repair.

What is the safest first production workflow?

Dry-run in the pull request, one protected apply after merge, short-lived identity, global serialization, committed lockfile, remote-state verification, a low-risk test session, and a named partial-apply recovery owner.