# Plan a Multi-File Change Before Editing in Gin with Atlas in 2026 > Atlas's plan agent allows Gin developers to design multi-file changes and secure review before modifying any Go code, integrating with go test (httptest) for validation. Atlas empowers Gin developers in 2026 to design multi-file changes comprehensively before any code modification, leveraging its dedicated plan agent to research your codebase with tools like codebase_search and lsp, document the strategy, and secure approval, all while integrating direct with go test (httptest) and gofmt for a robust workflow. ## Key takeaways - Atlas's plan agent provides a read-only environment for designing multi-file Gin changes. - Research Gin code effectively using `codebase_search`, `grep`, `read`, and `lsp` in plan mode. - Document your Gin change strategy in a dedicated `.atlas/plans/*.md` file before coding. - Atlas ensures safety with permission-gated tool calls and unified diffs for all Gin code edits. - Validate Gin changes using real toolchain commands like `go test (httptest)` and `gofmt` with Atlas. ## How to design multi-file Gin changes with Atlas's plan agent In 2026, Atlas's dedicated plan agent provides a read-only environment for designing multi-file Gin changes, ensuring no accidental modifications occur. This agent's permissions explicitly deny all edit tools except for writing to a single markdown plan file, offering a secure space for complex architectural design. Atlas's plan agent is specifically engineered to facilitate the design phase of multi-file changes within a Gin codebase. When you initiate Atlas in plan mode, its permission set is strictly configured to disallow any modifications to your project files, enforcing a read-only state across your entire Go module. The sole exception is the ability to write to a designated markdown file within the `.atlas/plans/` directory. This ensures that all research and design activities remain purely conceptual, preventing premature or unintended alterations to your Gin handlers, middleware, or request types. This focused environment allows developers to thoroughly map out changes involving multiple `gin.HandlerFunc` implementations or widespread updates to `struct` binding tags without the risk of introducing half-baked code. ## Researching Gin codebases for multi-file changes To effectively plan multi-file Gin changes, Atlas provides powerful research tools that operate safely within the plan agent, allowing you to explore your codebase in 2026. These tools, including codebase_search and lsp, index your Go code by AST declarations, offering precise insights without modifying a single line. Within the read-only plan agent, Atlas provides a suite of tools essential for deep research into your Gin application. The `codebase_search` tool, powered by hybrid semantic and keyword retrieval, allows you to quickly locate relevant `gin.HandlerFunc` definitions, router groups, or specific `struct` binding tags across your project. For instance, you can search for all instances where `c.ShouldBindJSON` is used or where a particular middleware is applied. The `lsp` tool provides language server protocol capabilities, enabling you to inspect type definitions, function signatures, and references for Gin-specific constructs, such as `gin.Context` methods or custom validators. Additionally, `grep` and `read` tools offer traditional text-based searching and file content inspection. All these research tools are fully permitted in plan mode, ensuring you have comprehensive understanding of your Gin codebase before committing to a design. ## Documenting your Gin change plan in Atlas Documenting your multi-file Gin change plan is a core step in Atlas's workflow, with the plan agent allowing writes only to a markdown file in 2026. This dedicated .atlas/plans/*.md path serves as the single approved location for outlining your design, ensuring all proposed modifications are clearly articulated before implementation begins. Once research is complete, the next critical step is to document your proposed multi-file change. Atlas's plan agent provides a secure mechanism for this by allowing writes exclusively to markdown files located under the `.atlas/plans/` directory. For example, you might create `.atlas/plans/refactor_user_auth.md` to detail changes affecting multiple authentication handlers and middleware. This markdown file becomes the central artifact of your design phase, where you can describe the new `gin.HandlerFunc` signatures, outline modifications to `go mod` dependencies, or specify how existing `httptest` cases will be adapted. This controlled writing environment ensures that your design is fully articulated and reviewed as a plan document, rather than as speculative code changes, maintaining a clear separation between design and implementation. ## Reviewing and approving Gin changes with Atlas's safety features Atlas ensures robust review and safety for Gin changes in 2026 by requiring explicit approval at multiple stages, including a unified diff for every file edit. Before any code is written, the plan_exit tool prompts for a transition to the build agent, and subsequent tool calls are permission-gated, safeguarding your Gin application. Atlas integrates several layers of safety and review into its workflow for Gin projects. After documenting your plan, calling the `plan_exit` tool initiates a crucial prompt: "Plan at is complete. Would you like to switch to the build agent and start implementing?" Answering 'Yes' transitions Atlas from the read-only plan agent to the build agent, which has permissions to modify files. Crucially, every single file edit proposed by Atlas, whether it's modifying a `gin.HandlerFunc`, updating `go.mod`, or adjusting `struct` tags, is presented as a unified diff for your explicit approval. Furthermore, Atlas's tool calls, such as running `go test ./... -race` with `httptest` cases or applying `gofmt`, are permission-gated, requiring your consent before execution. This granular control ensures that you maintain full oversight over every change, from the initial design to the final commit, preventing unintended modifications and ensuring the integrity of your Gin codebase. ## Steps 1. Start Atlas in plan mode for your Gin project: Run `atlas` in your Go module root, ensuring `go.mod` requires `github.com/gin-gonic/gin`. Atlas will automatically enter plan mode, restricting edits to `.atlas/plans/*.md`. 2. Research your Gin codebase with Atlas's tools: Use `atlas codebase_search "gin.HandlerFunc"` to find relevant handlers, `atlas lsp definition "MyGinMiddleware"` to inspect middleware, or `atlas grep "c.ShouldBindJSON"` to locate binding logic. 3. Document your multi-file Gin change plan: Write your detailed design into a markdown file, for example, `atlas write .atlas/plans/new_api_endpoint.md`, outlining changes to router groups, `struct` tags, and `httptest` cases. 4. Initiate the transition to implementation: Call `atlas plan_exit` to signal plan completion. Atlas will ask, "Plan at .atlas/plans/new_api_endpoint.md is complete. Would you like to switch to the build agent and start implementing?" 5. Approve the switch to the build agent: Answer 'Yes' to the `plan_exit` prompt. Atlas will transition to the build agent, enabling file modification permissions for your Gin project. 6. Let Atlas implement the Gin changes: Guide Atlas to apply your plan, for instance, by asking it to "replace manual body decode with `ShouldBindJSON` and proper 400 handling" in a specific Gin handler. 7. Approve `httptest` cases and run `go test`: When Atlas drafts new `httptest` cases or modifies existing ones, review the diff. Then, approve Atlas to run `go test ./... -race` to validate the changes against your Gin engine. 8. Approve `gofmt` and `go vet` execution: After code modifications, Atlas will propose running `gofmt` for formatting and `go vet` for static analysis. Review the diffs and approve these standard Go toolchain commands. 9. Review and commit the final Gin changes: Atlas will present a unified diff of all proposed file changes. Review thoroughly, approve the diff, and then let Atlas stage and create a commit on your behalf. ## FAQ ### How does Atlas prevent accidental edits in Gin during planning? Atlas's plan agent operates in a strictly read-only mode for your Gin codebase. Its permissions deny all edit tools for every path except for writing to markdown files within the `.atlas/plans/` directory, ensuring no accidental modifications occur during the design phase. ### Can Atlas understand Gin's `gin.HandlerFunc` and binding tags? Yes, Atlas indexes code by AST declarations using tree-sitter, allowing it to understand Gin-specific constructs like `gin.HandlerFunc` middleware, router groups, and the binding and `json` struct tags on your request types. ### What Gin testing tools does Atlas integrate with? Atlas integrates directly with the standard Go testing toolchain. It can write `httptest` cases against your Gin engine and run `go test ./... -race` behind a permission prompt, ensuring your Gin application's tests are executed and validated. ### How does Atlas ensure code quality for Gin changes? Atlas ensures code quality by integrating `gofmt` for consistent formatting and `go vet` for static analysis. It presents the diffs from these tools for your approval before applying them, maintaining high standards for your Gin codebase. ### Can I use Atlas to refactor Gin middleware chains? Yes, Atlas can assist in refactoring Gin middleware chains. You can use its research tools to identify existing middleware, plan the new structure in a markdown file, and then guide the build agent to implement the changes, such as modifying `router.Use()` calls. ### How does Atlas handle `go mod` dependencies for Gin projects? Atlas understands and interacts with `go mod` for dependency management in Gin projects. It can read your `go.mod` file and, with your approval, propose updates or additions to module requirements as part of a multi-file change, ensuring your dependencies are correctly managed. ### What happens if I reject a proposed change by Atlas in Gin? If you reject a proposed change, such as a file edit or a tool execution like `go test`, Atlas will not apply it. You can then refine your instructions or the plan, ensuring that only approved and correct modifications are made to your Gin codebase. ### Does Atlas keep my Gin code off third-party servers? Yes, Atlas can build its code index with local Ollama embeddings, keeping your Gin code off third-party servers. This ensures that your proprietary Gin application code remains secure and private on your local machine. --- Canonical HTML: https://runatlas.sh/resources/stacks/plan-a-multi-file-change-before-editing-in-gin Source of truth: aeo_pages row `/resources/stacks/plan-a-multi-file-change-before-editing-in-gin` (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.