# Opencode for Go: practical agent-driven development guide

URL: https://agentvera.dev/en/blog/opencode-for-go/ · Published: 2026-11-01

Learn how to use opencode on Go projects: AGENTS.md setup, working loops, go test and vet, concurrency pitfalls, and running multiple agents.

**In short:**

- opencode reads AGENTS.md, so Go build, test, lint, and layout rules become agent defaults.
- Keep changes small, run go test and go vet after every step, and review diffs for goroutine and nil-interface issues.
- For parallel work, separate git worktrees and automatic code review prevent Go refactors from clobbering each other.

opencode is a terminal coding agent you start by running `opencode` in a project folder. For Go work, add an AGENTS.md file that records your build, test, vet, and layout rules. Then work in small steps: ask for a change, run `go test ./...` and `go vet ./...`, and review the diff before moving on. See [opencode](/en/agents/opencode/) for the agent itself.

## opencode’s strengths for idiomatic Go codebases

opencode operates on the actual source tree and can run the same commands you already use: `go build`, `go test`, `go vet`, and `gofmt`. Because Go projects tend to have strong conventions around packages, interfaces, and table-driven tests, a coding agent that reads project instructions from AGENTS.md can apply those rules consistently. The agent handles mechanical refactors such as renaming an interface or threading context.Context through a call chain without losing the shape of your tests. It also respects module boundaries: it can reason about `internal/` visibility and import paths, and it typically avoids suggesting package cycles when you ask for a design change.

## Prepare a concise AGENTS.md for the Go module

The single most useful thing you can do is write a concise AGENTS.md in the repository root. opencode reads it before acting, so it becomes the default specification for every task. Keep it specific to this codebase, not generic Go advice.

```
# AGENTS.md
Module: github.com/acme/checkout
Layout:
  cmd/ - main packages
  internal/ - private packages
  pkg/ - public libraries (avoid unless necessary)
Build: go build ./...
Test: go test ./...
Race: go test -race ./...
Vet: go vet ./...
Format: gofmt -w .
Rules:
- Prefer the standard library; justify third-party dependencies.
- All exported identifiers need doc comments.
- Functions that block on I/O take context.Context as the first argument.
- Use table-driven tests in the same package with t.Run for subtests.
- Return errors instead of panicking for normal failures.
- Goroutines must have clear ownership and cancellation via context.
```

That file gives the agent enough to start a task without asking you whether to run `go test ./...` or where main packages live. Update it whenever you change the module path or add a required lint step such as `staticcheck`.

## Keep a tight edit, test, and review cycle

Do not hand the agent a 50-line request. Plan the change, ask for a small slice, run the verification commands, then review the diff. opencode works best when each step is testable in isolation.

A typical loop looks like this:
1. State the goal and the files or packages affected.
2. Ask the agent to write or update tests along with the implementation.
3. Run `go test ./...`, `go vet ./...`, and `gofmt -l .` yourself.
4. Review the diff for interface changes, goroutine ownership, and error handling.
5. Commit the verified step and move to the next slice.

Example prompts that match this loop:
- Add a context-aware worker pool to internal/worker using sync.WaitGroup, with table tests that exercise cancellation and error aggregation.
- Define a smaller PaymentProvider interface in the consumer package, keep the existing gateway as the implementation, and update all tests without changing public behavior.
- Trace the hot path in internal/checkout and replace the hand-rolled retry loop with a context-aware helper; add tests for backoff and deadline exceeded.
- Convert the store package from package-level globals to an explicit Store struct with a constructor; update all callers and tests.
- Run gofmt and go vet, fix the reported issues, and add a doc comment for every newly exported identifier.

For longer sessions, the step-by-step guide at [How to use opencode: a step-by-step guide](/en/blog/how-to-use-opencode/) is a useful reference.

## Concurrency, interfaces, and other areas to watch

opencode handles several Go tasks well: generating table tests for existing functions, adding context propagation through a package, splitting a large package into internal subpackages, writing mocks for interfaces, and updating error wrapping with `fmt.Errorf` and `%w`. It is also good at enforced formatting and vet fixes.

