Skip to content
Hands-on Coding Assistants

Part 4 — Build the Harness Chapter 15

Prompt Engineering for Code Assistants

In this chapter

Your prompt derives from your spec

“Fix registration” gives an agent enough information to find the route. It leaves the response format, validation rules, and side effects open. In the spec exercise, a rejected request had to leave the next ID available. If that line is missing from the prompt and the agent skips the spec, you may get an entirely plausible patch that breaks the rule.

Compare three prompts on one task

Use a clean branch at lab-start.

git switch -c prompt-evidence lab-start

Select the same model in three fresh Plan sessions and submit one prompt per session.

Plan a fix for registration.
Read src/app.ts. Plan a change that validates names and email addresses
before storing a registration.
Read specs/registration-validation.md, contracts/registration.test.ts, and
the registration route in src/app.ts. Plan a patch within that route.
Map each acceptance criterion to a check and show how you would observe
the next ID after rejection. Keep the repository unchanged.

Mark each plan for the same things. Did it check types before normalization? Did it set the error status and shape? Did it check the order of validation and ID assignment? Did those points come from a file the session actually read? Open the tool activity to check. If two prompts work equally well on this task, keep the shorter one with the file boundaries you can defend.

Save the chosen prompt as prompts/plan-registration.txt and track it with its input spec. If you use Build, supply the reviewed plan and ask it to run npm test and npm run test:registration separately so you can match one observed result to each command. When a check fails, quote the shortest useful assertion and its input so the agent can locate the failure.

Keep a record that survives the session

A teammate may have the commit and no way to open your conversation. Keep notes/registration-verification.md with the fields you need to review the change. Update it after an intervention changes the task or the patch.

RecordWhere to get it
Starting ref, final commit, and diffgit rev-parse lab-start, git rev-parse HEAD, and git diff lab-start HEAD after you commit the exercise
Spec, prompt, and instruction files usedRepository paths and the exact versions you checked, plus file reads visible in the session
Model and tool configurationModel ID, opencode --version, and the project rules that applied
Commands and resultsTool activity or terminal output, with exit status and failing assertions where relevant
Human interventionWhat changed in the request, patch, or decision, and what you verified after the change

OpenCode can export a session with opencode session export SESSION_ID --sanitize. Use the actual session ID from opencode session list. Check the export before sharing it, and keep evidence of exact commands in your review note if the export omits it.

Try redaction with a fake value such as SAMPLE_REDACTION_MARKER=DO_NOT_SHARE_EXERCISE. Put it in a scratch copy of the note, remove the sensitive value, and search that copy for the exact marker. Review file paths, stack traces and diffs by hand too. Store only the evidence the next reviewer needs. Keep raw session data out of the patch and PR.

References