The animated scenes show on a laptop or desktop screen.

Plan mode

Plan mode and working in rounds

One engineer on Razorpay's payments platform team has four tickets on a Monday. This chapter shows which two of them Claude Code can change straight away, why 20 files of a 48-file migration had to be edited again when Claude started it the same way, and how plan mode avoids that. The same team then improves its work in rounds, using examples, tests written first, questions before building, and one message for bugs that affect each other.

What this chapter shows you

  1. Small changes need no plan, and large changes do. Two of the four tickets fit in one sentence each, and when Claude started a 48-file migration without a plan, 20 files had to be edited again.
  2. In plan mode, Claude reads and plans before anything changes. The Explore subagent does the searching in its own context, and the engineer's approval starts the edits.
  3. Examples and tests show Claude the result you want. Three examples make a format consistent. With tests written first, fewer tests fail each round, and one test case makes the migration keep a NULL amount as NULL.
  4. Claude asks questions first, and related bugs go in one message. Claude interviews the engineer before the order-tracking code is built, and three rounding bugs on a shop's bill are fixed in one message.
  5. Check yourself. Choose plan mode or direct execution for six tasks, then answer one question in the exam's style.

Part 1: Small changes need no plan, and large changes do

Razorpay's payments platform team from chapter 2, about 40 engineers in Bengaluru, keeps its code in one , payments-platform. The engineers use in a terminal on their laptops. Claude Code is the program on the laptop that reads and edits files and runs commands, and Claude is the model it sends each request to, which decides what to do next. Money in this code is a whole number of , as the team's says, so ₹1,234.56 is stored as 123456.

On Monday, 19 October 2026, one engineer on the team has four tickets. PAY-3101 reports that the refunds service accepts a refund dated before the order it refunds was placed. PAY-3102 is a that the checkout service throws at line 88 of receipt.ts when an order has no coupon, and the ticket includes the . PAY-3103 asks for the old Rupees , which stores amounts as decimal rupees such as 499.50, to be replaced with a new helper, Money, that stores whole paise such as 49950, in all 48 files that use it. Those files are in three services: checkout, which takes payments, refunds, and catalogue, which checks each order against the price list of the shop that sold it. PAY-3104 asks for every customer to get a receipt after paying, either by email or on WhatsApp.

Claude can make a change you can describe in one sentence straight away.

is the exam guide's name for asking Claude to make a change straight away: Claude reads what it needs and edits the files in the same . It suits simple, well-scoped changes, such as adding one check to one function. is a of Claude Code in which Claude reads the code and writes a plan, and Claude Code blocks edits to the project's files until the engineer approves the plan. The exam guide says plan mode is designed for large changes across many files, for work with more than one valid approach and for decisions about how the system is structured.

A permission mode decides which actions Claude can take without asking the engineer. The engineer moves to the next mode by pressing Shift+Tab, and the status bar at the bottom of the terminal names the current one. This chapter uses four modes:

⏸ manual mode on

Read files. In Claude Code asks the engineer before each file edit and before each command that is not read-only.

⏵⏵ accept edits on

Read and edit files. In Claude Code still asks before most commands.

⏵⏵ auto mode on

Read, edit and run commands. In a checks each action that is not a read or a file edit in the project before it runs, and blocks the ones it judges unsafe.

⏸ plan mode on

Read and search. In plan mode, edits to the project's files are blocked until the engineer approves a plan.

Claude Code has no setting called direct execution. For direct execution the engineer asks for the change while Claude Code is in manual, accept-edits or auto mode.

Claude Code's best-practices page gives a quick test: “If you could describe the in one sentence, skip the plan.” PAY-3101 passes it: reject a refund dated before its order. PAY-3102 passes it too, because the stack trace names the file and the line: show no discount when the order has no coupon. PAY-3103 fails it, because the change touches 48 files in three services. PAY-3104 fails it too, because it has two valid designs that need different . Email needs a mail-sending service and a sender address that inboxes accept as genuine. WhatsApp needs a WhatsApp business account and message templates that WhatsApp approves before they can be sent.

Direct execution or plan mode

The engineer has four tickets. Two are small fixes, one is a migration across 48 files, and one asks for a choice between two designs.

Each small fix can be described in one sentence, so Claude makes both changes straight away. This is direct execution.

The migration touches 48 files in three services, so it goes to plan mode, where Claude reads and plans before any file changes.

The fourth ticket has two valid designs, receipts by email or on WhatsApp, and each needs different infrastructure. Choosing between them is also work for plan mode.

Small, well-scoped changes go to direct execution, and changes across many files or with more than one valid design go to plan mode.

Two tickets fit in one sentence, and two need a plan

The engineer has four tickets for Monday, 19 October: a refund date check, a TypeError with its stack trace, the Money migration across 48 files, and a choice between sending receipts by email or on WhatsApp.

The change for PAY-3101 fits in one sentence, and so does the change for PAY-3102. Both tickets go to direct execution.

PAY-3103 cannot be described in one sentence, because it changes 48 files in three services, and PAY-3104 needs two sentences, one for each design and its infrastructure. Both tickets go to plan mode.

