# Claude Code para iniciantes: análise e edição de projetos na prática
> Guia prático para trabalhar com o Claude Code: exploração da base de código usando Read, Glob e Grep, realização de Code Review, edição completa de arquivos e reversão segura de alterações.
## 1. Como o Claude Code explora e lê a base de código
Diferente dos chats de IA convencionais no navegador, onde o desenvolvedor precisa copiar manualmente o código-fonte para a janela do diálogo, o Claude Code é um agente terminal completo. Ele possui acesso direto ao sistema de arquivos local do seu projeto e seleciona autonomamente ferramentas especializadas para navegar pela base de código.
O agente não carrega todo o projeto na memória simultaneamente (o que levaria ao esgotamento imediato do limite de tokens), mas aplica uma estratégia pontual de leitura em etapas.
```mermaid
flowchart TD
A["Запит розробника:
'Як працює авторизація?'"] --> B["Claude Code CLI"]
B --> C["Glob
(Пошук файлів auth/*, login.*)"]
B --> D["Grep
(Пошук ключових слів createSession, jwt)"]
C & D --> E["Аналіз знайдених шляхів"]
E --> F["Read
(Цільове читання знайдених файлів)"]
F --> G["Синтез відповіді з точними посиланнями"]
```
### Arsenal principal de ferramentas de exploração
| Ferramenta | O que faz | Cenário de uso típico |
| :--- | :--- | :--- |
| **`Read`** | Abre e lê um arquivo específico pelo caminho indicado | `Read src/auth/login.ts` para estudar a lógica do componente |
| **`Glob`** | Localiza arquivos e caminhos por padrão ou extensão | Busca de todos os configs `**/*.config.{js,ts}` ou testes `*.test.ts` |
| **`Grep`** | Executa busca full-text de caracteres ou expressões regulares | Localização de chamadas de função ou comentários `TODO` em todo o código |
| **`Bash(ls)`** | Inspeciona a estrutura de diretórios e módulos existentes | Exploração da estrutura da pasta `src/components/` |
> [!NOTE]
> Você não precisa chamar esses utilitários manualmente. Basta formular uma pergunta de engenharia em linguagem natural, e o Claude Code executará sozinho a cadeia de ferramentas otimizada.
---
## 2. Onboarding rápido em projetos desconhecidos
Ao abrir um repositório grande pela primeira vez, gastar horas lendo centenas de arquivos manualmente é ineficiente. O Claude Code permite obter um panorama arquitetural abrangente em segundos.
### Formulação da consulta arquitetural inicial
Navegue até a raiz do repositório, execute `claude` e comece com um prompt diagnóstico amplo:
```text
Give me an overview of this project. What does it do, what is the tech stack, and how is the code organized?
```
### O que o agente faz durante a varredura
1. **Leitura de manifestos de dependências:** analisa `package.json`, `Cargo.toml`, `go.mod` ou `requirements.txt`, identificando as principais bibliotecas e frameworks.
2. **Verificação da documentação:** abre `README.md`, `ARCHITECTURE.md` ou arquivos de especificação.
3. **Análise da estrutura de pastas:** avalia a divisão de responsabilidades entre os diretórios (`src/api`, `src/components`, `src/services`, `prisma`).
4. **Elaboração do resumo:** retorna um relatório estruturado com a lista de módulos-chave, pontos de entrada e instruções de execução.
> [!TIP]
> As explicações do Claude são construídas sobre o código atual presente no disco, e não sobre documentação desatualizada, que frequentemente fica anos sem ser atualizada.
---
## 3. Exploração pontual: rastreamento de fluxos de dados e requisições
Após compreender o panorama geral, chega a hora de investigar cenários de negócio específicos. A vantagem mais poderosa do Claude Code sobre modelos comuns é a capacidade de rastrear a cadeia completa de chamadas (Call Trace) entre as diferentes camadas da aplicação.
:::tabs
@tab Autenticação
```text
How does authentication work in this project? Trace the lifecycle of a request from the login form submission through JWT validation to the protected database query.
```
@tab Processamento de Pedido
```text
What happens when a user submits the checkout form? Trace the request flow from the frontend form to payment gateway processing and email notification dispatch.
```
@tab Tratamento de Eventos (Webhooks)
```text
Trace how incoming Stripe webhooks are received, verified for signature integrity, and processed in our database transaction worker.
```
:::
### Como o Claude rastreia cadeias de interação
Quando você define uma tarefa no formato "rastrear o fluxo", o agente executa os seguintes passos:
- Localiza o componente UI do formulário via `Grep`.
- Encontra a função manipuladora de clique e identifica o endpoint de API correspondente.
- Abre a rota do backend e analisa as camadas intermediárias (middleware) aplicadas.
- Investiga as chamadas de ORM/banco de dados e retorna um diagrama passo a passo coeso com números de linha.
---
## 4. Busca profunda por padrões e refatoração de imports
Graças às ferramentas integradas `Grep` e `Glob`, o agente realiza buscas precisas pelo uso de funções, tipos ou arquivos baseados em padrões, poupando você da saída bruta do terminal.
### Exemplos de consultas de busca precisas
```bash
# Знайти всі файли, які імпортують утиліту авторизації
Which files import from @/lib/auth or use the useSession hook?
# Знайти всі залишені технічні борги та мітки
Show me all TODO, FIXME, and HACK comments across the codebase with file paths
# Знайти всі виклики конкретної функції
Where is the calculateDiscount function called, and what parameters are passed to it?
# Знайти файли міграцій бази даних
List all migration files in the prisma/migrations/ directory created in the last month
```
O Claude processa os resultados, agrupa-os por categorias e explica o contexto de cada ocorrência encontrada, em vez de apenas despejar uma lista desconexa de linhas.
---
## 5. Decomposição e análise de trechos complexos de código
Ao se deparar com código legado confuso, expressões regulares incompreensíveis ou pipelines complexos de processamento de dados, recorra ao Claude para uma decomposição detalhada.
### Consultas para decomposição de código
```text
# Análise da cadeia de middlewares
Explique o pipeline de execução dos middlewares em src/server/middleware.ts. O que cada middleware faz e em qual ordem exata eles são executados?
# Explicação de uma expressão regular complexa
Esta expressão regular em src/utils/validators.ts é difícil de ler. Decomponha-a parte por parte e forneça exemplos de strings que correspondem e que não correspondem ao padrão.
# Análise do ciclo de vida do componente
O gerenciamento de estado em UserDashboard.tsx parece excessivamente complexo. Explique o fluxo de estado, o que dispara cada useEffect e onde podem ocorrer condições de corrida (race conditions).
```
O agente não apenas reconta o código, mas analisa casos extremos (edge cases), potenciais vazamentos de memória e problemas de sincronização.
---
## 6. Realização de Code Review e análise de Git Diff
O Claude Code é excelente para auditoria local de mudanças antes de criar um commit ou abrir um Pull Request.
### Fluxo de trabalho de revisão
```bash
# 1. Швидкий аудит застейджених змін перед комітом
git diff --staged | claude -p "Review this diff for bugs, edge cases, security issues, and style problems. Be concise."
# 2. Перевірка розбіжностей між гілкою задачі та main
git diff main...feature-branch | claude -p "Perform a code review of this branch. Focus on performance regressions and breaking changes."
```
### Revisão interativa dentro da sessão
Se você já está no modo interativo do Claude, basta digitar:
```text
Review the changes I made in the last commit. Look for logic bugs, missing error handling, and potential production bottlenecks.
```
O Claude analisará a saída do `git diff`, apontará potenciais problemas de confiabilidade e sugerirá correções específicas antes mesmo que seus colegas vejam o código.
---
## 7. Ferramentas de modificação: Edit, Write e Bash
Entender como o Claude Code modifica o sistema de arquivos é a chave para controlar a segurança da base de código. Para aplicar alterações, o agente utiliza a tríade de ferramentas: `Edit`, `Write` e `Bash`.
```mermaid
flowchart LR
subgraph Модифікація_диска["Інструменти редагування"]
E["Edit Tool
(Точкова заміна рядків)"]
W["Write Tool
(Створення / перезапис файлів)"]
B["Bash Tool
(Команди, пакети, збірка)"]
end
E --> D["Диференційний перегляд (Diff)"]
W --> D
B --> D
D --> U{"Підтвердження користувача"}
U -->|Y| S["Збереження на диску"]
U -->|N| R["Скасування правки"]
```
### Ferramenta Edit: edições cirúrgicas pontuais
`Edit` realiza substituições pontuais de fragmentos de texto. Ele encontra um bloco único de linhas no arquivo e o substitui pela versão atualizada, mantendo o restante do arquivo intacto.
```diff
// Приклад візуалізації дифу в терміналі Claude Code:
async function fetchUser(id: string) {
- const response = await fetch(`/api/users/${id}`);
- return response.json();
+ try {
+ const response = await fetch(`/api/users/${id}`);
+ if (!response.ok) {
+ throw new Error(`Failed to fetch user: ${response.status}`);
+ }
+ return await response.json();
+ } catch (error) {
+ console.error('Error fetching user:', error);
+ throw error;
+ }
}
```
Você sempre visualiza o diff colorido no terminal antes de aprovar a aplicação da mudança.
### Ferramenta Write: criação de novos módulos
`Write` é usado para gerar novos arquivos do zero ou para atualização completa de arquivos de configuração:
```text
Create a new utility module at src/lib/formatters.ts with helpers for currency formatting, relative timestamps, and phone numbers. Include JSDoc comments.
```
### Ferramenta Bash: operações do sistema e verificação
`Bash` permite que o agente interaja com o sistema operacional: instalar pacotes, executar migrações, compilar o projeto e rodar testes.
```text
Install zod and create a registration form schema in src/schemas/auth.ts, then run typecheck to make sure types align.
```
---
## 8. Mudanças transversais em múltiplos arquivos simultaneamente
A principal vantagem da abordagem agêntica completa sobre chats comuns é a capacidade de realizar refatorações transversais coerentes que afetam diferentes camadas da arquitetura.
```text
Add a 'phoneNumber' field to the User entity. Update the Prisma schema, generate the migration, update the registration API route, and add the input field to the Profile form component.
```
### Como o Claude garante a consistência das edições
1. **Atualização do esquema de dados:** edita `schema.prisma` via `Edit`.
2. **Execução da migração:** chama `npx prisma migrate dev` via `Bash`.
3. **Atualização da validação do backend:** adiciona validação de campo no esquema Zod da rota `src/app/api/user/route.ts`.
4. **Atualização da interface UI:** adiciona um campo de input no arquivo `src/components/ProfileForm.tsx`.
5. **Validação da compilação:** roda `npm run typecheck`, confirmando a ausência de conflitos de tipos.
Cada ação solicita sua confirmação, garantindo total transparência no processo.
---
## 9. Refinamento iterativo e desfazer seguro de edições
Desenvolver com o Claude Code é um diálogo interativo. Se uma edição gerada precisar de ajustes, não há necessidade de repetir todo o contexto novamente.
### Refinando edições no contexto da sessão atual
```text
# Alteração de estilo de código
Isso parece bom, mas por favor substitua as instruções if/else por uma instrução switch concisa.
# Adição de documentação
Ótimo, agora adicione comentários JSDoc abrangentes a todas as funções exportadas neste arquivo.
# Otimização de desempenho
Podemos memoizar este cálculo com useMemo para evitar recálculos a cada renderização?
```
### Mecanismos para desfazer mudanças indesejadas
Se uma alteração foi aprovada, mas o resultado não te agradou, existem duas formas confiáveis de reverter tudo:
1. **Via Claude:**
```text
Undo the last changes you made to src/lib/validation.ts and return the file to its previous state.
```
2. **Via Git diretamente no terminal:**
```bash
# Скасувати зміни в конкретному файлі
git checkout -- src/lib/validation.ts
# Скасувати всі незафіксовані зміни в проєкті
git reset --hard HEAD
```
> [!TIP]
> Faça um commit limpo antes de iniciar cada refatoração de grande escala com o Claude Code. Isso permite retornar a um estado funcional a qualquer momento com um único comando `git checkout`.
---
## 10. Melhores práticas de engenharia e checklist final
Seguir práticas de engenharia comprovadas transforma o Claude Code em um parceiro extremamente confiável de pair programming.
### Quatro regras para uma interação produtiva
1. **Uma tarefa — uma consulta:** Não misture features diferentes em um único prompt (*"Adicione autenticação, reescreva os estilos do header e remova os testes antigos"*). Divida o trabalho em passos atômicos.
2. **Verificação via compilador e testes:** Após concluir cada série de edições, peça ao assistente para verificar o resultado: `Run npm test and npm run typecheck to make sure everything compiles cleanly`.
3. **Compreensão da mecânica das ferramentas:** Lembre-se que mudanças pontuais passam pelo `Edit`, novos arquivos pelo `Write`, e verificações pelo `Bash`. Isso ajuda a dar instruções mais precisas.
4. **Higiene de contexto:** Se a tarefa foi concluída e você vai mudar para um tópico completamente diferente, use o comando `/compact` ou reinicie a sessão para limpar a memória de logs desnecessários.
### Autoavaliação rápida
> **1. Qual ferramenta o Claude Code usa para substituir fragmentos de código pontualmente sem sobrescrever o arquivo inteiro?**
>
> > [!TIP]
> > **Resposta:** A ferramenta `Edit`. Ela encontra um trecho único de código e realiza a substituição, exibindo uma visualização diferencial (diff).
> **2. Por que o Claude Code não carrega todos os arquivos do projeto na memória imediatamente ao iniciar?**
>
> > [!TIP]
> > **Resposta:** Para não exceder os limites da janela de contexto e não desperdiçar tokens excessivos. Em vez disso, ele usa navegação direcionada através de `Glob`, `Grep` e `Read`.
> **3. Como verificar rapidamente as diferenças da branch atual do PR em relação à main usando o Claude Code?**
>
> > [!TIP]
> > **Resposta:** Execute no terminal o comando `git diff main...feature-branch | claude -p "Code review this PR"`.
### Checklist final de trabalho prático
- [ ] Use prompts de visão geral para familiarização rápida com novas bases de código.
- [ ] Explore a arquitetura através de consultas de rastreamento de fluxos (*"Trace the flow from UI to database"*).
- [ ] Realize code reviews locais antes de criar cada Pull Request via `claude -p`.
- [ ] Revise atentamente o diff colorido no terminal antes de confirmar a chamada do `Edit`.
- [ ] Fixe commits estáveis antes de iniciar refatorações complexas.