Lesson 22.422.4 Resources as code

In everyday life. A restaurant chain keeps its recipes in one binder at head office, not in each cook's memory. A change to the house soup is written on a new page, tasted by the head chef, and only then sent to every kitchen. Each kitchen keeps a list of which page it is cooking from. When a soup tastes wrong in one kitchen, anyone can check which page that kitchen used. In this concept, the binder is your files, the head chef's tasting is the plan and review, and each kitchen's list is the lock file.

What you will learn. How to keep the worker's definition and its setting as reviewed files, preview every change before it is made, and record which file made which part.

Why it matters. A change made by hand in a web form skips review, and nobody can say later which version is running. Files make every change visible in a pull request.

One request, start to finish. Ana wants the worker to say an invoice's due date in plain words, "due next Tuesday", as well as the date. The builder asks a coding agent for the change:

1. A coding agent edits one file, agents/ap-worker.md, adding one line to the worker's instructions.
2. It opens a pull request. The diff shows the one line.
3. CI checks the files: the configuration check (a script that fails when a file breaks one of the worker's rules) passes, and a diff of the files alone (what changed, line by line) shows the one changed line.
4. The builder merges. The deploy workflow shows the plan, "update agent ap-worker, version 4 to 5, instructions changed", then applies it to the staging workspace (a separate space on the platform, here the one for testing), and records that agents/ap-worker.md is now version 5 of that agent.
5. Ana tries it in staging. Then a person applies it to production.

At no point did anyone edit the worker in a web form.

Why keep resources as files?

An agent definition is part of your product, so it should change the way code changes: in a file, reviewed in a pull request, tried in staging first (Chapters 15 and 17). Keeping resources as files is called resources as code. A tool reads the files and does two things:

• It shows a plan first: what it would create, change or leave alone, and why. A plan changes nothing. In Task 2, the plan runs on your computer, and nothing changes until you approve it. Later, in Task 13, CI runs it after each merge.
• It writes a lock file, which records, for each file, the id of the resource it made and a fingerprint (a hash, Chapter 18) of what it applied. The lock file is committed, so the next run, on any computer or in CI, updates the same resources instead of making new ones.

Three rules follow, and the lab checks each:

At work. In Lab 22, Task 2, Claude Code writes agents/ap-worker.md and environments/ap-sandbox.yaml, runs the plan, and shows it to the builder before applying anything. After the builder approves, it applies, and shows the lock file: two entries, each with an id and a hash. Then the builder changes the system prompt by hand in the platform's web console, and asks Claude Code to apply again. The tool refuses: the resource changed outside the files. Claude Code shows both versions, and the builder chooses the file's.

The operating rule: keep every resource as a file, show a plan before every apply, and commit the lock file. Never edit a resource in a web form.

Figure 22.8. Files, a plan, then the resources. The lock file says which resource each file made.