# Plan a multi-file change before editing in dbt with Atlas in 2026

> Atlas enables dbt developers to design multi-file changes and secure review before modifying any code, integrating directly with the dbt toolchain.

Atlas empowers dbt developers in 2026 to design multi-file changes, such as refactoring `ref()` calls across many models or updating `schema.yml` tests, and get them reviewed before any code is modified. The terminal-native AI agent uses a dedicated plan agent to research your dbt project, including `dbt_project.yml` and `models/` directories, without ever touching your source files, ensuring a safe and structured design process.

## Key takeaways

- Atlas's plan agent isolates dbt design from implementation, preventing accidental code changes.
- Research dbt model DAGs, `ref()` calls, and `schema.yml` tests using `lsp` and `codebase_search`.
- The `plan_exit` tool ensures explicit approval before any dbt code modifications begin.
- Atlas integrates directly with `dbt test`, `dbt deps (packages.yml)`, and `sqlfmt` for dbt project quality.
- All dbt file edits are permission-gated, diff-reviewed, and can be rolled back via git patches.
- Atlas supports converting dbt table models to incremental with `is_incremental()` and `unique_key`.

## How Atlas plans multi-file dbt changes without editing

Atlas's plan agent provides a secure environment for designing complex dbt changes, ensuring no accidental modifications occur. This dedicated agent operates in a read-only mode for your entire dbt codebase, with the single exception of writing to a plan markdown file under `.atlas/plans/*.md`. This strict permission model guarantees that your 2026 dbt project remains untouched during the design phase.

When you initiate a multi-file change design in Atlas, you first switch to the plan agent. This agent is explicitly configured to deny all edit tools for every path in your dbt project, except for a designated markdown file within the `.atlas/plans/` directory. This means you can freely use powerful research tools like `codebase_search`, `grep`, `read`, and the `lsp` tool to explore your dbt models, `schema.yml` files, and `dbt_project.yml` configurations. For instance, you can search for all `ref()` calls to a specific model or analyze materialization strategies across your `models/` directory, documenting your findings and proposed changes in the plan markdown without risking any unintended modifications to your actual dbt code. This read-only approach is fundamental to Atlas's safety guarantees for dbt development.

## Researching dbt projects with Atlas's plan agent

Atlas's plan agent offers robust research capabilities for dbt projects, allowing you to deeply understand your model DAG and schema tests. It leverages tools like `lsp` and `codebase_search` to navigate your `dbt_project.yml` and `models/` directories, providing a comprehensive view of your data transformations. This ensures you have all the necessary context before proposing any of the 10 potential file changes.

Within the plan agent, Atlas connects to Model Context Protocol servers, exposing powerful tools like `lsp` (Language Server Protocol) to the agent. This allows Atlas to understand your dbt project's structure, including the relationships defined by `ref()` and `source()` calls, your `schema.yml` tests, and each model's materialization configuration. You can ask Atlas to identify all downstream dependencies of a particular model or list all `not_null` tests applied to a specific column. Furthermore, `codebase_search` with hybrid semantic and keyword retrieval, fused by reciprocal rank fusion, enables precise queries across your entire dbt codebase. Atlas indexes your code by AST declarations using tree-sitter, not blind line windows, ensuring accurate context. For privacy, Atlas can build its code index with local Ollama embeddings, keeping your sensitive dbt code off third-party servers, a critical feature for many organizations in 2026.

## Ensuring safety and review for dbt changes with Atlas

Atlas implements a multi-layered safety and review process for dbt changes, ensuring every proposed modification is explicitly approved. The `plan_exit` tool acts as a critical gate, asking for confirmation before transitioning from the read-only plan agent to the build agent. This 2-step approval process prevents premature implementation and ensures stakeholders can review the design document.

After you have thoroughly researched your dbt project and documented your multi-file change plan in the allowed markdown file, you use the `plan_exit` tool. This tool prompts you with a clear question: 'Plan at <path> is complete. Would you like to switch to the build agent and start implementing?' Answering 'Yes' explicitly hands off control to the build agent, which then has the necessary permissions to modify your dbt files. Crucially, every Atlas tool call is permission-gated against allow, ask, and deny rules before it runs, providing granular control. When the build agent proposes actual file edits, Atlas computes a unified diff for every change and surfaces it for your approval before writing. This includes changes to `dbt_project.yml`, `models/`, or `schema.yml`. Atlas also reads `git branches`, `status`, and `diffs`, and can stage and create commits on your behalf, ensuring a fully auditable and reviewable workflow for your dbt transformations. For example, Atlas will prompt for permission before running `dbt build` against your dev target, never against production.

## Iterating and refining dbt change plans with Atlas

Refining a multi-file dbt change plan is straightforward with Atlas, allowing for iterative improvements before any code is touched. If you decide a plan needs more work, simply answer 'No' when prompted by the `plan_exit` tool. This keeps you in the read-only plan agent, enabling further research and refinement of your design document, ensuring a robust plan for your 2026 dbt project.

