> ## 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: Understanding a Code Project

> Use a combination of @file modes to quickly understand the architecture and flow of an unfamiliar codebase.

Joining a new project can be challenging. Where are the main files? What is the architecture? How does the authentication flow work? This recipe shows how to use **ChatCLI** to drastically accelerate your onboarding process.

## The Problem

You cloned a repository with hundreds of files and need to become productive as quickly as possible. Reading everything is impractical, and the documentation may be outdated.

## Ingredients

* A code repository cloned to your local machine.

***

## Step by Step

This workflow uses a "top-down" approach: first we get an architecture overview and then we dive into specific details.

<Steps>
  <Step title="The Panoramic View with @file --mode=summary">
    The first step is to get a map of the territory. The `summary` mode is perfect for this, as it lists the file and directory structure without sending the code content.

    ```bash theme={"system"}
    @file --mode=summary . > Describe the overall architecture of this project based on the file structure. Which components appear to be the most important?
    ```

    **What to expect from the AI:**

    The AI will return a high-level analysis, such as:

    ```text theme={"system"}
    This appears to be a Go backend project.
    The /cmd directory suggests there are multiple binaries.

    The /internal/api folder likely contains the HTTP route handlers,
    while /internal/database manages the database access logic.

    The docker-compose.yml file indicates the project uses Docker for
    the development environment.
    ```

    With this, you already have a mental map of where to look for things.
  </Step>

  <Step title="Specific Investigation with @file --mode=smart">
    Now that you have an overview, you can ask specific questions. The `smart` mode is ideal here, because you don't need to know which files contain the answer. The AI will find them for you.

    Let's investigate the authentication flow.

    ```bash theme={"system"}
    @file --mode=smart ./internal/ > Explain the end-to-end authentication flow, from the API route to token validation.
    ```

    <Info>
      **How it works:**

      1. ChatCLI sends the list of all files inside `./internal/` to the AI.
      2. The AI, based on the question "authentication flow," identifies that files like `auth_handler.go`, `jwt_service.go`, and `user_repository.go` are likely the most relevant.
      3. ChatCLI then sends the content of **only those selected files**.
      4. The AI answers your question based on the actual code from the most important files.
    </Info>
  </Step>

  <Step title="Deep Dive into a File with @file --mode=full">
    During your investigation, you may want to understand a specific file in detail. Now, use the `full` mode (or simply omit the mode, as it is the default).

    ```bash theme={"system"}
    @file ./internal/api/middleware/auth.go > Refactor this middleware to follow Go best practices, adding more robust error handling and logging.
    ```

    The AI now has the complete file content and can perform complex tasks such as refactoring, documentation, or test generation.
  </Step>
</Steps>

<Tip>
  **Result:** In less than 15 minutes, you went from zero knowledge of the project to:

  1. Understanding the high-level architecture.
  2. Mapping a critical business flow (authentication).
  3. Analyzing and even refactoring a specific code component.
</Tip>

This workflow transforms hours or days of manual exploration into a focused and efficient question-and-answer session.