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.
| Record | Where to get it |
|---|---|
| Starting ref, final commit, and diff | git rev-parse lab-start, git rev-parse HEAD, and git diff lab-start HEAD after you commit the exercise |
| Spec, prompt, and instruction files used | Repository paths and the exact versions you checked, plus file reads visible in the session |
| Model and tool configuration | Model ID, opencode --version, and the project rules that applied |
| Commands and results | Tool activity or terminal output, with exit status and failing assertions where relevant |
| Human intervention | What 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
- OpenCode maintainers. CLI commands and Session commands. Official OpenCode 2 documentation for sessions and sanitized exports.
- Git maintainers. git-diff. Git reference manual.