The two tickets that Claude can change straight away each fit in one sentence. The two that need plan mode do not: one changes 48 files, and the other needs a choice between two designs before any file changes.

The engineer's first attempt starts the 48-file migration without a plan.

The engineer handles PAY-3103 like the first two tickets, with a long instruction that fixes the order and the structure of the work before anyone has read the code. The engineer assumes that catalogue has to stay in rupees, because it checks orders against the shops' price lists, which are written in rupees. Claude Code is in auto mode, so Claude edits files without stopping to ask about each one.

The team has built services/catalogue for shops that take payments through Razorpay. Each shop uploads a to it, a spreadsheet of its products and prices, with prices typed in rupees, such as 499.00. The code in services/catalogue/src/pricelists/ reads these spreadsheets and checks that every order was charged the price on the shop's list. Nobody on the team has read that code yet.

Replace Rupees with Money. Amounts are integer paise.

This line says what to change and repeats the paise rule from CLAUDE.md.

Convert checkout first, then refunds. Convert each service
at its API boundary. Catalogue stays in rupees, because it
checks orders against the shops' price lists, which are in
rupees. Wherever a file passes an amount to catalogue, wrap
it in toRupees().

This part fixes the structure in advance. A service's API boundary is the place where it sends amounts to another service or receives them, and because catalogue is assumed to stay in rupees for good, every amount sent to it is turned back into rupees with toRupees().

Do not change src/pricelists. Keep the tests passing.

This line keeps Claude out of the price-list code, which nobody has read, so nothing in the prompt says where the shops' prices enter the code.

The exam guide's sample question about a large restructuring lists three ways to start without a plan, and this migration uses all three. The engineer writes a long instruction before anyone has read the code, which, in the guide's words, “assumes you already know the right structure without exploring the code”. Claude starts editing straight away and works out the design as it goes, which “risks costly rework when dependencies are discovered late”. The engineer switches to plan mode only when the work gets hard, which “ignores that the complexity is already stated in the requirements”: the ticket already said 48 files, a new money helper and three services.

Direct execution on a large change

The engineer writes a long prompt for the migration before anyone has read the code, and one line tells Claude to turn every amount sent to catalogue back into rupees with toRupees(). Claude reads the whole prompt.

Claude starts editing straight away, with no plan. It converts files service by service and adds a toRupees() call wherever a file passes an amount to catalogue, as the prompt asked.

Claude reaches the price-list code and finds that the shops' rupee prices enter in one file, import.ts. If that file turned them into paise, all of catalogue could work in paise, and every toRupees() call Claude added would send catalogue a figure 100 times too small.

The toRupees() calls have to be removed again, so every file Claude has converted must be edited a second time.

Only now does the engineer switch to plan mode. The ticket already said the job covered 48 files, a new money helper and three services, so the plan was needed before the first edit.

A long prompt written before reading the code, starting without a plan and switching to plan mode only when the work got hard all led to this rework.

Without a plan, 20 of the 48 files are edited twice

The engineer's prompt asks Claude to convert checkout and then refunds, keep catalogue in rupees and wrap amounts sent to catalogue in toRupees(). Auto mode is on, so Claude edits files without asking.

Claude converts the 14 files in checkout and then 6 in refunds, one file per turn, and adds a toRupees() call wherever a file passes an amount to catalogue. By now Claude has taken 20 turns.

Claude opens check.ts and finds that it compares prices that import.ts produces. If import.ts turned rupees into paise, all of catalogue could use paise, and the toRupees() calls in 20 files would send it figures 100 times too small, so they must come out.

At turn 20 the engineer presses Shift+Tab three times, through manual mode and accept-edits mode, to reach ⏸ plan mode on. The 20 files still have to be edited again.

Each of the 20 files was converted as the prompt asked, and all 20 still had to be edited again, because the conversion to paise belongs where catalogue reads the shops' price lists, and nobody had read that code before the edits started. Keeping the toRupees() calls would have left catalogue's price checks in decimal rupees, which the CLAUDE.md paise rule forbids and PAY-3103 exists to remove.

Plan mode is the mode whose status bar reads ⏸ plan mode on, in every version. As of 22 October 2026, Claude Code version 2.1.283 and later starts new terminal sessions in auto mode unless a setting chooses another mode, so Shift+Tab passes through ⏸ manual mode on and ⏵⏵ accept edits on before it reaches ⏸ plan mode on. Older material starts the cycle in manual mode.

Part 2: In plan mode, Claude reads and plans before anything changes

Plan mode is on, and Claude asks to read libs/money/rupees.ts. What happens?

Claude Code blocks edits until the engineer approves the plan.

is Claude Code's for designing a change before making it. Anthropic's docs describe it this way: “Claude reads files, runs to explore, and writes a plan, but does not edit your source.” The at the bottom of the terminal shows ⏸ plan mode on for as long as plan mode lasts.

