Lesson 3 of 14 · 23 min read
Prompting for real work: plans, constraints and tests
Use plan mode, compare a vague prompt with a precise one, state constraints before any code is written, and define done as passing tests.
Code: shop-workspace and the four repositories its setup.sh clones, from the tag lesson-03-start to lesson-03-end. To get the demo, see lesson 1.
This chapter starts at the tag lesson-03-start and ends at lesson-03-end. The script that checks out a tag lives in shop-workspace. Run this there to put all five demo repositories at the start:
./checkout-lesson.sh 03
What you build is an idempotent PaymentCaptured consumer with tests, after first seeing what a vague prompt produces. If a session goes wrong, run this from shop-workspace to jump every repository to lesson-03-end:
./checkout-lesson.sh 03 --end
You need uv, Git, a Claude account with Claude Code access, and the demo repositories. The demo's unit tests use a fake broker, and Kafka is needed only for the end-to-end flow.
This chapter was recorded on Claude Code 2.1.295 in October 2026. Documented defaults, limits, and labels are as of that month and may have changed since. The recording used Opus 5.5 (claude-opus-5-5) at medium effort.
Each claim says where it comes from: 'the documentation says' marks documented behavior, which I paraphrase; 'in the recorded run' marks what the recording showed; and 'in my view' marks my own inference or recommendation. The demo was recorded twice, so I write 'in both recorded runs' where the two agree. Examples I made up for this chapter are marked invented.
The plan-approval menu's third option is the chapter's worked case of using these phrases side by side: one wording was recorded and a different one is documented.
Model output differs between runs, so your plans and code will differ from the recorded runs and from lesson-03-end.
1. The official sequence: explore, plan, implement
The documentation says, in its best-practice guidance, to explore first, then plan, then implement, and to skip the plan when you could describe the diff in one sentence.
In this chapter, explore means reading the relevant code and context before a plan exists. Implement means the edits that follow once you have agreed the plan.
Plan mode is how this chapter carries out the plan step. In plan mode Claude proposes a plan and you read it. The documentation says a menu then asks what to do next. You read the plan and decide at that menu before you approve anything.
The one-sentence rule is a test you apply to a request. Take an invented task: add the order ID to one log line. The diff fits in one sentence, so the rule says skip the plan.
Now take the vague prompt typed in the recorded run and used later in this chapter: Handle payments in orders. Try to write its diff in one sentence. In my view you cannot, because the decisions behind it are unmade: what handling means, which states are involved, which places change. The documentation gives the one-sentence test itself, and this reading of the prompt is mine.
In my view, the chapter's demo task, an idempotent PaymentCaptured consumer with tests, falls on the plan side of the rule too: once you list what idempotent has to mean, its diff no longer fits in one sentence. Activity 1 has you sort six tasks with this test.
2. A vague prompt: what two recorded runs planned
The vague prompt for this chapter is the one typed in the recorded run. It is not a documented pattern. It reads exactly:
Handle payments in orders.
In both recorded runs, this prompt produced a plausible plan full of decisions nobody asked for. The recording gives three examples: a new PAID status, changes to the end-to-end tests or flow, and edits in shop-workspace. The rest of this chapter calls them the three decisions from the vague runs. This is what the recording showed. It is not guaranteed output, and the plan you get will differ.
The recorded plans were plausible. They read like reasonable answers to the request. In my view the problem is whose decisions they contain: Claude's, not yours. Someone who approved such a plan would be approving choices they never made. I draw that from two recorded runs, and it is not a rule about every vague prompt.
The contrast is the precise prompt in the recorded runs, which named constraints and tests before any code. The section on stating constraints develops it. Activity 2 has you run the vague prompt yourself and list the decisions you did not ask for.
3. Reading the plan-approval menu
After a plan, Claude Code shows a menu that asks what to do with it. The documentation says the menu has three options. Two of the three labels are the same in the recording and in the documentation. The third differs.
The labels side by side:
| Option | Recorded (lesson 03 recording) | Documented (current official documentation) |
|---|---|---|
| First | Yes, and use auto mode | Yes, and use auto mode |
| Second | Yes, manually approve edits | Yes, manually approve edits |
| Third | Tell Claude what to change | No, keep planning |
In the recorded run the third option read 'Tell Claude what to change'. The documentation says it reads 'No, keep planning', and the two labels do not agree. The documentation describes the third option as 'stay in plan mode and tell Claude what to change'. That description says what the option is for: staying in plan mode and telling Claude what to change.
I cannot confirm the exact label that Claude Code 2.1.295 shows. Claude Code's changelog has no entry from 2.1.288 to 2.1.296 that renames the option, and that does not settle which label is right. In my view two explanations are possible: the recorded wording may be a placeholder, or the label may differ between versions. I have nothing that decides between them.
Expect your own menu to read differently from one of these columns, or from both. Record what you see, word for word. Activity 3 gives you the record to fill in.
4. Stating constraints before any code
A precise prompt settles, before any code is written, the decisions the vague prompt left to Claude. For the PaymentCaptured consumer, four of those decisions are engineering constraints. Each constraint is a question you answer in the prompt. In my view these are the four questions to answer:
- Idempotency: what happens if the same event arrives twice?
- Retries: what is retried, and what must be safe to repeat?
- Compatibility: what existing behavior, event shapes, or data must stay unchanged?
- Transaction boundaries: what must succeed or fail together?
Answer each as something you could observe from outside, not as a design. An invented example of an observable requirement: 'Delivering the same event twice leaves the same result as delivering it once.' It names no mechanism. The plan is where Claude proposes one for you to review.
In the recorded runs, the precise prompt named constraints and tests before any code. The skeleton below is one I built for this chapter, and it is not the recorded prompt. Fill each bracketed slot with your own answer:
Goal: The orders side handles PaymentCaptured events idempotently.
Before planning, read [what already exists for handling events on the orders side].
Constraints, each stated as something I could observe:
- Same event twice: [what must be true afterwards]
- Retries: [what is retried, and what must be safe to repeat]
- Compatibility: [what existing behavior, event shapes and data must not change]
- Transaction boundaries: [what must succeed or fail together]
Scope: for each of a new PAID status, changes to the end-to-end tests or flow, and edits in shop-workspace, [in scope or out of scope].
Done means: the service's tests pass, and each constraint above has a test.
Present a plan before writing any code.
The three decisions from the vague runs work as a checklist: a new PAID status, changes to the end-to-end tests or flow, and edits in shop-workspace. For each one, the precise prompt should say whether it is in scope or out of scope.
The skeleton follows the sequence the documentation gives: the read-first line is the explore step, and the plan request is the plan step.
In my view, start the precise attempt from a clean context. The plan from the vague attempt is still in the context window, where it can shape what comes next. /clear or a new session drops it.
5. Tests as the definition of done
Done needs a definition. The documentation says to give Claude a way to verify its work. For the PaymentCaptured consumer, passing tests are that way. Done means the orders-service tests pass, including tests for the consumer. Run them in orders-service with uv run pytest -q.
In the two consistent recorded runs, Claude wrote code and tests together and ran the suite once. So asking for 'done means tests pass' did not set the order in which Claude wrote code and tests. Two runs do not show what Claude always does, and your session may differ. Activity 6 has you look at the order in your own session and write it as 'in my run'.
Read the tests as well as the implementation when you review the diff. In my view, for each constraint you stated, find the test that covers it, or note that none does. These are the questions I would put to the tests:
- Idempotency: is there a test that delivers the same event twice?
- Retries: is there a test for handling that is repeated after a failure?
- Compatibility: do the existing tests still pass unchanged, and does any test pin the old behavior?
- Transaction boundaries: is there a test where handling fails part-way and nothing is left half done?
In my view, passing tests are only as strong as the tests. A suite that passes proves little if no test would fail when a constraint is broken.
6. Reviewing the result against what you asked for
Review the finished diff against what you asked for, tests included. The three decisions from the vague runs are the first things to look for in your own diff. In my view, these are the review questions to ask:
- New PAID status: does the diff introduce any status value or state change you did not ask for?
- End-to-end changes: does it add or change end-to-end tests or end-to-end flow code you did not ask for?
- Edits in
shop-workspace: does it touch the workspace repository,shop-workspace, rather than onlyorders-service?
A change that traces to none of your requirements is a decision you did not make. Write down what you found, starting each entry with 'In my run': the change, and the requirement it traces to or the lack of one.
At the end of the chapter your reviewed PaymentCaptured consumer with tests, passing, is committed on a scratch branch in orders-service, or stashed or discarded if you chose that route, and git status --short prints nothing in each of the five demo repositories. You also hold your notes: the table of six tasks, the list of unrequested decisions from the vague prompt, the three-way menu label record, your precise prompt, the requirement-to-test mapping, and your note on the order of code and tests. lesson-03-end is the reference state to compare your result against. Your result is a variant of it, not a copy, and differences are expected because model output varies.
Activity 1: Apply the one-sentence rule to six invented tasks
This exercise applies the one-sentence rule to six tasks and changes nothing in the demo. It fixes the plan or skip decision that the PaymentCaptured work in Activity 5 depends on. The documentation says to skip the plan when you could describe the diff in one sentence. In my view, that means you plan when you could not.
Task 1 is the vague prompt typed in the recorded run. Tasks 2 to 6 are invented for this exercise, and some name parts of the shop that you may not find in the code, so judge each one from its wording.
- Handle payments in orders.
- Add an idempotent consumer for PaymentCaptured events on the orders side, with tests.
- Correct a spelling mistake in one error message in orders-service.
- Remove one unused import that ruff reports in orders-service.
- Add a delivery fee to every order: store it, include it in the OrderPlaced event, and have payments charge it.
- Add the missing type annotation to one function argument in orders-service.
Steps:
- For each task, write the diff in one sentence. If you cannot, write 'cannot be stated in one sentence'.
- Mark each task 'plan' or 'skip the plan'.
- For each task marked 'plan', name one thing to read or explore before planning. Explore here means reading the relevant code and context.
- Put the result in a table with four columns: task, one-sentence diff or 'cannot be stated', plan or skip, and what to explore first.
You should end with:
A small table of six rows in your notes, with the four columns from step 4.
Hints:
- In my view, a sentence that has to list several behaviors or several places is a sign the diff does not fit. The documentation gives only the one-sentence test itself.
- In my view, a request whose decisions are unmade cannot be summarized as a diff, which is why the vague prompt lands in the 'plan' group.
Check yourself:
- Every task has either a one-sentence diff or an explicit 'cannot be stated', and a plan or skip decision. Read the table: no row lacks a decision, and each 'skip' row carries a real one-sentence diff.
- Tasks 1 and 2 are both marked 'plan'. Look at those two rows.
Activity 2: Run the vague prompt in plan mode and list what you did not ask for
This lab shows you a plausible plan made of decisions the prompt never stated, and lets you compare it with the two recorded runs. It changes no code. It produces the decision list that Activity 4 uses as a checklist for the precise prompt. Do it in one sitting with Activity 3, because the menu you record there is the one that appears at the end of this lab.
Steps:
-
Check that the demo repositories are at
lesson-03-startwith a clean working tree:git statusshows no changes. -
Start a new Claude Code session in
orders-servicewithclaude. Starting in that directory is a lab instruction. -
Put the session into plan mode. In the recorded run, pressing Shift+Tab until the footer showed plan mode did this.
-
Type the prompt from the recorded run exactly:
Handle payments in orders. -
Read the plan without approving it. Write down every decision the plan makes that the prompt did not state, quoting the plan text each one came from.
-
Compare your list with the three decisions recorded for both runs: a new PAID status, changes to the end-to-end tests or flow, and edits in
shop-workspace. Mark each of your entries 'also recorded' or 'not recorded'. Differences are expected and are not errors. -
The menu is now on screen. Before you choose anything, do Activity 3 and copy the labels exactly.
-
Do not choose either approving option. Choose the third option, whatever its label says in your session, and stop there. In the recorded run, the reply typed after choosing it was
No. Drop this plan, I'll describe the task properly.You can type the same reply. -
Drop the attempt from the context with
/clearor by starting a new session. Rungit statusand confirm that it shows no changes.
You should end with:
A list of unrequested decisions, each tied to plan text and marked 'also recorded' or 'not recorded', and a clean git status. In your notes, the prompt and the three recorded decisions are both labeled 'in the recorded run'.
Hints:
- Look for nouns, states, and files that the four words of the prompt never contained.
- Your plan will differ from the recorded plans because model output varies between runs.
- The Shift+Tab route in step 3 is what the recording used. If your installation behaves differently, write down the route that worked for you.
Check yourself:
- At least three unrequested decisions are listed, each quoting the plan text it came from. A reviewer checks that every entry has a plan quotation and is phrased as a decision, not as a complaint.
- Nothing was approved and the working tree is unchanged. Run
git statusin the demo repositories before the next activity. If it shows changes, record them as an observation. - The prompt and the three recorded decisions are both labeled 'in the recorded run'. Check that your note uses that label for both.
Activity 3: Record the plan-approval menu three ways
This exercise keeps three things apart: the recorded label, the documented label, and the label you observe. The third option is the unresolved case. Do it while the menu from Activity 2 is on screen. It changes no code. It gives you a dated record of the menu that the approval step in Activity 5 uses.
Steps:
-
Copy each option label exactly as your session shows it. Note the Claude Code version your installation reports and today's date. Also note the date on which you checked the current official documentation for the documented labels.
-
Fill a record like this one. The first two label columns are fixed. Do not edit them to match what you see.
Option Recorded (lesson 03 recording) Documented (current official documentation) Observed in my session Match First Yes, and use auto mode Yes, and use auto mode Second Yes, manually approve edits Yes, manually approve edits Third Tell Claude what to change No, keep planning -
In the Match column, write 'matches recorded', 'matches documented', 'matches both', or 'differs from both' for each row.
-
Write one sentence on what the third option is for, using the documented description: stay in plan mode and tell Claude what to change. If you add an explanation of why labels might differ, mark it 'in my view'.
You should end with:
A record of the three sets of labels (recorded, documented, and observed) that carries your version, your date, and the date on which you checked the documentation, plus one sentence on the third option's purpose. In the third row, the recorded label sits beside the documented one.
Hints:
- If your third label equals neither the recorded nor the documented one, write it down as it is.
- Your observation says what your session showed. It does not settle what 2.1.295 showed.
Check yourself:
- The Observed column holds verbatim labels with a version and a date. Check that the record has all three observed labels, a version, a date, and the date on which you checked the documentation.
- The third row keeps the recorded label and the documented label side by side, and any explanation you add is marked 'in my view'. Read the third row and the sentence below the table for the words 'recorded' and 'in my view'.
- No sentence states which label Claude Code 2.1.295 shows. Search your notes for any claim about the 2.1.295 label.
Activity 4: Draft the precise prompt
This exercise turns the four constraints and a done criterion into a prompt you write before any code is requested. The prompt you write is your own. It will differ from the one used in the recorded runs and must not be presented as that one. It changes no code. It produces the prompt that drives the consumer you build in Activity 5.
Steps:
- Write a one-sentence goal: the orders side handles PaymentCaptured events idempotently.
- Write one requirement for each of idempotency, retries, compatibility, and transaction boundaries. State each as behavior you could observe, not as a design.
- Write the done criterion: the service's tests pass. Name which tests must exist to cover each requirement.
- Add an instruction to read what already exists before planning, and an instruction to present a plan before writing code.
- Check the prompt against your Activity 2 list. For each of the three decisions from the vague runs (a new PAID status, changes to the end-to-end tests or flow, and edits in
shop-workspace), state whether it is in scope or out of scope. - Arrange the prompt in the order of the skeleton from the section on stating constraints, and save it as text.
You should end with:
Your own precise prompt, saved as text. It has a goal, four requirements, a done criterion, a read-first instruction, and in-scope or out-of-scope statements.
Hints:
- In my view, a requirement states what must hold, for example the outcome of handling the same event twice. It does not say how to implement it.
- If you cannot state a requirement, that gap is a decision you have not made yet.
Check yourself:
- All four constraints, a done criterion, and a read-then-plan request appear before any request to write code. Read the prompt from top to bottom: the request for code comes after all of them.
- Each of the three vague-run decisions is ruled in or out of scope. Check that the prompt names the new PAID status, the end-to-end changes, and the
shop-workspaceedits, or explains why one does not apply.
Activity 5: Plan, approve, implement, and verify the PaymentCaptured consumer
This is the chapter's demo change: a reviewed, idempotent PaymentCaptured consumer with tests, accepted only when the tests pass. Work in orders-service. You start from lesson-03-start with a clean working tree and a fresh context.
Steps:
-
Start from
lesson-03-startwith a clean working tree and a fresh context: a new session, or/clearafter Activity 2. -
Put the session into plan mode the way you did in Activity 2, and submit the prompt from Activity 4.
-
Read the plan against your four requirements and your scope statements. List every mismatch, with at least one line per requirement.
-
If there are mismatches, choose the third option, whatever its label reads in your session, and state the change you want. Read the revised plan. Repeat until the plan matches.
-
In a second terminal, run
git statusin the demo repositories. Nothing should have changed. -
When the plan matches, approve it. In my view, use the option labeled 'Yes, manually approve edits', so that each edit is visible while you read. That is an inference from the label's own words, and I describe its effect no further.
-
Read each edit as it lands, then read the whole diff, tests included.
-
Run the
orders-servicetests withuv run pytest -q. If it fails, give Claude the failure output and ask for a fix. Count the rounds until it passes. -
For each requirement, point to a test that covers it, or write that none does.
-
Leave the demo repositories with a clean working tree. How the checkout script treats uncommitted changes is not documented here, so settle the reviewed consumer before you run
./checkout-lesson.shagain. Choose one route:- Commit it on a scratch branch. In
orders-service, rungit switch -c scratch/payment-captured(the branch name is an invented example), then give Claude the prompt the recorded run typed after the plan was approved:Commit this.You can rungit addandgit commityourself instead. Do not push. In my view this is the route to take unless you want the change gone, because the commit keeps the diff available for the review at the end of the chapter. - Stash it. In
orders-service, rungit stash push --include-untrackedso that new test files go into the stash with the edits. - Discard it. Read
git status --shortfirst. Rungit restore .for the tracked edits and delete the new files thatgit status --shortlists as untracked. Discarding cannot be undone, and it removes the diff from your tree.
Then run
git status --shortin each of the five demo repositories. It should print nothing. If a repository other thanorders-serviceshows changes, read them as part of your diff review and settle them the same way. - Commit it on a scratch branch. In
You should end with:
- a reviewed, idempotent
PaymentCapturedconsumer with tests on the orders side, kept as a commit on a scratch branch inorders-service, or stashed or discarded if you chose that route - a passing run of the service's tests
- the list of plan mismatches and how each was corrected
- diff review notes with the requirement-to-test mapping
- a clean working tree:
git status --shortprints nothing in each of the five demo repositories
The consumer you built is a variant of lesson-03-end, not a copy.
Hints:
- Check the plan against your constraints first, then read the detail.
- In the recorded runs the suite ran once. Yours may run it several times. That is a different run, not an error.
- If Claude reports it is done without having run the tests, say that done means the tests pass, and ask it to run them.
Check yourself:
- No file in the working tree changed before a plan was approved.
git statusis clean at the moment of approval. - The approved plan was checked against all four requirements and the scope statements. The mismatch list exists, even if empty, with one line per requirement.
- The service's tests pass at the end. Run the suite, see it pass, and paste the final summary line into your notes.
- Every requirement is either covered by a named test or marked as uncovered. Check that the requirement-to-test mapping has four rows.
- The tree is clean before the next checkout.
git status --shortprints nothing in each of the five demo repositories. If you committed,git branch --show-currentinorders-servicenames your scratch branch andgit log --oneline -1shows the commit.
Activity 6: Record the order of code and tests in your run
This exercise checks, in your own session, whether asking for passing tests set the order in which Claude wrote code and tests. It changes nothing in the demo. It adds the labeled run observation that the chapter's definition of done relies on.
Steps:
- Look back through your Activity 5 session, as far as your terminal scrollback goes. Find when the test files were created or edited relative to the implementation files.
- Note whether the suite ran once or several times.
- Write three sentences that begin 'In my run': the order you saw, how often the suite ran, and how this compares with the two recorded runs, where Claude wrote code and tests together and ran the suite once.
- Write one more sentence on what your done criterion did and did not determine.
You should end with:
A short note, labeled as a run observation, on the order of code and tests in your own session.
Hints:
- A comparison with the recorded runs can match or differ. Neither outcome is a failure.
- One session cannot show what Claude always does, so do not generalize from it.
- This activity observes the order. It does not ask you to change it.
Check yourself:
- The note says 'in my run' and names the order observed. Read the note for a concrete description of the edit order.
- The note makes no claim about how Claude always orders work, and it mentions that in the recorded runs the done criterion did not set the order. Check that the note contains no general rule and refers to the recorded runs.
This chapter adds the demo's idempotent PaymentCaptured consumer with tests on the orders side. You build it through a plan you reviewed against four stated constraints (idempotency, retries, compatibility, and transaction boundaries), and you accept it only when the service's tests pass. It is the first demo change in the course made by plan then implement, and the first with tests as the stated definition of done.
Starting state: all five demo repositories at lesson-03-start, reached with ./checkout-lesson.sh 03, with a clean working tree and a fresh Claude Code session. The vague-prompt attempt in Activity 2 changes nothing, and git status confirms it before the consumer work begins.
Ending state: your reviewed idempotent PaymentCaptured consumer with passing tests is committed on a scratch branch in orders-service, or stashed or discarded if you chose that route, and git status --short prints nothing in each of the five demo repositories. You also hold your notes. lesson-03-end is the reference state to compare against, and ./checkout-lesson.sh 03 --end jumps every repository to it. Your result is a variant of it, not a copy, and differences are expected because model output varies.
What you hand on at the end of the chapter:
- a table sorting six tasks into 'plan' and 'skip the plan', with one-sentence diffs
- a list of the unrequested decisions found in the plan from the vague prompt typed in the recorded run, each tied to plan text and marked 'also recorded' or 'not recorded'
- a record of the plan-approval menu labels (recorded in the lesson 03 recording, documented in the current official documentation, and observed in your session), with your Claude Code version, the date, and the date on which you checked the documentation
- your own precise prompt, with a goal, four constraint requirements, a done criterion, a read-then-plan request, and in-scope or out-of-scope statements
- a reviewed idempotent
PaymentCapturedconsumer with passing tests, committed on a scratch branch inorders-serviceor stashed or discarded as you chose - a clean working tree in each of the five demo repositories
- a requirement-to-test mapping that covers idempotency, retries, compatibility, and transaction boundaries
- a short run observation on the order of code and tests in your own session