15.1 The change is the unit of work
- Approved by
- Panaversity ·
In everyday life. A homeowner hires a contractor to rebuild a kitchen. The homeowner does not inspect every nail. Before the work starts, the two agree what the job is for. When the contractor says "all done", the homeowner does not take that as proof. They turn on the tap and watch the water run.
What you will learn. How to judge a change that an agent proposes by two things: its purpose, and the evidence for it.
Why it matters. Writing got cheap. What a team now lacks is the time to prove that a change is right.
Where did the work go?
To the steps around the writing. A bottleneck is the slowest step in a process, and it decides how fast everything else can go. When people wrote every line, writing was the bottleneck. A feature took days to type, test and fix. Coding agents changed that. Tanya's agent, in this chapter's opening story, wrote its change in twenty minutes.
It is as if the contractor could now build a kitchen in a day. The homeowner's part does not shrink. They still say what the kitchen is for, and they still check that it works. So two skills matter most now. The first is specifying intent: saying what you want before any code exists. The second is validation and delivery: proving that what came back is right, getting it reviewed, and getting it safely to the people who use it.
Faster writing does not make a team faster on its own. More changes arrive, and each one still waits in line to be proved. A team that skips the proving ends the way Tanya's story did.
What do I judge, if I do not judge the code?
The change the agent proposes, by its purpose and its evidence. The homeowner judges the job, not the nails. Here is all that Tanya had in front of her when she accepted her agent's change:
Done. All tests pass.
31 lines changed.And here is what Ana Morales, the AP analyst, asks for before she accepts the weekend rule from Chapter 13:
Purpose: pay a Saturday or Sunday due date on the Friday before.
The rule stays off until the setting PAY_WEEKEND_RULE turns it on.
Evidence, with the payment run on Friday, March 5:
rule off 8 invoices, total $19,229.53
rule on 10 invoices, total $33,109.53
Open decision: does AP use this policy at all?The second one is a proposed change: a set of edits offered for you to accept, with its purpose and its evidence. It is the unit of work now, the one piece you judge and accept. A team reads a proposed change on one page, called a pull request. Chapter 12 named it, and 15.3 shows its parts.
What do I ask about its purpose?
What the change is for, and what it must leave alone. The homeowner says: "New cupboards. The pipes stay where they are." Tanya asked her agent to "speed up the payment list". That said what should change. It did not say what must stay the same: the list itself. Her agent made the list faster and shorter.
A purpose can also hold a question that the builder cannot answer. Whether AP pays weekend due dates on the Friday before is a policy. A decision about policy belongs to the person who owns the policy. Here that is Dave Kowalski, the controller. It does not belong to the agent, and it does not belong to the builder. So Ana's change records it as an open decision, apart from the work that is finished.
What counts as evidence?
A run you can repeat: the command, what went in, and what it printed. "All tests pass" is a claim, like the contractor's "all done". Evidence is the water running from the tap.
A count of changed lines is not evidence either. A list of the changed lines, called a diff (15.2), shows which lines changed between two versions of the code. Only a run shows behavior, which is what the program does. Tanya saw 31 changed lines. One run of the payment list would have shown her 6 invoices where there had been 8.
When is evidence weak?
In three cases. A well-written summary can make each of them look strong.
- It is not scoped. Scoped evidence says which outputs were run, and which are only assumed to be unaffected. A contractor who says "everything works" has not said which taps were turned on. When an agent says "all outputs verified", ask which ones it ran.
- It is not sourced. Each expected result needs a source outside the agent: an agreed rule, a calculation by hand, or a person's answer. Tanya's agent changed the test to expect 6 invoices, so the test agreed with the code. If one agent writes the code and its tests from one wrong reading, both agree and both are wrong.
- It is not current. Evidence belongs to one version of the code. If the code changes after the run, the evidence is stale, or out of date, until the checks run again. A tap that was tested before the plumber came back has not been tested.
How much evidence a change needs depends on what it could break. 15.5 sets the amount.
At work. Ana does not accept the two totals above on the agent's word. She asks for the commands that gave them, and has the agent run both again while she watches. Then she asks which files the change touches. One of them is src/reconcile.ts. A rule for the payment list has no clear reason to touch reconciliation, so she asks why.
How do I set up to try this?
Once, in four steps. Every Try it in this chapter uses the folder you make here. You set up Git, Node.js and uv in 13.1.
1. Download. Get brightline-lab-ch15.zip, and unzip it. You get a folder named brightline-lab-ch15, with a folder named brightline-ap inside it.
2. Copy. Copy brightline-ap to a new folder beside it, named practice-15, so the lab still starts clean. Open practice-15 in your agent. Keep your notes in a text editor, outside this folder.
3. Make the agent ask before it acts. Do this before your first message, in your own tool:
Choose Manual in the mode selector.1
Use the permission mode Ask for approval,2 with Work in set to This computer, so the agent works in your folder and not on a machine in the cloud. Codex asks only when a command goes beyond its sandbox,3 so commands inside the project run without stopping. Read what each one did, right after it runs.
4. Install. Send: "Set my git name and email for this project only, and ask me what they are. Then install the packages this project needs, from its own lists, for TypeScript and for Python. Add nothing new." When the agent reports that the packages are installed, the folder is ready.
Try it
Use the folder from the setup above. It holds three versions of Brightline's scripts. One is the trusted version, named main. The other two are proposed changes, kept beside it, named weekend-rule and agent-speedup. You see one version at a time, and the agent can show you any of them. 15.2 gives these things their git names. Here you judge weekend-rule by its purpose and its evidence.
- Send: "What does the version named
weekend-ruleadd to the main version? Show me the notes its author wrote for it. Change nothing." From the notes, write the purpose of the change in one line in your own notes. - Predict: with the weekend rule on, will more or fewer invoices be due by Friday, March 5? Why?
- Send: "Show me the version named
weekend-rule. Run the due list there for 2027-03-05. Then run it again with the settingPAY_WEEKEND_RULEset to on for that one run. Show me the last line of each run." - Send: "How many files does that version change, compared with the main version? List their names. Change nothing." Look for a file whose name has nothing to do with the payment list, and mark it. Then send: "Show me the main version again."
What you should see. Two notes, the newest first: "Add the weekend rule behind PAY_WEEKEND_RULE, off by default", then "Failing tests for the weekend rule". So the tests came first. With the setting off, the last line is 8 invoices, total $19,229.53. With it on, it is 10 invoices, total $33,109.53. Those two lines are the evidence for the claim. Six files change. The one to mark is src/reconcile.ts. Reconciliation checks the dates in an export, and it is not part of the payment list. 15.7 comes back to it.
The operating rule: judge a change by its purpose and its evidence. Ask what it is for and what it must leave alone, and accept a run you can repeat, never a claim.
Next. 15.2 shows how git keeps a proposed change apart from the trusted copy.
Check yourself
Question 1 / 8
0 answered
An agent's pull request says: "Refactored the allocation report. All outputs verified." Which question tests whether that claim is scoped?
Sources
- Owner
- Panaversity