For PAY-3103, plan mode means Claude can read all 48 files, the price-list code and the before any file changes. If the first approach is wrong, the engineer corrects the plan while every file is still as it was, so nothing has to be undone.

The engineer can turn plan mode on in four ways. Shift+Tab moves the status bar through the modes until it shows ⏸ plan mode on. Typing /plan followed by a description enters plan mode and starts on that task at once. claude --permission-mode plan starts a whole terminal in plan mode. A project can also make plan mode the starting mode for every terminal session in its :

{
  "permissions": {
    "defaultMode": "plan"
  }
}

.claude/settings.json in the repository. With defaultMode set to "plan", every new Claude Code terminal session in payments-platform starts in plan mode unless the engineer passes another mode with --permission-mode.

Claude can also switch into plan mode itself, with its EnterPlanMode tool. Plan mode makes one exception to its block on edits: Claude writes its plan to a file in a folder on the engineer's laptop, ~/.claude/plans/, outside the repository. Every file in the project stays as it was.

Claude Code gives Claude tools for this work. opens a file, searches the text inside files for a word, finds files by their names, change files, and runs a shell command.

For the exam, Grep searches the text inside files and Glob finds files by name, both as built-in tools. As of 22 October 2026, Claude Code on macOS and Linux, including Linux running inside Windows, leaves Grep and Glob out of its default tools and searches with the grep and find commands through Bash, unless Grep or Glob is named in --tools or when the session starts. Razorpay's team names them when it starts a session, so this chapter uses them.

Plan mode

The engineer turns on plan mode, and the status bar shows ⏸ plan mode on. Until the engineer approves a plan, Claude Code blocks edits to the project's files.

Claude reads the code freely. With Read, Grep and Glob it finds the 48 files that use Rupees and reads the money helper.

Claude runs shell commands that explore without changing anything, and reads the price-list code that takes in the shops' rupee prices. Claude does not try to edit a file.

Claude writes the plan to a file in a folder on the engineer's laptop, outside the project, ~/.claude/plans/. It says where the shops' rupee prices will become paise and in what order the services change, in six numbered steps.

The engineer's approval ends plan mode and starts the edits. Until then, every source file in payments-platform stays as it was.

In plan mode, reads run without asking, and so do the commands on Claude Code's built-in read-only list, such as git log. Any other shell command goes to the same as in , which lets the command run or blocks it. When auto mode is not available, Claude Code asks the engineer instead. One example is pnpm tsc --noEmit, which checks the TypeScript code for type errors, values of the wrong kind, without running it or writing any files. It changes nothing, but it is not on the read-only list, so the classifier checks it before it runs.

In plan mode, reads run and edits are blocked

The engineer types /plan migrate the money helper to Money in paise, and the status bar changes to ⏸ plan mode on. From this point Claude Code blocks Claude's Edit and Write tools on the project's files.

Claude Code, on the laptop, sends the task to Claude, the model, in an API request, with a note that plan mode is on. Claude reads it.

Claude asks for Grep("Rupees"), Read(libs/money/rupees.ts) and Read(pricelists/check.ts). Claude Code runs all three without asking, because plan mode allows reading and searching.

Claude Code sends the results to Claude: 48 files use Rupees, Rupees stores decimal rupees, and the price check compares prices that import.ts produces from the shops' spreadsheets.

Claude asks to run a type-check, pnpm tsc --noEmit, which changes no files. It is not on the read-only list, so the classifier checks it and lets it run, and the result comes back: no errors.

Plan mode lets Claude write one file, its plan, in ~/.claude/plans/ on the laptop. Every file in services/ stays as it was.

The plan's six steps appear in the terminal. The status bar still reads ⏸ plan mode on, and edits are still blocked.

Claude read the code, ran a type-check and wrote the plan file, and every file in services/ stayed exactly as it was, because plan mode blocks edits to the project's files and leaves reading open.

For the exam, plan mode lets Claude explore the code and design the change before anything is changed. Claude Code has one more mode, , in which it runs almost every action without asking. As of 22 October 2026, in an interactive terminal session started with bypass permissions available, Claude Code does not enforce plan mode's block on edits, and Claude is only told not to edit. A payments team should not start sessions that way.

The Explore subagent does the searching in its own context window.

A is a separate Claude instance that a session starts for one job. It has its own , and only its final answer comes back to the main conversation. The is a read-only subagent built into Claude Code for searching and reading a codebase.

So far in plan mode Claude has made one search and two reads. Planning PAY-3103 in full starts with discovery: find every use of Rupees and how each one does arithmetic. That means hundreds of search matches and dozens of files. If Claude does this in the main conversation, every match and every file it reads stays in the main context window, before the plan is even written. Anthropic's best-practices page warns that as the context fills, “Claude may start ‘forgetting’ earlier instructions or making more mistakes”, and one of the earliest instructions in this session is the paise rule from . The plan and the implementation that follows share the main conversation, so the discovery output goes to Explore and the main context keeps room for both phases.

