Add a health endpoint without breaking the existing one

The task is bounded: the service already answers /health, and the ticket is to add GET /healthz alongside it (the previous lesson located the existing handler). Ask for the additional /healthz address. The project is the course’s payments service: an Express and TypeScript app whose routes begin in src/index.ts, with payment code under src/payments/ and Vitest tests in tests/, run with npm test. Use it if your course host supplies it. Otherwise read this lesson as a walkthrough, or adapt the task to a disposable Express project you own, substituting its test command, paths, and baseline; the chapter introduction describes the project and both options. Begin from an unchanged working copy, and run npm test in a separate terminal to record the baseline before Claude edits anything.

The shipped payments fixture currently starts with six passing tests. Save your actual result rather than trusting that count: it is the comparison you will need when the agent later says it has finished. Claude cannot see that other terminal, so put the result where the session can use it: paste the summary and any failure names into the conversation before you send the ticket, or save the output to a file in the project and ask Claude to read it. The ticket below refers to “the baseline we recorded”, and that comparison works only if the before-change result is in the session’s context.

Give the ticket an edge

Send this prompt in the session that inspected the route:

Add GET /healthz to this payments service. It must return HTTP 200
with the JSON body {"status":"ok"}.

Keep GET /health working with the same response. Do not change payment,
ledger, or rate-limiting behavior, and do not add a runtime dependency.

Add HTTP-level tests for both health routes in tests/health.test.ts.
Use the project's existing test runner. If making the app importable
requires separating it from server startup, explain that change.

Run the new tests and the full suite. Compare full-suite failures with
the baseline we recorded. Report what passed and what remains failing.
Do not commit yet.

The preservation requirement matters as much as the new endpoint. Without it, a rename could satisfy the first sentence and still break an existing caller. The test requirement matters too: a function returning an object is not evidence that an HTTP request reaches the right handler.

This prompt gives the agent a result to produce and boundaries to respect. It leaves room for implementation judgment, including one complication visible in the current source: src/index.ts creates the Express app and starts listening on port 3000 in the same file.

Watch the first unexpected change

An HTTP test needs an application it can exercise. Importing the current entry point also starts the server. The agent may therefore propose moving application construction into src/app.ts and leaving server startup in src/index.ts.

That is more than adding a route, but it can be justified by the test. Read the proposed extraction: existing routes and middleware should retain their order and behavior. A new payment abstraction, dependency upgrade, or unrelated cleanup has a different justification and belongs outside this ticket.

If a test reports EADDRINUSE, check whether importing the entry point started a server on a port already in use. Separate app construction from startup and make the test close any server it opens. Do not keep retrying against an unexplained listener; you could be testing yesterday’s process.

Permission prompts may appear as Claude requests edits or commands. Their frequency depends on the session’s permission mode - the setting that decides which actions run without asking - and saved rules. Use /permissions, typed at the prompt of the running session, to inspect those rules, and review the scope of any approval you grant. An approval allows an operation; it does not certify the resulting code. See the permission reference.

Ask the tests a precise question

After the agent creates the test file, run the checks yourself from another terminal in the project:

npm test -- tests/health.test.ts
npm test

The focused run should exercise both addresses through HTTP, checking status 200 and the JSON body. Inspect the test to confirm it does that. The full run tells you whether the wider suite passes or how its failures compare with the baseline. Neither command has a universal expected test count, and this walkthrough does not substitute an invented transcript for your result.

If the health tests pass but the full suite regresses from the recorded baseline, the narrow result is not enough: the new behavior has coverage, but the project is not ready. Investigate any new failure before accepting the change. Do not let the agent delete a failing assertion to improve its summary.

This is the feedback loop in miniature: inspect enough to form a hypothesis, make a bounded change, then use the result to decide what to inspect next. The following widget shows a separate, illustrative login example. Its files and timings are simulated; follow how a failed check sends the agent back into the work.

Step 1 / 8You hand over a task

Reset← BackNext →

you→gather context→act→verify↺→done

> The login test is failing on main. Fix it.

(prompt enters the window)

Your message lands in the context window. In this illustrative run, the model starts by reproducing the failure so it has evidence to investigate.

The stepper’s closing note - every tool result from the loop stays in the window - does not refer to the next lesson. It points at what fills the context window and what that costs, a later chapter of the course.

Your health check is simpler than that example, but the same question closes both: what did the verification actually establish? Keep the test output beside the diff. The next lesson uses both to decide whether the change is ready.