# Plan a Multi-File Change Before Editing in Go with Atlas (2026) > In Go, Atlas drafts the change inside a plan agent that denies edit for every path except .atlas/plans/*.md, so no .go file is modified before the plan is approved. 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. ## Key takeaways - Atlas plan mode denies the edit tool for every path except .atlas/plans/*.md, so no .go file changes while you design. - codebase_search, grep, read, and the lsp tool all stay allowed in plan mode, which is enough to map a go.mod module end to end. - plan_exit is an explicit handoff: answering No raises Question.RejectedError and keeps you refining the plan. - Atlas indexes Go code by AST declarations using tree-sitter, so a plan names interfaces and methods rather than line ranges. - gofmt and go test run after the build agent lands the diffs you approved, not before. ## 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 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. ## Steps 1. Start atlas in the module root, the directory that holds go.mod, so the index covers every package under internal/, cmd/, and pkg/. 2. Switch to the plan agent; its permission set denies edit for every path and allows writes only under .atlas/plans/*.md. 3. Ask codebase_search a plain-language question about the behavior you are changing, then pin the exact identifiers with grep across your .go files. 4. Use 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. 5. Have Atlas write the plan into .atlas/plans/.md, naming each package, each function, and each go test target that must stay green. 6. Call plan_exit and answer Yes to the prompt Plan at 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. 7. Approve each unified diff the build agent surfaces before it writes to a .go file. 8. Run 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. ## FAQ ### 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. --- Canonical HTML: https://runatlas.sh/resources/stacks/plan-a-multi-file-change-before-editing-in-go Source of truth: aeo_pages row `/resources/stacks/plan-a-multi-file-change-before-editing-in-go` (segment: Stacks) (this file is generated from it, never hand-edited). Licence: Atlas is proprietary with a free core. It is not open source and there is no public source repository.