Claude starts Explore with the and a brief. Explore runs its own searches and reads in its own context window and sends back a summary, so the main conversation receives only the summary. Three details matter for Razorpay. Explore starts without the project's CLAUDE.md, so the paise rule reaches Explore only if the brief states it. Claude asks for a level of thoroughness, quick, medium or very thorough, by writing it in the brief. And Claude cannot send an Explore run a follow-up question after it reports back, so a follow-up needs a new run with a new brief, and the first brief should ask for everything the plan needs.

{
  "subagent_type": "Explore",
  "description": "Find every use of Rupees",

Claude's call to the Task tool. subagent_type picks the built-in Explore subagent, and description is a short title for the job.

  "prompt": "Find every use of Rupees in services/ and libs/
    and how each one does arithmetic. Amounts are integer
    paise. Be very thorough. Group the results by folder."
}

The brief, the only part of the main conversation that Explore receives. It is one piece of text, shown here on three lines. It repeats the paise rule because Explore does not load CLAUDE.md, and it asks for very thorough work.

For the exam, Claude starts a subagent with the Task tool. As of 22 October 2026, Anthropic's docs call this tool Agent, the name it took in Claude Code version 2.1.63, and references to Task in settings and agent definitions still work.

The Explore subagent

Claude does the search itself, and every match and every file it reads is added to the main conversation's context window. The paise rule from CLAUDE.md was loaded at the start of that context.

The context window, all the text Claude can see in this conversation, fills with search output. The paise rule is still in it, and with this much text after it, Claude is more likely to stop following it.

Claude starts again and hands the search to the Explore subagent with the Task tool. Explore does not load CLAUDE.md, so Claude writes the paise rule into the brief.

Explore runs the searches and reads the files in its own context window, and the main conversation's context window does not grow.

Explore returns one summary and ends, and everything it read is discarded. Claude adds the summary to the main conversation, where it will write the plan from it.

The main conversation received one summary in place of every search result, so Claude can still follow the paise rule.

Explore searches in its own context window

Without Explore, Claude runs the search itself: one Grep and then Read after Read. Every result is added to the main conversation's context window, which fills up.

The context window is full, and Claude is now less likely to follow the paise rule from CLAUDE.md, which was loaded at the start.

With Explore, Claude asks for the Task tool with a brief that says amounts are integer paise. Claude Code starts the Explore subagent with its own context window and passes it the brief, without CLAUDE.md.

Explore runs its own Grep and Read calls through Claude Code. Explore's context window fills, and the main conversation's does not grow.

Explore sends back a 40-line summary, which Claude Code passes to Claude, and the main conversation grows a little. Explore then ends and its context is discarded, so a follow-up question would need a new Explore run with a new brief.

The main conversation received a 40-line summary in place of every match and every file, so the paise rule and the work still to come had room in its context window. Explore's own context filled up instead, and it was discarded when Explore returned.

For the exam, the subagent that keeps discovery output out of the main conversation is Explore. As of 22 October 2026, Claude Code also passes research inside plan mode to a second built-in subagent, Plan, which is read-only like Explore and keeps its output in its own context window.

Plan mode and Explore do different jobs. Plan mode is a setting for the whole session, and it keeps the project's files unchanged. Explore is a separate Claude instance with its own context window, and it keeps search output out of the main conversation. An answer that says plan mode keeps discovery output out of the main context has mixed the two up.

Approving the plan switches the session to editing.

Approving the plan means choosing one of the Yes options in the menu Claude Code shows when the plan is ready. The choice ends plan mode and switches the session to the mode that option names. With auto mode available, the menu has three options: Yes, and use auto mode, Yes, manually approve edits and No, keep planning. Without auto mode, the first option reads Yes, auto-accept edits and switches to accept-edits mode. The engineer can press Ctrl+G to open the plan in a text editor and change it first. After a Yes option, Claude starts editing: in auto mode it edits without asking, and in manual mode it asks the engineer before each edit. No, keep planning keeps plan mode on, and the engineer says what to change.

This is the exam guide's combination of the two modes: plan mode for the investigation and the design, then of the approved plan. Claude does not plan again before each file, because the plan already says what each step is. Catalogue is converted before checkout and refunds, so the plan adds a temporary at catalogue's entry for the rupees they still send, and removes it in the last step. Here is the plan Claude wrote for PAY-3103, with the line the engineer added:

1. Add Money (integer paise) in libs/money/money.ts.
   Keep Rupees until step 6.
2. Convert the price-list importer first:
   services/catalogue/src/pricelists/import.ts
   turns the shops' rupee prices into paise as it reads.

The new helper first, then the one file where the shops' rupee prices enter the code, which reading the price-list code showed. From step 2 on, every price from a shop's list is in paise.

3. Convert the other 21 files in services/catalogue.
   Add a temporary adapter at its entry that turns the
   Rupees amounts checkout and refunds still send into
   Money. Run its tests.
4. Convert services/checkout (14 files). Run its tests.
5. Convert services/refunds (12 files). Run its tests.

