Codex is a capable coding agent for Go when you treat it like a fast junior engineer: clear instructions, small diffs, and verification after every step. This guide covers project setup, AGENTS.md, prompt loops, common pitfalls, and testing workflows so you can use Codex on Go projects without fighting the language.
Go-friendly agent behavior
Go’s toolchain gives Codex fast, unambiguous feedback. A single command such as go test ./... compiles and tests the whole module, while gofmt -l . and go vet ./... give formatting and correctness signals that are easy for the agent to act on. Because Go has explicit interfaces, table-driven tests, and a small standard library, Codex can often produce idiomatic changes without external context. The module system also makes dependency boundaries visible: Codex can stay inside the project layout when you tell it which folders are off-limits. Codex’s ability to run commands and read compiler errors means many Go mistakes get caught before you review the diff, and gofmt removes formatting debates.
Project prep: AGENTS.md that keeps Codex on track
Codex reads project instructions from AGENTS.md. Keep the file short and operational: commands the agent should run, folder conventions, and rules that prevent common Go mistakes. A realistic AGENTS.md for a Go project looks like this:
# AGENTS.md
## Commands
- Build: `go build ./...`
- Test: `go test ./...`
- Lint: `go vet ./...` and `gofmt -l .`
- Generate: `go generate ./...`
## Folder conventions
- Library code that is not part of the public API lives in `/internal`.
- Generated code lives in `/gen`; do not edit it by hand.
- One package per directory; tests live next to the source.
## Go rules
- Always run `gofmt -w` on changed files before finishing.
- Do not add new dependencies without asking first.
- Prefer table-driven tests for new behavior.
- Keep `context.Context` as the first parameter in functions that accept it.
- Use `go test -race ./...` when touching goroutines or shared state.Do not turn AGENTS.md into a style guide. The agent needs to recall commands and constraints, not read a book. If the project uses make or a specific linter, put the exact invocation there. If your CI runs go test -race or staticcheck, include that command too, because Codex will use it before you merge.
A short feedback loop with prompts that work
Work in small steps and verify each one. A useful loop is: describe the desired change and its tests, let Codex edit the files, run go test ./..., go vet ./..., and gofmt -l . to check formatting, then review the diff. If the agent changes more than expected, reset or ask it to split the change. Review the diff with git diff --stat and git diff --check to catch whitespace and broad changes.
For CLI details outside this guide, How to use Codex CLI: a step-by-step guide covers the basics.
Example prompts for common Go tasks:
- Add a
GetUsermethod to theUserStoreinterface and implement it for the postgres and memory stores. Update the generated mocks and add a table-driven test for missing users. - Fix the timeout in
worker.goso it respects the caller context. Usectx.Done()andsync.WaitGroup, and add a test with a canceled context. - Refactor
main.goto move HTTP handlers intointernal/api. Keep public behavior unchanged and update all imports. - Run
go test ./...andgo vet ./..., then fix any failures you introduced. - Review the diff for error handling: wrap errors with
%w, do not usepanicin library code, and close response bodies where needed.
The important part is that each prompt names a file, package, or test target. Vague instructions such as improve the code produce broad diffs and more review work.
Good fits and Go-specific pitfalls
Codex is useful for interface updates, test generation, refactors, and concurrency fixes, but Go has specific failure modes.
| Task | Good prompt | Watch closely |
|---|---|---|
| Add an interface method | Add Update to Store and implement it for all current implementations. | Every implementation and mock must be updated; the compiler catches missing methods but not semantic drift. |
| Fix a goroutine leak | Make process exit when the context is canceled and wait for spawned goroutines. | Check ctx.Done(), sync.WaitGroup, channel closure, and run go test -race. |
| Move code between packages | Move handler from main to internal/api. | Import cycles, exported names, and whether the package remains testable. |
| Change a dependency | Upgrade golang.org/x/sync and adjust call sites. | Changes in go.mod and go.sum, license and API compatibility, and transitive dependency bloat. |
Go-specific pitfalls to watch: Codex may overuse interface{} / any when a concrete type or constrained generic would be clearer. It may wrap errors inconsistently or forget %w when you need callers to inspect the original error. It may add a dependency for something already in the standard library. It may introduce a data race by sharing a slice or map across goroutines. It may create an import cycle when refactoring packages. When Codex adds an interface, check that it does not over-abstract; an interface with one method and one implementation is often premature. Always ask the agent to run go test -race ./... and go vet ./... after touching concurrency or imports.
Verification beyond compile: race, vet, fmt
Use Go’s own test output as the acceptance signal. Prefer table-driven tests because they give Codex a clear pattern to follow and make failures pinpoint a specific case. After each change, run:
go test ./...
go test -race ./...
go vet ./...
gofmt -l .If Codex writes a test, review it for false confidence: a test that only checks err == nil or uses a fixed sleep is weak. Ask Codex to use contexts, timeouts, and table cases instead of sleeps. For HTTP handlers, ask Codex to use httptest; for time-dependent code, inject a clock or use timers with contexts rather than time.Sleep. For a second pass over Codex diffs, automated review can catch issues you would otherwise miss; the workflow is described in AI code review: check what your agents write.
Parallel agents on a Go codebase
AgentVera is a desktop app that runs Codex and other coding agents’ real command line tools in separate terminal panels. For Go projects, the most useful parts are parallel agents in their own git worktrees so they don’t overwrite each other’s files, automatic code review with file:line links when a turn ends, token budgets per agent/turn/day that stop runaway work without losing the conversation, and checkpoints that let you undo a bad refactor or replay a session step by step. This fits Go work because package boundaries make independent changes easy to split, and a second review pass catches interface or concurrency mistakes before they reach your branch.
Final thoughts
Codex works well on Go projects when you give it a tight AGENTS.md, small prompts tied to files or tests, and a verification loop built around go test, go vet, and gofmt. Watch it most closely around interfaces, goroutines, and module boundaries, and use AgentVera when you need several agents working in parallel without stepping on each other.