Part 1 — Start from a Repository Chapter 3
Exploring an Unfamiliar Codebase
In this chapter
Start with a question about the application
Where does a task live between POST /tasks and GET /tasks? The answer tells you where to look when a write appears to succeed and whether the task will still be there after a restart.
In your fork, with a clean working tree, create a branch and open OpenCode.
git switch -c read-task-api lab-start
git status --short
opencode
Choose Plan and the model from setup. Use the assistant to find evidence. Save your own notes once you have checked it. Plan can inspect the repository and can write designated plan files. Its shell calls still follow the tool permission rules.
Sketch the architecture from entry points
On the Plan interface, give this request.
Read AGENTS.md and package.json. Find the runtime dependencies and the
entry points of npm start and npm test. Follow both to the HTTP server.
Find the listen address, default port and configuration override.
Explain where a task is stored. Cite a path and symbol for each finding.
Label any inference. Return your notes in chat.
Open the files it cites. You should find the following paths.
| Path | Evidence to follow |
|---|---|
| Runtime | package.json has no runtime dependencies. src/app.ts imports node:http. |
npm start | package.json starts src/server.ts, which calls createApp() and listens on 127.0.0.1. PORT defaults to 3000. |
npm test | test/app.test.ts uses startApp() in test/client.ts. That helper starts the same factory on port 0, so the operating system chooses a free port. |
| State | createApp() allocates arrays inside the factory. Each fresh instance starts with one task and no registrations. |
Try the port override from your own terminal. Leave the server running for the next two sections.
PORT=3100 npm start
In another terminal, check both initialization and the running API.
curl -sSi http://127.0.0.1:3100/health
curl -sSi http://127.0.0.1:3100/tasks
Expect 200 with {"status":"ok"}, then 200 with [{"id":"1","title":"Write a spec"}]. If an answer names a database, ask for the connection call and open the factory yourself. The arrays explain why restarting the service resets the lab.
Trace a request from input to response
On the Plan interface, give this request.
Trace POST /tasks with the JSON body {"title":" "}. Find where the body
is read, where the title is normalized, and where the route returns.
Does execution reach the array push? Name a test that checks both the
response and the stored state. Return the evidence in chat.
Follow readObject() to the route’s trim() call. The empty title gets 400 and {"error":"invalid_task"}. The branch returns before tasks.push(task). Check both observations in a live request and in the relevant automated test.
curl -sSi http://127.0.0.1:3100/tasks \
-H 'Content-Type: application/json' -d '{"title":" "}'
curl -sS http://127.0.0.1:3100/tasks
node --test --test-name-pattern='a blank task title' test/app.test.ts
Expect the original one-item list and one passing test. The source establishes the path through the handler. The test exercises a particular input and its observable effects.
Ask the question that leads to the spec
Again, on the Plan interface, give this request.
Compare POST /registrations and POST /tasks on the starter. What does
POST /registrations do when name is a number? Cite the conversion and
the state change. Leave the desired behavior open for the next task.
curl -sSi http://127.0.0.1:3100/registrations \
-H 'Content-Type: application/json' \
-d '{"name":42,"email":"ada@example.test"}'
On the fresh service, you should see 201 with {"id":"1","name":"42","email":"ada@example.test"}. Stop the server with Ctrl+C. Write notes/repo-map.md with the checkout, the entry point and dependency map, the task request trace, and the commands and observed responses. Separate what you read in the factory from what you saw over HTTP. Inspect the diff and commit just the map.
git add notes/repo-map.md
git diff --cached --check
git diff --cached --stat
git commit -m "Map the Task API starter"
Conclusion
After the exercises, you should be able to answer the original question. A task lives in memory between POST /tasks and GET /tasks. The starter’s factory allocates an array for tasks. Each request handler reads or writes that array. The array is lost when the service stops.
This is what we can do using the coding assistants to explore an unfamiliar codebase. Now we can continue to the next chapter, The Spec-First Workflow, where we will learn how to write a spec for a new feature and use it to guide our development.
References
- OpenCode maintainers. Agents and Permissions. OpenCode 2 documentation.
- Node.js contributors. HTTP and Test runner. Node.js API reference.