Catalogue first, so it works in paise before checkout and refunds are converted. Until they are, the temporary adapter turns the rupees they send into paise in one place, so every service's tests can pass after each step and no converted file needs a toRupees() call. Each service is followed by its own tests, so a problem shows up in the folder that caused it.

   And check last week's orders against the price lists
   end to end.
6. Remove the adapter, and delete libs/money/rupees.ts
   when no file imports it.

The engineer's added line under step 5, a full check against real orders, and the last step, which removes the adapter and the old helper.

The plan stays available for the whole migration. Claude Code keeps the plan in its file, and after replaces a long conversation with a summary, the plan is read back from that file into the context.

Approving the plan

The engineer opens the plan in an editor with Ctrl+G and adds one line under step 5: a full check of last week's orders against the shops' price lists.

The engineer chooses an approve option. Plan mode ends, the session switches to the mode that option names, and edits are allowed.

Claude follows the plan's order. It adds Money to libs/money and converts the price-list importer, so the shops' rupee prices become paise in one place.

Claude converts catalogue and adds a temporary adapter, a few lines at catalogue's entry that turn the rupees checkout and refunds still send into paise. Then it converts checkout and refunds, the engineer approves each edit, and each service's tests run before the next service starts.

Claude removes the adapter and deletes rupees.ts, and the full check of last week's orders against the price lists passes.

The approved plan set the order of every edit, from the price-list importer first to removing the adapter last.

Approving the plan ends plan mode and starts the edits

The plan stands in the terminal as six numbered steps. The status bar reads ⏸ plan mode on, and edits are blocked.

The engineer opens the plan in an editor and adds one line under step 5: “and check last week's orders against the price lists end to end”.

Claude Code asks how to proceed. The engineer chooses Yes, manually approve edits, and the status bar changes to ⏸ manual mode on.

Claude follows the plan's order: the new Money helper, the price-list importer, the other 21 catalogue files with the temporary adapter, then 14 checkout files and 12 refunds files, 48 files in all. The engineer approves each edit, and each service's tests pass.

Claude removes the adapter and deletes rupees.ts, and last week's orders match the price lists end to end. No file in payments-platform uses Rupees any more.

The approval was the one switch between the two modes. Before it, plan mode kept every file unchanged; after it, Claude worked through the plan's steps in the order the engineer had approved, and the temporary adapter came out in the last step.

If the team turns on the showClearContextOnPlanAccept setting, the menu gains an extra option, listed first, that approves the plan and clears the conversation, so implementation starts with only the plan in context.

Part 3: Examples and tests show Claude the result you want

Two or three examples make a format consistent when a description leaves it open.

An is one input written next to the exact output expected for it. After a customer pays a shop through Razorpay, the customer sees a on their phone, and its amounts need Indian number format. An engineer asks Claude Code to write the formatter with one sentence: “Format paise amounts on customers' payment receipts in Indian number format.” In run 1 Claude writes a formatter, and the receipt using it shows ₹123,456.00. Runs 2 and 3, from the same sentence, give formatters that show ₹1,23,456 and Rs 123456.00. Each result fits the words, because the sentence does not say where the commas go, whether the are shown or how the rupee is written.

The exam guide's fix for a description that gives different results each time is two or three concrete input/output examples. Anthropic's prompting guide adds that examples should be relevant to the task, varied enough to cover the unusual cases, and wrapped in tags: each example in its own <example> tags, and the whole set in <examples> tags, so Claude can tell the examples apart from the instruction. Here the three examples cover a large amount, a round amount and an amount under one rupee.

Format paise amounts on customers' payment receipts in
Indian number format.

The instruction that gave three different results on its own.

<examples>
<example>12345600 → ₹1,23,456.00</example>
<example>5000 → ₹50.00</example>
<example>99 → ₹0.99</example>
</examples>

Three inputs in paise, each with its exact output in its own <example> tags, and the set inside <examples> tags. Together they settle the comma positions, the two paise digits and the ₹ sign.

Input/output examples

The engineer asks Claude Code for a formatter that shows paise amounts “in Indian number format”. In the first run, Claude's formatter shows 12345600 paise as ₹123,456.00, with the commas in the international places, where Indian format puts them as ₹1,23,456.00.

The second and third runs, from the same words, show ₹1,23,456 and Rs 123456.00. The words do not say where the commas go, whether paise are shown or how the rupee is written.

The engineer adds three input/output examples to the prompt: 12345600 → ₹1,23,456.00, 5000 → ₹50.00 and 99 → ₹0.99.

In the next run a new amount, 98765432 paise, comes out as ₹9,87,654.32, in the same format as the examples.

The three examples decided the choices the description left open.

Three input/output examples make the format consistent

The engineer asks Claude Code for a formatter that shows paise amounts on customers' receipts in Indian number format. With the formatter from run 1, the customer's receipts screen shows ₹123,456.00.

The formatters from runs 2 and 3, written from the same prompt, show the same amount as ₹1,23,456 and then as Rs 123456.00.

Three examples go into the prompt under the instruction, marked with tags so that Claude can tell them apart from it: 12345600 → ₹1,23,456.00, 5000 → ₹50.00 and 99 → ₹0.99.

