> ## Documentation Index
> Fetch the complete documentation index at: https://chatcli.edilsonfreitas.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Recipe: Safe Refactoring with Agent Mode

> Use the power of Agent Mode to plan and execute a code refactoring step by step, with safety and full control.

Refactoring code, such as renaming an important variable across multiple files, can be risky. A single mistake can break the application. This recipe shows how to delegate this task to **Agent Mode**, using its planning and controlled execution capabilities to perform the refactoring safely.

## The Problem

You need to rename a configuration variable, for example from `DATABASE_URL` to `POSTGRES_DSN`, across your entire project. Doing this manually is tedious and error-prone. Using `sed` or mass `find-and-replace` can be dangerous if the variable name is a common substring.

## Ingredients

* A code project where you need to perform the refactoring.
* ChatCLI in interactive mode.

***

## Step by Step

<Steps>
  <Step title="Delegate the Task to the Agent">
    Start Agent Mode with a clear and detailed instruction. Be specific about what needs to be done.

    ```bash theme={"system"}
    /agent across the entire project, find all files that contain the string "DATABASE_URL" and replace it with "POSTGRES_DSN". Show me the files that will be modified before making any changes.
    ```

    <Info>
      **Deconstructing the Prompt:**

      * **"across the entire project..."**: Defines the scope of the operation.
      * **"find... and replace..."**: Describes the refactoring action.
      * **"Show me the files... before making any changes"**: This is a crucial safety instruction. We are asking the agent to create a plan that allows us to validate the scope before executing the change.
    </Info>
  </Step>

  <Step title="Review the Action Plan">
    The AI will analyze your request and propose a plan. A good plan for this task will likely have two steps:

    ```text theme={"system"}
    PLAN (compact view)
      #1: List affected files -- grep -rl "DATABASE_URL" .
      #2: Execute the replacement -- find . -type f -name "*" -exec sed -i 's/DATABASE_URL/POSTGRES_DSN/g' {} +
    ```

    <Warning>
      **Attention:** The `sed -i` command modifies files in place. Although the plan is logical, the second step is destructive. This is where Agent Mode's control becomes vital.
    </Warning>
  </Step>

  <Step title="Execute and Validate the First Step">
    Instead of running everything at once, let's execute only the first command to validate the scope.

    At the agent prompt, type `1` and press Enter.

    ChatCLI will run `grep -rl "DATABASE_URL" .` and display the list of files containing the string.

    **Example Output:**

    ```text theme={"system"}
    LAST RESULT
      ./config/app.go
      ./internal/database/connection.go
      ./docker-compose.yml
    ```

    <Note>
      Now you can review this list. If it contains an unexpected file (e.g., `README.md`), you know the approach needs to be refined.
    </Note>
  </Step>

  <Step title="Edit the Plan for Greater Safety (Optional but recommended)">
    The `sed` command is powerful but can be risky. Let's edit command 2 to use a backup extension, creating copies of the original files.

    At the agent prompt, type `e2` (edit command 2). ChatCLI will ask for the new command.

    ```text theme={"system"}
    Command 2/2 (shell): find . -type f -name "*" -exec sed -i'.bak' 's/DATABASE_URL/POSTGRES_DSN/g' {} +
    ```

    Now, the `sed` command will create a `.bak` file for each modified file, allowing easy rollback if something goes wrong.
  </Step>

  <Step title="Execute the Refactoring and Wrap Up">
    With the plan validated and improved, execute the second command by typing `2`.

    The agent will perform the replacement. After completion, you can verify the changes with `git diff` and, if everything looks correct, remove the backup files. You can even ask the agent to do this:

    ```text theme={"system"}
    Your choice: c2  (Continue after executing step 2)
    ```

    > The refactoring was completed successfully. Now, please create a command to find and remove all .bak files in the project.

    <Tip>
      **Result:** You performed a refactoring across the entire codebase in an interactive and safe manner. Agent Mode acted as a pair programmer, allowing you to validate each critical step before execution.
    </Tip>
  </Step>
</Steps>