A new job

Unit 4 is where the platform grows quickly. An agent can write in an hour what took a week, and it will happily write the wrong thing in an hour too. It does not know your plant, it does not remember last week's decisions unless they are written down, and it will say it is done when it thinks it is done. None of that is a reason not to use it. It is a reason to direct it well.

Directing well takes three skills, one per chapter: writing a brief the agent can act on, writing the acceptance checks before the work starts, and reading the change it hands back before it ships. The ten quality clamps from Session 9 catch the mistakes a machine can catch. These three skills cover the rest.

The change you will direct

Acme's quality engineer wants burr height measured on the first-off check on Line 3, not just a yes or no: a number in millimetres, limit 0 to 0.10. It touches every layer of the platform: a migration, an access rule, the operator screen, the review card and the board. That makes it a good first brief: small enough for one pull request, big enough to go wrong in interesting ways.

How it is scored

The element is complete when you have opened every chapter and taken the assessment, and passed at 80% or more. Homework 4 (a workflow built by agents, due at the end of week 6) asks for your briefs, the changes and your checks; start keeping them now.

What an agent needs

Anthropic's guidance for its own coding agent puts it plainly: the more specific the instructions, the better the first attempt, and the fewer corrections later ^[1]. Specific does not mean long. It means the agent can answer, from the brief alone, four questions: what outcome do you want, where are the edges, how will we both know it is done, and what should I tell you when I stop.

Standing rules go in one file

Some rules apply to every change: money in whole cents, row-level security on every table, phone first, secrets never in code, the clamps. Do not repeat them in every brief. Coding agents read a standing-instructions file at the start of every session: Claude Code reads CLAUDE.md ^[2], and many other agents read AGENTS.md, an open format for the same purpose ^[3]. Keep it in the repository, short, and written as rules. When an agent makes the same mistake twice, add a rule.

# Rules for agents working in this repository
1. Every table has row-level security, generated from docs/matrix.md. Never add a table without it.
2. A route is closed until docs/matrix.md opens it.
3. Money is integer cents. Measurements are stored in the unit named in the column (for example burr_mm).
4. Never edit a test to make it pass, never edit an applied migration, never add || true to a script.
5. Every page passes the phone check at 360 and 390 px.
6. No keys, passwords or tokens in code, chats or commits. Ask a person to set them in Vercel or GitHub.
7. Stop and report when a limit in the brief would have to be broken to finish.

Size: one pull request

A brief should produce one change a person can read in about fifteen minutes. If you cannot list its acceptance checks on one screen, split it. Agents do better on small, well-defined tasks with a clear check than on large open ones, and so do reviewers. Anthropic's own advice on building with agents is to start with the simplest approach that works and add complexity only when it is needed ^[4].

Let it plan before it builds

For anything bigger than a few lines, ask the agent to read the relevant files and write a short plan first, then stop. Read the plan; it takes two minutes and catches the misunderstanding before it becomes two hundred lines of code. Anthropic recommends this explore-plan-code pattern for its agent ^[1]. Approve the plan or correct it, then let the agent build.

Why first

If the checks are written after the code, they tend to describe what the code does rather than what you needed. Written first, they are your definition of done, fixed before anyone is tempted to bend it. This is test-driven development: write a failing test, make it pass, then tidy up ^[1]. With an agent it matters even more, because the agent can iterate against a test on its own, many times, without you ^[2].

Write them in plant words

Start in plain language, in the shape given, when, then, which the Gherkin format popularised for exactly this purpose ^[3]. Each line names a person, an action and an observable result. Then turn each one into an automated test.

test("burr height above its limit fails on the server and shows the difference", async ({ page }) => {
  await signInAs(page, "operator-line3");
  await page.setViewportSize({ width: 360, height: 800 });
  await page.goto("/operator/first-off?press=L3-P02");
  await page.getByLabel("Burr height (mm)").fill("0.14");
  // ... fill the other fields within limits ...
  await page.getByRole("button", { name: "Submit check" }).click();
  await expect(page.getByText("Fail: burr above 0.10")).toBeVisible();
  const [row] = await sql`select burr_mm, result from first_off_checks order by entered_at desc limit 1`;
  expect(row).toEqual({ burr_mm: "0.14", result: "fail" });     // decided by the server, not the browser
});

Playwright drives a real browser at phone width, so the same check proves the screen, the server and the record ^[4]. A second, short SQL test signs in as a role from another plant and expects zero rows, proving the new column did not open a gap in the access rules.

Checks the agent cannot bend

An agent told to make a test pass may make it pass by changing the test. It is not malice; it is the shortest path to what it was asked. Close that path three ways:

• Say it in the limits: the brief and the standing rules both say tests may not be edited.
• Commit the checks first, on main or on the branch before the agent starts, so any change to them shows up as a separate, obvious diff.
• Make test files need your review: a CODEOWNERS file can name you as the required reviewer for the test/ folder, so GitHub asks for your approval whenever it changes ^[5].

Green is necessary, not sufficient

The clamps prove the change compiles, follows the rules a machine can check, and passes the tests. They cannot tell you whether it solves the right problem, whether it added something nobody asked for, or whether the agent quietly worked around a limit. That is the reviewer's job. Google's published guidance for its own reviewers says the same: look first at whether the change is designed well and does what was needed, then at the details ^[1].

Read in this order

1. The summary against the brief. Did it do what you asked, all of it, and nothing else? Anything it says it could not do is the most important line in the report.
2. Tests. In the pull request's Files changed tab, look for any change to test files ^[2]. A weakened assertion or a deleted test is the first thing to stop on.
3. Migrations. Every new table has row-level security switched on and a policy from the matrix. No applied migration was edited.
4. Access rules and routes. Nothing that was closed is now open. Middleware, policies and the matrix changed only as the brief allowed.
5. Packages and configuration. Any new dependency is known, maintained and needed. The workflow files and environment settings are unchanged unless the brief said so.
6. The code. Now read it, knowing what it should do. Errors handled, not swallowed; names that match the naming standard; no copy-pasted blocks.

Try it yourself

Open the pull request's preview address on your phone ^[3] and do the task as an operator would: with gloves, at 360 px, with a value outside the limits. Then sign in as the supervisor and as another plant's user. Five minutes on a phone finds what fifteen minutes of reading misses.

Merge, fix, or rewrite the brief

A brief that produced a bad result is not a failure; it is the most useful thing you will learn from this unit. Homework 4 rewards showing one brief you rewrote after a bad result, and why. Keep both versions next to the pull requests.