With the formatter from run 4, every amount on the customer's screen follows the examples, including a new one: ₹9,87,654.32.

The three examples settled the choices the instruction left open, so the formatter from run 4 showed a new amount the same way as the examples.

For the exam, the answer is 2 to 3 input/output examples. As of 22 October 2026, Anthropic's prompting guide for the API suggests 3 to 5 examples for best results.

Write the tests first, then fix the failing tests round by round.

means writing the before the code, then improving the code in rounds: Claude runs the tests, the failing tests show what is still wrong, and the next round fixes those.

The team is building an for shops that take payments through Razorpay: code that pairs each of the day's orders from all shops with the customer's payment for it, using the order number, so each shop can see that every order was paid once and for the right amount. Before any matcher code exists, the engineer writes twelve tests in match.test.ts. They cover the expected behaviour, the , such as a customer who paid twice for one order, and one performance requirement: 1 lakh orders matched in under 5 seconds.

Anthropic's best-practices page explains why the tests come first: “Claude stops when the work looks done. Without a check it can run, ‘looks done’ is the only signal available.” The engineer's first message asks Claude to write the matcher, run the tests, report the failures and leave the tests as written, because Claude could otherwise make a test pass by changing the test instead of the code. Each round Claude runs pnpm test itself and reads which tests failed in the output, and the failures go into the conversation. The engineer's reply asks Claude to fix them, so every round starts from the exact failures. The exam guide calls this iterating by sharing test failures. At the end Claude shows the test output as evidence that the code works.

test("two payments for one order are flagged", () => {
  const orders = [order("A101", 49900)];
  const pays = [pay("A101", 49900), pay("A101", 49900)];
  expect(match(orders, pays).paidTwice).toEqual(["A101"]);
});

order() builds one order and pay() builds one payment for the test. Order A101 for ₹499, written as 49900 paise, has two payments of ₹499 with its order number, so the customer was charged twice. .paidTwice is the list of orders the matcher flags as paid twice, and the test passes only if that list holds exactly A101.

test("1 lakh orders in under 5 s", () => {
  const orders = orderList(100000);
  const pays = payments(100000);
  const start = Date.now();
  match(orders, pays);
  expect(Date.now() - start).toBeLessThan(5000);
});

The performance requirement written as a test. orderList(100000) and payments(100000) build 1 lakh orders and 1 lakh payments, and Date.now() reads the clock in milliseconds. Matching must take less than 5,000 milliseconds, and the two inputs are built before the clock starts, so only the matching is timed.

Tests first

Before Claude writes any code, the engineer writes twelve tests for the order matcher, the code that pairs each order with its payment. One test requires 1 lakh orders matched in under 5 seconds. The engineer asks Claude to report failures and leave the tests as written.

Claude writes the matcher and runs the tests. Three fail, including the timing test at 7.2 seconds, and Claude reports the failures from the test output. The engineer's reply asks Claude to fix them.

In round 2 one test still fails. Claude reports it, and the engineer asks for that fix.

In round 3 all twelve tests pass, including the timing test at 3.9 seconds, and Claude shows the test output.

Because the tests were written first, each run told Claude which requirements were still unmet.

With tests written first, fewer tests fail each round

The engineer writes match.test.ts with twelve tests before any matcher code exists, and asks Claude to write the matcher, run the tests, report the failures and leave the tests as written.

Claude writes match.ts and runs pnpm test match.test.ts: 3 failed, 9 passed. Claude reads the three failures in the output and reports them, and the engineer replies “Fix these failures.”

In round 2 one test fails: a customer who paid twice for one order is not flagged. Claude reports it, and the engineer replies “Fix this failure.”

In round 3 all twelve tests pass, and the timing test matches 1 lakh orders in 3.9 seconds. Claude's last message shows the test output it ran.

The tests existed before the matcher, so each round's failures showed exactly what was still wrong: three tests, then one, then none, with the timing test measured at 3.9 seconds.

One test case settles one edge case.

A is code that runs the function on one input and checks the result against the exact output expected; it runs and either passes or fails. An input/output example sits in a prompt and shows Claude a format. A test case is run against the code and fails unless the output matches exactly, so Claude can check its own fix with it.

The Money migration also moves the old payments , payments_old, into the new table, payments, where amount_rupees becomes amount_paise. Claude writes the . Some old payments failed before any amount was recorded, so their amount_rupees holds . The first version of the script turns NULL into 0 paise, which records a failed payment as a payment of ₹0. The engineer replies “Handle null amounts properly”, and the next version stops with an error on the same row, because the message did not say what the right result is.

The exam guide's fix is a specific test case with the example input and the expected output:

test("a NULL amount stays NULL", () => {
  const old = { id: "pay_old_17", amount_rupees: null,
                status: "failed" };

The input: the real row from payments_old, a failed payment with no amount.

  expect(migrateRow(old)).toEqual({ id: "pay_old_17",
    amount_paise: null, status: "failed" });
});

