Skip to content
Hands-on Coding Assistants

Part 4 — Build the Harness Chapter 18

AGENTS.md & Project Context

In this chapter

In the exploration exercise you found the test command in package.json. You can save the next session that search by putting stable conventions in the repository. The agent can still open the file when it needs the details.

Check the instructions the workspace starts with

From a clean checkout, start an exercise branch at lab-start.

git switch -c project-instructions lab-start

Open AGENTS.md yourself. Compare its directions about the test command and route with package.json and src/app.ts. Then open a fresh Plan session from the root.

Using the guidance available at the start of this session, which
command checks the base repository after a change? Say which
instruction supports your answer. Leave files unchanged.

Look for npm test. The root file applies to work throughout the repository. In OpenCode 2, global and upward-discovered guidance are loaded at session startup. A personal global file may explain a difference between your results and a teammate’s.

See what changes when the agent enters a directory

Create contracts/AGENTS.md with this exercise rule.

When reporting on the registration contract, append a line beginning
with "Contract check" and include the command from package.json.

In a new Plan session, ask the same opening question. Then ask it to read contracts/registration.test.ts and explain which request checks preservation of the next ID. Inspect the read event. The directory guidance becomes available when a file there is read. The answer should now include the extra line and npm run test:registration.

Change the marker in the nested file and repeat in another fresh session. OpenCode can keep previously discovered nested guidance in a session’s history. A fresh session lets you test the current file. If the model omits the marker, check which path it read, and compare the text it received with your rule.

Review scope as well as wording. If a root rule seems to require npm test alone while a narrower file requires the feature contract too, specify that the contract is an additional check for its route. OpenCode combines guidance sources. You resolve conflicting instructions in the files. Keep the command from this exercise and the observed read in your notes. You’ll reuse the same distinction with configured instructions and tool permissions.

References