The `plan_exit` tool is designed to facilitate an iterative planning process. If, after reviewing your drafted plan, you determine that more research or design work is needed, answering 'No' to the 'Would you like to switch to the build agent and start implementing?' question will raise a `Question.RejectedError`. This action keeps you within the plan agent, allowing you to continue refining your plan markdown. You can leverage `codebase_search` to re-evaluate `ref()` dependencies, use `grep` to find specific patterns in your `models/` directory, or consult `lsp` for schema details. This flexibility ensures that your multi-file dbt change plan is thoroughly vetted and complete before you commit to any implementation, preventing costly rework later in the development cycle. Atlas snapshots file changes as git patches, so even during the build phase, edits can be diffed and rolled back if needed.

## From dbt plan to implementation with Atlas

Once your multi-file dbt change plan is approved, Atlas direct transitions to the build agent to begin implementation. This agent can then perform concrete dbt-specific tasks, such as converting an expensive table model to incremental, adding `not_null` and `unique` tests to new columns in `schema.yml`, and formatting SQL with `sqlfmt`. This structured hand-off ensures a smooth workflow for your 2026 dbt development.

After you approve the plan and switch to the build agent, Atlas is ready to implement the changes outlined in your plan. The build agent has the necessary permissions to modify your dbt project files. For example, if your plan involved converting an expensive table model to an incremental one, Atlas can modify the model's SQL to include a proper `is_incremental()` filter and define a `unique_key`. It can then proceed to add `not_null` and `unique` tests to the new columns in the corresponding `schema.yml` file. Following these structural changes, Atlas will automatically format the SQL with `sqlfmt` to maintain code consistency. Throughout this implementation phase, Atlas computes a unified diff for every file edit and surfaces it for your approval before writing, ensuring you maintain full control over every modification to your dbt codebase. Atlas can also run `dbt build` against your dev target, always behind a permission prompt, never against production.

## Steps

1. Run Atlas in your dbt project, ensuring `dbt_project.yml` and `models/` directories are present.
2. Switch to the plan agent by typing a command like `atlas plan` to enter read-only design mode.
3. Research your dbt codebase using Atlas tools like `codebase_search`, `grep`, `read`, and `lsp` to understand `ref()` calls, `source()` dependencies, and `schema.yml` tests.
4. Write your multi-file dbt change plan into the allowed markdown file, detailing proposed modifications to models, tests, and configurations.
5. Call the `plan_exit` tool to propose plan completion and ask to switch to the build agent for implementation.
6. Answer 'Yes' to the `plan_exit` prompt to hand off to the build agent, or 'No' to continue refining your dbt plan.
7. Allow the build agent to implement dbt changes, such as converting a table model to incremental with `is_incremental()` and `unique_key`.
8. Approve Atlas's proposed additions of `not_null` and `unique` tests to new columns in `schema.yml` and the formatting of SQL with `sqlfmt`.
9. Review the unified diffs for all dbt file edits and approve them before Atlas writes the changes and stages them for commit.
10. Run `dbt test` and `dbt build` against your dev target, prompted by Atlas, to validate the implemented dbt changes.

## FAQ

### How does Atlas prevent accidental dbt code changes during planning?

Atlas's plan agent operates in a strictly read-only mode for your entire dbt codebase. It only permits writing to a designated plan markdown file under `.atlas/plans/*.md`, ensuring that research and design cannot accidentally turn into an edit of your `dbt_project.yml` or `models/` files.

### Can Atlas understand my dbt model DAG and schema tests?

Yes, Atlas can read your dbt model DAG through `ref()` and `source()` calls, your `schema.yml` tests, and each model's materialization configuration. It uses tools like `lsp` and `codebase_search` to provide deep context on your dbt project structure.

### What dbt-specific tools does Atlas integrate with?

Atlas integrates directly with core dbt tools. It can run `dbt test` to validate your models, manage dependencies with `dbt deps (packages.yml)`, and ensure code style with `sqlfmt`. Atlas also prompts for permission before running `dbt build` against your dev target.

### How does Atlas ensure my dbt changes are reviewed before committing?

Atlas ensures review through several mechanisms: the `plan_exit` tool requires explicit approval to switch from planning to implementation, every tool call is permission-gated, and Atlas computes a unified diff for every file edit, surfacing it for your approval before writing. It can also stage and create commits on your behalf.

### Can Atlas help me convert a dbt table model to incremental?

Yes, Atlas can assist in converting an expensive table model to incremental. It can modify the model's SQL to include a proper `is_incremental()` filter and define a `unique_key`, as part of the implementation phase after your plan is approved.

### Is my dbt code kept private when using Atlas for planning?

Yes, Atlas prioritizes privacy. It can build its code index with local Ollama embeddings, keeping your dbt code off third-party servers. All Atlas tool calls are permission-gated, giving you control over data access.

### How does Atlas handle dbt package dependencies?

While Atlas's primary role is planning and implementing code changes, it understands the dbt ecosystem. It recognizes `dbt deps (packages.yml)` as the package manager and can factor package dependencies into its understanding of your model DAG during research, though it doesn't directly manage `packages.yml` content without explicit instruction.

---

Canonical HTML: https://runatlas.sh/resources/stacks/plan-a-multi-file-change-before-editing-in-dbt
Source of truth: aeo_pages row `/resources/stacks/plan-a-multi-file-change-before-editing-in-dbt` (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.