Watch it closely in these specific areas:
- Nil interfaces versus nil concrete pointers. An error or interface can be non-nil even when the underlying pointer is nil; tests may pass incorrectly.
- Goroutine leaks. If the agent writes a worker pool or retry loop, confirm cancellation exits all paths and cleanup runs.
- Copying values that contain sync.Mutex or sync.WaitGroup. `go vet` can catch some of this, but not always after a refactor.
- Error comparisons. Prefer `errors.Is` and `errors.As` instead of `==` or type assertions; the agent may revert to simpler patterns.
- Importing internal packages from outside the allowed parent. The compiler will catch it, but you can save a round trip by checking import paths in the diff.
- Ignoring context cancellation in long-running operations. Always read from a context or use a helper like `errgroup` if it is already a dependency.

If the agent proposes a change in generated code such as protobuf or stringer output, inspect it manually or regenerate the code yourself.

## Run go test, race, and vet after each change

Make verification explicit in every prompt: ask the agent to run `go test ./...` and `go vet ./...` before reporting completion. Then run them again yourself. For concurrency-sensitive changes, add `go test -race ./...`; it is slower but catches data races that table tests may miss.

| Command | What it catches |
|---|---|
| `go test ./...` | package compilation and unit/table test failures |
| `go test -race ./...` | data races in goroutines and shared state |
| `go vet ./...` | unsafe or suspicious constructs, such as copying locks |
| `gofmt -l .` | formatting drift that should not enter the diff |

When the agent adds tests, look for table-driven style with subtests and a clear name per case. Avoid accepting tests that only assert the happy path; request at least one case for cancellation, one for an error, and one for a zero value. After a refactor, use `git diff --stat` and `git diff` to confirm that unrelated files did not change.

## Run parallel agents in separate worktrees with AgentVera

AgentVera is a desktop app that runs coding agents' real command line tools, including opencode, side by side in one window. For Go work, the most valuable parts are parallel git worktrees, automatic code review, checkpoints, and flows. Separate worktrees let agents refactor packages without overwriting each other’s files. Automatic review after each turn catches mistakes such as copied mutexes or leaked goroutines and links to file:line. Checkpoints make it safe to undo a bad interface change. Flows let one agent design a package API and the next implement and test it. The other AgentVera features are less relevant when you already have Go’s own test and vet loop.

## Practical wrap-up for Go teams

opencode is most useful on a Go project when you treat it as a fast junior engineer with strong knowledge of the standard library. Give it a specific AGENTS.md, keep tasks small, verify with `go test` and `go vet`, and review every diff. If you need more throughput, run several agents in separate worktrees with AgentVera. For a comparison with another popular CLI agent, see [opencode vs Claude Code: an honest comparison](/en/blog/opencode-vs-claude-code/).

## Frequently asked questions

**How do I start opencode in a Go project?** Run opencode in the project root. Before you do, add an AGENTS.md file with the module path, build/test/vet commands, and package layout rules; opencode will read it and apply those conventions.

**Does opencode run go test and go vet automatically?** Not automatically. You should ask it to run go test ./... and go vet ./... as part of the task, and also run them yourself after the agent reports completion. Reviewing the diff before committing is still your responsibility.

**Can opencode write correct goroutine and context code?** It can write idiomatic context-aware code and worker pools, but you need to request go test -race ./... and review for goroutine leaks. Watch for copied mutexes and missing cancellation paths.

**What should I put in AGENTS.md for opencode on a Go project?** Keep a short AGENTS.md at the repository root with the module path, folder conventions such as cmd/ and internal/, build, test, race, vet, and format commands, plus rules like table-driven tests and context in blocking functions.

---

**About AgentVera.** AgentVera is a desktop app for macOS, Windows and Linux, built by Solviera Teknoloji. It runs 18 AI coding agents (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) side by side, per project, in real terminals with the user's own CLI installs and logins. The free plan has unlimited agents. Download: https://agentvera.dev/en/download/ · Pricing: https://agentvera.dev/en/pricing/