OpenCode Repo Checklist: Safer Coding-Agent Runs

OpenCode is useful when you want a coding agent close to your terminal and repository. That proximity is also the risk: the agent can inspect files, propose edits, run commands, and move faster than your review loop. Treat it like a sharp tool, not a teammate with production judgment.

This checklist gives you a repeatable way to run OpenCode on real code without turning every session into a mystery diff.

When OpenCode fits

Use OpenCode for bounded engineering tasks where success can be checked from the repo:

• Add a small feature behind an existing pattern.
• Refactor one module without changing behavior.
• Write or update tests for known code paths.
• Explain a failing test and propose a minimal fix.
• Draft a migration plan before touching files.

Avoid starting with broad prompts like “improve the app” or “clean this codebase.” Agent quality drops when scope is vague. Review quality also drops because nobody knows which changes belong.

Pre-flight checklist

Before you start an agent session, make the repo boring.

Run these first:

git status --short
git checkout -b agent/opencode-small-task
# Pick command already used by project:
npm test
# or
pytest

If tests are already failing, write that down before the agent starts. Otherwise you will not know whether OpenCode broke something or inherited existing damage.

Prompt shape that works

Good coding-agent prompts include five parts: goal, boundaries, context, verification, and output format.

Goal: Add server-side validation for project names.

Boundaries:
- Only edit src/projects/* and tests/projects/*.
- Do not change database schema.
- Keep public API response shape unchanged.

Context:
- Existing validation lives in src/projects/validation.ts.
- Tests use Vitest. Follow nearby test style.

Verification:
- Run npm test -- tests/projects.
- If tests cannot run, explain exact blocker.

Output:
- Summarize files changed.
- List test command and result.

This prompt does not ask OpenCode to be creative. It asks it to make one controlled change and leave evidence.

Configure before customizing

OpenCode documentation describes configuration, commands, and agents as first-class concepts. Use those mechanisms for repeatable repo behavior instead of retyping long instructions every session.

Practical examples:

1. Put project-specific rules in the documented configuration location for your setup.
2. Create reusable commands for common tasks such as “write tests for selected file” or “review this diff for risky changes.”
3. Define role-specific agent behavior only when the role has a clear job, such as reviewer, test-writer, or migration planner.

Keep configuration short. A bloated rule file becomes another prompt nobody audits. Good rules are specific:

- Prefer minimal diffs over broad rewrites.
- Never edit generated files directly.
- Always mention commands run and commands skipped.
- Ask for approval before deleting files or changing migrations.

During the run

Watch for three failure patterns.

1. Context drift. The agent starts in one area and edits another “while it is here.” Stop and split the task.

2. Test theater. The agent reports confidence but did not run the relevant command. Ask for exact command output, or run it yourself.

3. Large diff surprise. A simple task changes formatting across many files. Revert noise before review.

Use git as your seatbelt:

git diff --stat
git diff -- src/projects tests/projects
git restore path/to/unwanted-file

Small diffs are not automatically correct, but they are reviewable. That is the point.

Review checklist

After OpenCode finishes, review like you would review a junior engineer’s first PR: assume effort, verify behavior.

• Does the diff match requested scope?
• Are new tests meaningful, or do they only assert implementation details?
• Did the agent change public behavior without naming it?
• Are error paths, permissions, and input validation covered?
• Did it add dependencies, network calls, or generated files?
• Can you explain every changed line?

If answer to last question is no, do not merge. Ask for a smaller diff or revert and restart with tighter boundaries.

Merge rule

A safe OpenCode workflow ends with human ownership. The agent can draft code, run checks, and summarize decisions. You still own merge.

Minimum merge bar:

1. Clean diff with no unrelated files.
2. Relevant tests pass locally or in CI.
3. Reviewer understands behavioral change.
4. Rollback path is obvious.
5. Summary names limitations, not only successes.

OpenCode can speed up implementation. It should not speed up accountability. Keep sessions narrow, evidence visible, and final judgment human.