migrateRow is the function in Claude's migration script that converts one row. The test expects exactly this row back: the amount stays NULL and never becomes 0.

A test case for one edge case

Claude writes a migration script that copies the old payments into the new table and turns rupees into paise. One old payment failed before any amount was recorded, so its amount is empty (NULL), and the script turns it into 0, which makes the failed payment look like a payment of ₹0.

The engineer replies “Handle null amounts properly.” Claude changes the script, and the next run stops with an error on the same row, because the message did not say what the right result is.

The engineer gives one test case: the old row with the empty amount, and the exact new row expected, with the amount still empty (NULL). Claude changes the script, the row comes out with its amount still empty, and the test case passes.

The words left the result open, and one input with its exact expected output decided it.

A test case keeps a NULL amount as NULL

Claude's migration copies the old payments table into the new one. Payment pay_101's ₹499.00 becomes 49900 paise and pay_102's ₹1,250.50 becomes 125050, and pay_old_17, a failed payment with an empty amount (NULL), becomes 0.

The engineer writes “Handle null amounts properly.” The next version of the migration stops at pay_old_17 with an error.

The engineer gives one test case: this old row, and the exact new row expected, with the amount still NULL. Claude changes the script, the test runs against it, pay_old_17 keeps its empty amount, and the test passes.

“Handle null amounts properly” left the right result open, and the test case stated it, so the next run kept the NULL as NULL.

Part 4: Claude asks questions first, and related bugs go in one message

In the interview pattern, Claude asks the questions before anything is built.

The means asking Claude to question you about a task before it builds anything. Claude's questions bring up decisions you may not have thought about, and your answers go into a written specification.

The team is building a tracking page for shops that take payments through Razorpay, so that each customer can see where their order is. Courier companies will send each order's status updates, such as “shipped”, “out for delivery” and “delivered”, to a web address the team sets up, as a . The team needs a webhook consumer: code that receives these updates, stores them and keeps a for each order up to date, so the page opens fast on the customer's phone. The engineer has never built one, so the hard questions are the ones the engineer does not yet know to ask.

The engineer starts with a prompt adapted from Anthropic's best-practices page. Claude asks each question with its tool, which shows a multiple-choice question in the terminal; the engineer picks an option or types a different answer under Other. When the questions are done, Claude writes . The engineer then starts a new to build from it, so the work begins without any of the interview in the context, and Claude reads the specification from its file. Every decision is written in SPEC.md, so the new session starts with a clear context and has everything it needs. SPEC.md is a file the engineer asked for by name, and it is separate from the plan file that plan mode writes.

I want to build a webhook consumer that receives couriers'
status updates and keeps each order's tracking page up to
date. Interview me in detail using the AskUserQuestion tool.

What to build, and the instruction to ask questions through AskUserQuestion before building anything.

Ask about technical implementation, edge cases, concerns,
and tradeoffs. Don't ask obvious questions, dig into the
hard parts I might not have considered.

Which questions to ask: the hard parts, including the ones the engineer has not thought of.

Keep interviewing until we've covered everything, then
write a complete spec to SPEC.md.

When to stop, and the file where the answers go.

The interview pattern

The engineer asks Claude, in one line, for the code that receives couriers' updates and keeps each tracking page current, and asks to be interviewed first. Claude asks its first question with AskUserQuestion, about a decision the request left out, and the engineer picks an option.

Claude's second question is about another decision the request left out, and the engineer picks an answer.

More questions follow, each about something the engineer had not written down. The engineer can pick an option or type a different answer under Other.

When the questions are done, Claude writes every answer into SPEC.md, which is many times longer than the original request.

The engineer starts a fresh session to build. It begins without the interview, and Claude reads SPEC.md from its file.

None of these questions was in the original request, and every answer reached the build through SPEC.md.

Claude's questions become SPEC.md, and a fresh session builds from it

The engineer asks Claude to interview them with AskUserQuestion before building the code that receives couriers' updates, and to write the answers to SPEC.md.

Claude's first question asks what the consumer should do if the same update arrives twice. The engineer picks storing each update's id and skipping ids already seen, and a section headed “Repeats” appears in SPEC.md.

Two more questions cover failures: a slow reply that makes the courier resend an update, and updates that keep failing to arrive. The engineer picks replying at once and alerting after several failures.

The last two questions cover “delivered” arriving before “shipped” and the cached tracking page. SPEC.md then gains the files to create, what is out of scope and an end-to-end check.

The engineer opens a new session. None of the interview is in it, and the engineer types “Implement SPEC.md.”, so Claude reads the file.

Each section of SPEC.md came from a question Claude asked and the engineer answered, and the new session started without the interview and read the specification from its file.

Anthropic's docs add that a good specification names the files involved, says what is out of scope and ends with an end-to-end check, which is why SPEC.md ends with those three sections. The exam guide gives two examples of the design considerations an interview brings up, and these questions covered both: failure modes, such as an update that arrives twice, out of order or not at all, and cache invalidation, which decides when a cached page must be updated or rebuilt.

Bugs that affect each other are reported in one message, and independent bugs are fixed one at a time.

