# Refactor a legacy module in Clojure with Atlas in 2026 > Atlas helps Clojure developers in 2026 refactor legacy modules by mapping public surfaces, pinning behavior with `kaocha` tests, and applying changes with `apply_patch`. To restructure an old Clojure module without changing its behavior or breaking its callers, Atlas leverages your existing `deps.edn` project setup, `kaocha` for robust testing, and `cljfmt` for consistent formatting. Atlas maps the module's public surface, pins behavior with tests, and applies structural changes iteratively, ensuring safety and adherence to Clojure idioms. ## Key takeaways - Atlas uses `lsp` to map Clojure module public surfaces and `findReferences` to enumerate all callers. - Behavior is pinned by running `clojure -M:test` with `kaocha` via Atlas's `bash` tool. - Structural changes are applied safely with `apply_patch`, which validates against file drift. - Atlas integrates `cljfmt` to ensure consistent Clojure code formatting in all edits. - Iterative testing with `kaocha` after each change prevents regressions during refactoring. - The `todowrite` tool tracks remaining Clojure callsites, ensuring complete migration. ## How to map a Clojure module's public surface and callers with Atlas Mapping a Clojure module's public surface and its callers is the critical first step in any refactoring, ensuring no silent breakages. Atlas uses its `lsp` tool to perform `documentSymbol` operations on your Clojure files, identifying all 2026-era exported symbols. It then finds references for each, providing a comprehensive list of every callsite. Atlas begins by understanding the module's external contract. For a Clojure namespace like `my-project.legacy-module`, Atlas invokes its `lsp` tool to run `documentSymbol`, which parses the AST (Abstract Syntax Tree) using tree-sitter to identify all `deftype`, `defrecord`, `defn`, `def`, and other top-level declarations. This provides a precise list of public functions and data structures. Next, for each identified symbol, Atlas executes `findReferences` through the `lsp` tool. This operation enumerates every location in your codebase where these symbols are invoked, whether in `my-project.core` or `my-project.another-module`. This exhaustive enumeration of callsites is then tracked in a `todowrite` list, ensuring that every dependency is accounted for before any code modification begins, preventing unexpected runtime errors. ## How to pin Clojure module behavior with Kaocha tests before refactoring Pinning the existing behavior of a Clojure module is paramount before any refactoring, providing a green baseline to validate changes. Atlas achieves this by running your `kaocha` tests via the `bash` tool, recording the initial successful state. This ensures that any subsequent structural changes do not inadvertently alter the module's functionality, a crucial step in 2026 development practices. Before Atlas proposes any code changes, it establishes a behavioral baseline. In a Clojure project, this means executing your existing test suite. Atlas uses its `bash` tool to run the command `clojure -M:test`, which invokes `kaocha`, your project's test runner, as defined in your `deps.edn` file's `:aliases`. For example, if your tests reside in `test/my_project/legacy_module_test.clj`, `kaocha` will discover and execute them. Atlas captures the output, confirming that all tests pass. This 'green baseline' is a non-negotiable checkpoint. If the tests are insufficient, Atlas can assist in adding `deftest` cases under the `test/` directory, or threading a pipeline with `->>` to improve coverage, always presenting a diff for your review before committing any new test code. ## How Atlas applies structural changes to Clojure code with apply_patch Applying structural changes to Clojure code during a refactor requires precision to avoid file drift and merge conflicts. Atlas uses its `apply_patch` tool, which anchors on context lines and old lines, refusing to apply if the file has changed. This ensures that every modification, whether moving a `defn` or renaming a `defrecord`, is applied against the exact expected file state in 2026. Once the public surface is mapped and behavior is pinned, Atlas proceeds with structural changes. For instance, if you're moving a `defn` from `my-project.legacy-module` to `my-project.new-module`, Atlas generates a unified diff. This diff is then applied using the `apply_patch` tool. A key safety feature of `apply_patch` is its reliance on context lines and `old_lines`. If the target file has drifted,meaning its content no longer matches the `old_lines` specified in the patch,`apply_patch` will fail with a 'Failed to find context' error. This prevents applying changes to an outdated version of the file, which could introduce subtle bugs. Atlas computes a unified diff for every proposed file edit and surfaces it for your approval before writing, allowing you to review the exact changes to your Clojure source files, such as `src/my_project/legacy_module.clj`. ## How Atlas ensures Clojure code quality and safety during refactoring Ensuring Clojure code quality and safety during refactoring is paramount, especially when dealing with legacy modules. Atlas integrates `cljfmt` for consistent formatting and re-runs `kaocha` tests after each change, providing immediate feedback. Every Atlas tool call is permission-gated, and all file edits are presented as unified diffs for approval, offering multiple layers of safety in 2026. Atlas employs several mechanisms to guarantee code quality and safety throughout the refactoring process. After each hunk of changes lands via `apply_patch`, Atlas immediately re-runs the `clojure -M:test` command with `kaocha`. This iterative testing approach, rather than a single run at the end, provides rapid feedback, allowing you to catch and address regressions as soon as they occur. Furthermore, Atlas integrates `cljfmt`, your Clojure formatter, to ensure that all generated or modified code adheres to your project's indentation and style conventions. Atlas applies `cljfmt` so the diff keeps your indentation conventions, making reviews cleaner. All Atlas tool calls, including `lsp`, `bash`, and `apply_patch`, are permission-gated against allow, ask, and deny rules, giving you explicit control. Atlas also drafts a plan in a read-only plan agent and asks for approval before switching to a build agent, and it computes a unified diff for every file edit, surfacing it for approval before writing to disk. This multi-stage approval process, combined with git patch snapshots for easy rollback, provides robust safety for your Clojure codebase. ## How Atlas tracks remaining Clojure callsites and manages refactoring progress Tracking remaining Clojure callsites is crucial to prevent a partially migrated module from being mistaken for a finished one. Atlas uses its `todowrite` tool to maintain a clear list of outstanding migrations, ensuring every reference to the legacy module is updated. This systematic approach helps manage the complexity of large refactors, providing a transparent view of progress in 2026. As the refactoring progresses, Atlas systematically updates the callsites identified in the initial mapping phase. For each callsite that is successfully migrated,for example, updating a `require` statement in `my-project.consumer-module` from `my-project.legacy-module` to `my-project.new-module`,Atlas removes it from the `todowrite` list. This list serves as a dynamic checklist, providing a real-time view of the remaining work. If a refactor involves multiple files or namespaces, Atlas can fan out work to subagents that can run in parallel background sessions, accelerating the migration of numerous callsites simultaneously. The `todowrite` list ensures that the refactoring is truly complete only when all references to the old module are gone, preventing the deployment of an incomplete or broken module. Atlas also reads git branches, status, and diffs, and can stage and create commits on your behalf, making the entire refactoring workflow integrated with your version control system. ## Steps 1. Run Atlas in your Clojure project directory, ensuring a `deps.edn` file is present for Atlas to read your namespace requires, `:aliases`, and any Integrant or Component system map. 2. Use Atlas's `lsp` tool to `documentSymbol` on your legacy Clojure module (e.g., `src/my_project/legacy_module.clj`), then `findReferences` on each exported symbol to enumerate all callsites, tracking them with `todowrite`. 3. Pin the module's current behavior by having Atlas run `clojure -M:test` with `kaocha` via the `bash` tool, recording a green baseline. If needed, ask Atlas to add `deftest` cases under `test/` and review the diff. 4. Instruct Atlas to restructure the module using `apply_patch`. Atlas will propose changes (e.g., moving a `defn` or renaming a `defrecord`), generating a unified diff for your approval. 5. After each `apply_patch` hunk lands, have Atlas re-run `clojure -M:test` with `kaocha` via `bash` to immediately verify that behavior remains unchanged. Atlas will prompt for permission before committing. 6. Let Atlas apply `cljfmt` to maintain your Clojure project's indentation conventions, ensuring the diffs remain clean and readable during review. 7. Continue iterating, updating remaining callsites tracked in `todowrite` and re-running `kaocha` tests, until the legacy module is fully refactored and all references are migrated. ## FAQ ### How does Atlas ensure my Clojure refactor doesn't break existing code? Atlas ensures safety by first mapping all callsites with `lsp`'s `findReferences`. It then pins behavior by running your `kaocha` tests via `clojure -M:test` before any changes. All edits are applied with `apply_patch`, which fails if the file has drifted, and every change is presented as a unified diff for your approval. ### Can Atlas help me add new tests to my Clojure module before refactoring? Yes, Atlas can assist in improving test coverage. You can ask Atlas to thread a pipeline with `->>` or add new `deftest` cases under your `test/` directory. Atlas will then present the proposed test code as a diff for your review before committing, ensuring your test suite is robust before refactoring begins. ### What Clojure tools does Atlas integrate with for refactoring? Atlas integrates directly with your standard Clojure toolchain. It uses `deps.edn` for project configuration, `kaocha` as the test runner (via `clojure -M:test`), and `cljfmt` for code formatting. Atlas leverages these tools through its `bash` and `lsp` capabilities to perform refactoring tasks. ### How does Atlas handle code formatting during a Clojure refactor? Atlas ensures your Clojure code remains consistently formatted by integrating `cljfmt`. After making structural changes, Atlas will apply `cljfmt` to the modified files. This means that the unified diffs you review will already reflect your project's established formatting conventions, preventing style-related noise in your code reviews. ### Is it safe to let Atlas modify my Clojure source files directly? Atlas operates with multiple layers of safety. Every tool call is permission-gated, and Atlas drafts a plan in a read-only agent for your approval before executing. All file edits are presented as unified diffs for your explicit approval before writing. Additionally, Atlas snapshots file changes as git patches, allowing for easy diffing and rollback if needed. ### How does Atlas track the progress of a large Clojure module refactor? Atlas tracks refactoring progress using its `todowrite` tool. After initially identifying all callsites to the legacy module, Atlas maintains a list of these references. As each callsite is successfully migrated and updated, it is removed from the `todowrite` list, providing a clear, real-time view of the remaining work and preventing incomplete migrations. --- Canonical HTML: https://runatlas.sh/resources/stacks/refactor-a-legacy-module-in-clojure Source of truth: aeo_pages row `/resources/stacks/refactor-a-legacy-module-in-clojure` (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.