Skip to content
Hands-on Coding Assistants

Part 1 — Start from a Repository Chapter 1

Introduction & Overview

In this chapter

What this book covers

Someone asks you to fix registration in a service you’ve never run. Before you change the handler, you need to know how to start the service, how it handles invalid input, and what callers expect. In this book you’ll work on a small TypeScript service called the Task API. You’ll use OpenCode to trace a request through the code, then run the service to check what happens.

The request you traced gives you a concrete example for the spec. Later, that spec helps you catch a patch that returns the right error and still changes state. The exercises stay with the Task API so you can carry work forward. Your fork is where you’ll keep the documents, tests and patches you produce.

How the book is organized

Start from a Repository begins with getting OpenCode running with a local model or a free hosted model. You’ll map the Task API from its entry points and tests, turn a vague request about registration into acceptance criteria, and review a plan before asking OpenCode to implement it. The debugging exercise gives you a related failure. A rejected registration consumes an ID, so you have to send a second request to see what went wrong. You’ll reproduce that sequence and save it as a regression test.

In Shape and Document a Change, you’ll plan a larger feature that lets people label tasks and find them again. You’ll break the work into tickets, work out which tasks can run in parallel, and document the current service with C4 diagrams in Mermaid. That picture of the existing system gives reviewers a common starting point for your proposal, which you’ll write as a request for comments (RFC). You’ll revise it after review and record the decision about durable storage in an architecture decision record (ADR).

In Investigate a Production Incident, the Task API’s simulated gateway starts returning HTTP 504 when callers try to create tasks. You’ll use the Docker Compose lab to compare traces, logs and request counts in Grafana. From those records you’ll work out when the failures began, which requests were affected and whether service recovered after the rollback. The postmortem records what the evidence supports and gives you a reason to improve monitoring later in the book.

Build the Harness returns to the earlier exercises and makes some of their checks repeatable. You’ll put tests and coverage in CI, require a passing check before merge, and see an alert fire and resolve in the lab. You’ll also configure how OpenCode works in the repository. The chapters cover versioned prompts and project instructions, a reviewer with limited permissions, and ways to extend the assistant with skills, plugins and MCP.

Prove It on a Change looks at the time it takes to complete and review a change with an assistant, including the time you spend checking its work. Then you’ll implement searchable task labels with the existing in-memory store. You’ll use the spec, tests, review and CI together on the feature, and check what the running service reports when you exercise the new route.

Model, harness, and workspace

When you ask OpenCode to run npm test, the model can propose the command. OpenCode is the harness that connects the model to tools, checks permissions and runs the allowed command in your workspace, the checkout you opened. In the exercises, you’ll inspect the output from the tool call and compare it with the assistant’s summary. You’ll use the Plan agent to investigate and review an approach, then switch to Build when you’re ready to apply a change.

Working through the exercises

Follow the chapters in order on your first pass. Each exercise tells you which revision to open or which branch to continue from. Keep the work you want to reuse, and start from the named checkpoint when a chapter needs a known failure. The examples give you requests to send, tests to run and results to compare, even when your model takes a different route through the task.

When your fork is ready, set up OpenCode and run the first tool checks against the starter. You’ll use that same setup to investigate the repository in the following chapter.

References