Two problems when the right result for one depends on the other. Fixed one at a time, a correct fix can change a figure that was already checked, or leave the final result as wrong as before. The exam guide's rule is to describe interacting problems together in one detailed message, and to fix independent problems one at a time.

The team is building a bill page for shops that take payments through Razorpay. On one bill the items are worth ₹845.60, with a 10% coupon and of 5% on the price after the discount. The bill is meant to show every amount to the paisa, so the right figures are a discount of ₹84.56, GST of ₹38.05, which is 5% of ₹761.04, and a total of ₹799.09. The bill shows a discount of ₹85.00, GST of ₹39.00 and a total of ₹800.00, so the customer is charged 91 paise more than the right total. Three bugs cause this: three separate pieces of the code each round an amount up to the next whole rupee, one for the discount, one for GST and one for the total.

GST is worked out from the price after the discount, so when the discount is fixed, a GST figure the engineer has already checked changes again. In one message with a worked bill and its expected figures, Claude can design one change that satisfies all three rules.

The total on the bill for items of ₹845.60 is wrong. Three
bugs interact, so fix them together:

The message says at the start that the bugs interact and should be fixed in one change.

1. Round the 10% discount to the nearest paisa: ₹84.56.
2. GST is 5% of the price after the discount, ₹761.04,
   rounded to the nearest paisa: ₹38.05.
3. The total is items minus discount plus GST, with no
   rounding up: ₹799.09.

Each rule with its expected figure for the same bill, so all three can be checked at once.

Add a test with these figures and run it.

A test with the worked bill checks the three rules together.

Three other tickets are different: the typo “reciept” in a log message, a missing on the orders.phone column, which is used to find a customer's orders by phone number, and the wrong date format in the export of bills. None of them affects the others. Each one has its own result, so each fix can be checked on its own. Fixing them one at a time keeps each change small, and if something breaks, the cause is in one change.

Interacting and independent problems

The shop's bill is wrong because of three rounding bugs that affect each other. The engineer reports GST first, and after Claude's fix the total changes from ₹800.00 to ₹799.00, which is still wrong.

The engineer reports the discount. Claude's fix is correct, GST, which the engineer had already checked, changes again, and the total goes back to ₹800.00, the figure it started with.

After the third report and fix, the total is right at ₹799.09. Before this last fix, each correct fix had left the total wrong.

From the same start, the engineer sends one message with all three bugs, a worked bill and its expected figures. Claude makes one change, and every figure on the bill matches the expected one.

Three unrelated bugs, a typo in a log message, a slow lookup of orders by phone number and a wrong date format in a download, are fixed one at a time, and the engineer checks each one before the next.

Fixed one at a time, the bugs that affect each other changed each other's figures. In one message with a worked bill they were fixed together, and each independent bug was fixed and checked on its own.

Interacting bugs are fixed in one message, and independent bugs one at a time

The bill for items of ₹845.60 shows a total of ₹800.00, and the right total is ₹799.09. Working from the bill's discount, the engineer reports that GST should be ₹38.03. Claude rounds GST to the paisa, and the total becomes ₹799.00.

The engineer reports that the discount should be ₹84.56. Claude's fix is correct, GST changes by itself to ₹38.05, and the total goes back to ₹800.00, the figure it started with.

The engineer reports that the total is rounded up and should be ₹799.09. After the third fix the total is right.

Back at the starting figures, the engineer sends one message with all three bugs, the worked bill and its expected figures. One change makes every figure match, and the test checks all three figures together.

Three independent tickets, the typo “reciept” in a log message, a missing index that slows the lookup of a customer's orders by phone number, and the date format in the CSV download of bills, are fixed one at a time, and each is checked before the next.

Reported one at a time, the three rounding bugs changed each other's figures: fixing the discount moved a GST figure the engineer had already checked, and after two correct fixes the total was back at its starting figure. In one message with a worked bill, the three fixes were made and checked together. The independent tickets each had their own result, so each fix was checked on its own before the next.

Anthropic's best-practices page adds a related tip: if you have corrected Claude more than twice on the same issue in one session, the context is full of failed attempts, so run /clear, which empties the conversation, and start again with a more specific prompt.

Part 5: Check yourself

Choose plan mode or direct execution.

The exam guide's practice exercise compares the two modes on tasks of different sizes. Select every task that should start in plan mode, then check.

Select at least one item first.

The bill function writes amounts in words three different ways.

Razorpay's team asks Claude Code to write a function that prints a bill's total in words on printed bills, with the instruction “write the amount in words in the Indian system”. Across three runs, the function turns 25075000 paise into “Two lakh fifty thousand seven hundred fifty rupees”, “250 thousand 750 rupees” and “Rs. two lakh, fifty thousand, seven hundred and fifty”. What should the engineer do next?

Razorpay appears in this chapter only to explain how Claude Code and Claude work. Razorpay has no connection with these tutorials, and the code, systems, numbers and events in this chapter were written for the lesson. They do not describe how Razorpay works, and Razorpay does not use this code.