Make a code change

This is the everyday loop: you ask an agent for a change, you follow it in the terminal, and you end with a small diff you can review.

The goal is not to keep the agent busy. The goal is to get from intent to a scoped, 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 the change solves.
• 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 working directories. It does not sandbox commands, credentials, or network access. See run parallel agents.

Write the first prompt

A good first prompt gives the agent a job, a boundary, and a check.

Read the task and inspect the auth module. Fix the login redirect only. Keep changes to the files you name, and run the auth tests when done.

That prompt is not fancy. It tells the agent what to do, what not to do, and how to prove the change.

Ask for a plan before risky edits

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

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.

Follow the work in the terminal

The agent runs in a visible terminal pane. You do not need to read every line, but watch the moments where risk changes:

• The agent proposes a plan.
• It asks for permission to run a command.
• It starts editing files outside the expected area.
• A command fails.
• It says the work is done.

Interrupt early when the direction is wrong. A short correction before edits is cheaper than reviewing a wandering branch. Permission prompts, model choice, and slash commands still belong to the CLI agent you launched; Coldtea shows the terminal, it does not intercept it.

Let the agent implement in one small pass

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

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.

npm run lint
npm run types:check
npm test -- path/to/relevant.test.ts

If a check fails, capture the failure in the session log or the 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.