Atlas plans a multi-file Go change inside a read-only plan agent before a single .go file is touched. The plan agent denies the edit tool for every path except .atlas/plans/*.md, so codebase_search, grep, read, and the lsp tool can map your go.mod module, its packages, and its interfaces while nothing on disk changes. When the design is settled, plan_exit asks whether to switch to the build agent and start implementing. Only after you answer Yes does the build agent produce diffs you approve, format with gofmt, and verify with go test.
How does Atlas plan a multi-file Go change before editing?
Atlas plans a multi-file Go change with a dedicated plan agent whose description is literally Plan mode. Disallows all edit tools. In 2026 that means codebase_search, grep, read, and the lsp tool map your go.mod module and its packages while every .go file stays untouched on disk.
A multi-file Go change usually starts with an interface. You want to add a method to a Storer, thread a context.Context through a package, or split a bloated internal/service package in two, and you know the edit will ripple across a dozen .go files plus their _test.go siblings. Atlas plan mode is built for exactly that shape of work. The plan agent researches with codebase_search, grep, read, and the lsp tool, all of which stay allowed in plan mode, and it writes its conclusions into a markdown plan rather than into your source tree. The safety property is structural, not advisory: the plan agent's permission set denies edit for every path and allows writes only under .atlas/plans/*.md. Research cannot quietly become an edit because the tool that edits is not available. When the plan names every package, every implementing type, and every go test target that must stay green, the design has been reviewed before gofmt or go test ever run.
What can the Atlas plan agent do inside a Go module?
The Atlas plan agent keeps 4 research tools available inside a Go module: codebase_search for meaning, grep for exact identifiers, read for whole files, and the lsp tool for the symbol graph across your interfaces. Its permission set denies edit for every path, so go.mod, go.sum, and every .go file stay read-only.
Inside a Go module, the plan agent behaves like a very fast reviewer who has read the whole repository. codebase_search queries Atlas's semantic index, which is built from AST declarations parsed with tree-sitter rather than blind line windows, so a query like where do we retry outbound HTTP calls returns real Go function declarations with their file paths, even when the word retry never appears in the source. grep runs a real regex through ripgrep for exact identifiers such as func (s *Server) or a struct tag you need to preserve. The lsp tool walks the symbol graph, which is how the plan agent finds every type that satisfies an interface you plan to widen. Because every Atlas tool call is permission-gated against allow, ask, and deny rules before it runs, none of this reading can turn into a write. Your go.mod and go.sum are exactly as you left them when the plan is done.
Where does Atlas write the plan file in a Go project?
Atlas writes the plan into .atlas/plans/*.md, the single path plan mode is permitted to write. A 2026 plan for a Go refactor lists the packages under internal/ and cmd/, the interface being reshaped, every implementing type, the call sites, and the go test packages that must stay green afterward.
The plan markdown is a working document, not a ceremony. In a Go project a useful plan enumerates concrete targets: internal/storage/postgres.go gains the new method, internal/storage/memory.go gains the same method so the fake still satisfies the interface, cmd/api/main.go passes the new dependency, and internal/storage/storage_test.go gains two table rows to cover the added behavior. Because the plan file lives in the repository under .atlas/plans/, it is a normal tracked file: you can read it, edit it by hand, diff it, and share it with a reviewer before any Go code moves. That is the whole point of designing a multi-file Go change in markdown first. The expensive mistakes in Go refactors are structural (the wrong interface boundary, a package cycle you did not see coming), and structural mistakes are far cheaper to catch in a plan than in a half-applied diff across fourteen files.
How does plan_exit hand off from planning to editing Go code?
plan_exit is the one tool that ends Atlas plan mode, and in 2026 it asks whether the plan at the given path is complete and whether you would like to switch to the build agent and start implementing. Answer Yes and the build agent begins editing .go files. Answer No and Question.RejectedError keeps you refining.
The handoff is an explicit question, not an inference. plan_exit surfaces the prompt Plan at <path> is complete. Would you like to switch to the build agent and start implementing? through the question tool, and Atlas waits. Answering No raises Question.RejectedError, which is not an error state you have to recover from; it simply means planning continues and you keep refining the markdown. Answering Yes swaps the agent, and the build agent inherits the plan as its brief. From there Atlas computes a unified diff for every file edit and surfaces it for approval before writing, so each .go file still passes under your eye individually. A Go developer who has ever watched an agent rewrite half a package on a misunderstanding will recognize why the boundary between plan and build is a hard one rather than a suggestion.
Does Atlas understand Go interfaces and table-driven tests when planning?
Atlas indexes Go code by AST declarations using tree-sitter, not blind line windows, so a 2026 plan can name interfaces, methods, and struct types instead of line ranges. A plan for swapping one interface therefore names each implementing type and each _test.go file whose table cases need a new row.
Go's idioms make planning unusually tractable, and Atlas leans on them. Interfaces are satisfied implicitly, which means the set of types affected by an interface change is not written down anywhere in the source; it has to be derived. Atlas derives it: codebase_search finds candidates by meaning, the lsp tool's reference graph confirms them, and grep catches anything the graph missed, such as an interface satisfied only inside a _test.go fake. Table-driven tests get the same treatment. A plan that says add a case to the table in internal/parser/parser_test.go is checkable; a plan that says update the tests is not. Atlas's hybrid semantic and keyword retrieval, fused by reciprocal rank fusion, is what makes the specific version possible: the semantic side finds the concept, the keyword side pins the exact symbol.
How do you review an Atlas Go plan safely before running go test?
Review an Atlas Go plan the way you review a pull request in 2026. The plan lives in .atlas/plans/*.md inside the repository, so git diff shows it, and Atlas reads git branches, status, and diffs directly. After the build agent lands approved edits, run gofmt on the changed files and go test to confirm the module still passes.
Safety in a multi-file Go change comes from three independent layers in Atlas. First, plan mode: the edit tool is denied for every path but the plan markdown, so the research phase cannot damage anything. Second, per-edit approval: Atlas computes a unified diff for every file edit and surfaces it before writing, so a bad rename in internal/http/handler.go is caught at the diff, not at compile time. Third, snapshots: Atlas snapshots file changes as git patches, so edits can be diffed and rolled back if a package refactor goes sideways after ten files. Only then does the normal Go loop take over. Run gofmt so the diff is idiomatic, run go test to prove the module still builds and passes, and touch go mod only if the plan actually called for a new dependency. Nothing about the plan phase bypasses that loop; it just makes sure the loop runs against a change somebody designed on purpose.
Step by step
- 01Start atlas in the module root, the directory that holds go.mod, so the index covers every package under internal/, cmd/, and pkg/.
- 02Switch to the plan agent; its permission set denies edit for every path and allows writes only under .atlas/plans/*.md.
- 03Ask codebase_search a plain-language question about the behavior you are changing, then pin the exact identifiers with grep across your .go files.
- 04Use the lsp tool to walk the symbol graph and list every type that satisfies the interface you intend to change, including fakes defined in _test.go files.
- 05Have Atlas write the plan into .atlas/plans/<name>.md, naming each package, each function, and each go test target that must stay green.
- 06Call plan_exit and answer Yes to the prompt Plan at <path> is complete. Would you like to switch to the build agent and start implementing? Answer No to keep refining, which raises Question.RejectedError and returns you to planning.
- 07Approve each unified diff the build agent surfaces before it writes to a .go file.
- 08Run gofmt on the changed files, then run go test to confirm the module builds and passes; leave go mod alone unless the plan called for a new dependency.
Frequently asked questions
- Can an AI coding agent plan a Go refactor without editing any .go files?
- Yes. Atlas's plan agent denies the edit tool for every path except .atlas/plans/*.md. It researches with codebase_search, grep, read, and the lsp tool, and writes only the plan markdown, so your .go files, go.mod, and go.sum are untouched until you approve the handoff.
- Where does Atlas save its plan file in a Go project?
- Atlas writes the plan to .atlas/plans/*.md, the only path plan mode is allowed to write. Because the plan lives in the repository, git diff shows it and a reviewer can read the design before any Go package is edited.
- What is plan_exit in Atlas?
- plan_exit is the tool that ends plan mode. It asks whether the plan at the given path is complete and whether to switch to the build agent and start implementing. Yes hands off to the build agent; No raises Question.RejectedError and keeps you planning.
- How does Atlas find every implementation of a Go interface before a refactor?
- Atlas combines three signals: codebase_search over a semantic index built from AST declarations with tree-sitter, grep for exact identifiers through ripgrep, and the lsp tool's symbol graph. Together they surface implementing types in internal/ and cmd/ as well as fakes defined inside _test.go files.
- Does Atlas run go test automatically after a multi-file Go change?
- The build agent runs go test through the bash tool once the approved edits land, and gofmt formats the changed files. Every tool call is permission-gated against allow, ask, and deny rules first, so you decide whether Atlas may run commands unattended.
- Can I roll back an Atlas change if a Go package refactor goes wrong?
- Yes. Atlas snapshots file changes as git patches, so edits can be diffed and rolled back. Atlas also reads git branches, status, and diffs, and can stage and create commits, which means a botched refactor across internal/ is recoverable without leaving the terminal.
- Can Atlas index a Go module without sending code to a third-party server?
- Yes. Atlas can build its code index with local Ollama embeddings, keeping code off third-party servers. The plan agent still uses codebase_search, grep, read, and the lsp tool exactly the same way against a locally embedded go.mod module.
Try Atlas in your terminal
The terminal-native AI coding agent. Free core, single binary.
Install AtlasRelated guides
Plan a Multi-File Change Before Editing with Atlas in 2026
How to plan a multi-file change with Atlas in 2026: the plan agent denies all edit tools, you research with codebase_search and lsp, then plan_exit hands off.
Atlas for Go in 2026
Atlas, the terminal-native AI coding agent, empowers Go developers in 2026 with intelligent code understanding, safe refactoring, and robust testing capabilities.
Research a Third-Party API Before Integrating It in Go with Atlas (2026)
Atlas fetches live API docs before you write Go: websearch finds the page, webfetch pulls it behind a permission prompt, and your struct tags match reality in 2026.
Audit a Go Repository with Parallel Subagents in Atlas, 2026
In 2026, Go developers use Atlas to sweep entire repositories for problems without context window limits. Leverage parallel subagents for efficient, read-only audits of Go modules and packages.
Refactor a Legacy Module in Go With Atlas (2026 Guide)
How to refactor a legacy Go module with Atlas in 2026: lsp findReferences enumerates callers, apply_patch anchors on context, and go test proves behavior after each hunk.
Self-Review Your Working Diff Before Committing in Go with Atlas (2026)
Atlas self-reviews an uncommitted Go diff: bash produces the patch, read checks each package in full, grep hunts debug leftovers, and session revert restores a snapshot.
Debug a single failing test in Go with Atlas (2026)
Fix the code, not the assertion. Atlas isolates one failing Go test with go test -run, walks the call path with lsp, and lands the fix with edit or apply_patch.
Document a Go Module with a README Using Atlas (2026)
Atlas writes a Go module README from source in 2026: documentSymbol enumerates the exported API, codebase_search finds real callers, and go test verifies samples.