Make a code change

Use this workflow when an agent is going to create a diff you might keep.

The goal is not to make the agent busy. The goal is to get from intent to a small, reviewable change with the right checks attached.

Start from intent

Write down the work before you launch the brew. For task-linked work, the task should say:

• What problem should be solved.
• What outcome the user should see.
• What files or areas are likely in scope.
• What should stay out of scope.
• Which check should pass before review.

If you cannot describe the finish line, the agent cannot either.

Pick the working lane

Use the base project when the change is small and you are not running other implementation work in the same checkout.

Use a worktree when:

• Another agent is already working nearby.
• The change may touch several files.
• You want to compare two approaches.
• You need an easy way to discard the branch.

A worktree separates Git edits. It does not sandbox commands, credentials, or network access.

Ask for a plan before risky edits

For anything beyond a tiny copy fix, ask the agent to inspect first and propose a route.

Good plan prompts name the constraint:

Read the task and propose the smallest implementation plan. Name the files you expect to change and the checks you will run. Do not edit yet.

Read the plan before edits start. You are checking whether the agent understood the task, not whether the plan sounds polished.

Let the agent implement in one small pass

Once the plan is acceptable, ask for the smallest useful diff.

Keep the instruction direct:

Implement the plan. Keep changes scoped to the files you named. If you need to touch another area, stop and explain why first.

That stop condition matters. Most bad agent work starts with a reasonable task and then drifts into nearby cleanup.

Run the right checks

Use the checks that prove this change, not every command in the repo.

Examples:

npm run lint -w @coldtea/docs
npm run types:check -w @coldtea/docs
npm test -- path/to/relevant.test.ts

If a check fails, capture the failure in the session log or next prompt. Do not bury it in terminal scrollback.

Review before accepting

Before the change leaves the branch:

1. Read the task again.
2. Inspect the diff.
3. Confirm scope did not drift.
4. Read any plan and session log.
5. Check the command output.
6. Decide whether to keep, revise, or discard the branch.

A passing check does not prove the change solved the right problem. It only proves the command passed.

Next: review agent work for the detailed review path.