6 6 

7> Guias passo a passo para explorar bases de código, corrigir bugs, refatorar, testar e outras tarefas cotidianas com Claude Code.7> Guias passo a passo para explorar bases de código, corrigir bugs, refatorar, testar e outras tarefas cotidianas com Claude Code.

8 8 

9Esta página aborda fluxos de trabalho práticos para desenvolvimento cotidiano: explorar código desconhecido, depuração, refatoração, escrita de testes, criação de PRs e gerenciamento de sessões. Cada seção inclui exemplos de prompts que você pode adaptar aos seus próprios projetos. Para padrões e dicas de nível superior, consulte [Melhores práticas](/pt/best-practices).9Esta página coleta receitas curtas para desenvolvimento cotidiano. Para orientação de nível superior sobre prompting e gerenciamento de contexto, consulte [Melhores práticas](/pt/best-practices).

10 10 

11## Entender novas bases de código11Esta página aborda:

12 12 

13### Obter uma visão geral rápida da base de código13* [Receitas de prompt](#prompt-recipes) para explorar código, corrigir bugs, refatorar, testar, PRs e documentação

14* [Retomar conversas anteriores](#resume-previous-conversations) para que uma tarefa possa abranger múltiplas sessões

15* [Executar sessões paralelas com worktrees](#run-parallel-sessions-with-worktrees) para que edições simultâneas não colidam

16* [Planejar antes de editar](#plan-before-editing) para revisar alterações antes de tocarem o disco

17* [Delegar pesquisa para subagents](#delegate-research-to-subagents) para manter seu contexto principal limpo

18* [Canalizar Claude em scripts](#pipe-claude-into-scripts) para CI e processamento em lote

19 

20## Receitas de prompt

21 

22Estes são padrões de prompt para tarefas cotidianas como explorar código desconhecido, depuração, refatoração, escrita de testes e criação de PRs. Cada um funciona em qualquer superfície do Claude Code; adapte a redação ao seu projeto.

23 

24### Entender novas bases de código

25 

26#### Obter uma visão geral rápida da base de código

14 27 

15Suponha que você acabou de ingressar em um novo projeto e precisa entender sua estrutura rapidamente.28Suponha que você acabou de ingressar em um novo projeto e precisa entender sua estrutura rapidamente.

16 29 

56 * Solicite um glossário de termos específicos do projeto69 * Solicite um glossário de termos específicos do projeto

57</Tip>70</Tip>

58 71 

59### Encontrar código relevante72#### Encontrar código relevante

60 73 

61Suponha que você precise localizar código relacionado a um recurso ou funcionalidade específica.74Suponha que você precise localizar código relacionado a um recurso ou funcionalidade específica.

62 75 

90 103 

91***104***

92 105 

93## Corrigir bugs com eficiência106### Corrigir bugs com eficiência

94 107 

95Suponha que você tenha encontrado uma mensagem de erro e precise encontrar e corrigir sua origem.108Suponha que você tenha encontrado uma mensagem de erro e precise encontrar e corrigir sua origem.

96 109 

124 137 

125***138***

126 139 

127## Refatorar código140### Refatorar código

128 141 

129Suponha que você precise atualizar código antigo para usar padrões e práticas modernas.142Suponha que você precise atualizar código antigo para usar padrões e práticas modernas.

130 143 

164 177 

165***178***

166 179 

167## Usar subagents especializados180### Trabalhar com testes

168 

169Suponha que você queira usar subagents de IA especializados para lidar com tarefas específicas de forma mais eficaz.

170 

171<Steps>

172 <Step title="Visualize subagents disponíveis">

173 ```text theme={null}

174 /agents

175 ```

176 

177 Isso mostra todos os subagents disponíveis e permite que você crie novos.

178 </Step>

179 

180 <Step title="Use subagents automaticamente">

181 Claude Code delega automaticamente tarefas apropriadas para subagents especializados:

182 

183 ```text theme={null}

184 review my recent code changes for security issues

185 ```

186 

187 ```text theme={null}

188 run all tests and fix any failures

189 ```

190 </Step>

191 

192 <Step title="Solicite explicitamente subagents específicos">

193 ```text theme={null}

194 use the code-reviewer subagent to check the auth module

195 ```

196 

197 ```text theme={null}

198 have the debugger subagent investigate why users can't log in

199 ```

200 </Step>

201 

202 <Step title="Crie subagents personalizados para seu fluxo de trabalho">

203 ```text theme={null}

204 /agents

205 ```

206 

207 Em seguida, selecione "Create New subagent" e siga os prompts para definir:

208 

209 * Um identificador único que descreve o propósito do subagent (por exemplo, `code-reviewer`, `api-designer`).

210 * Quando Claude deve usar este agente

211 * Quais ferramentas ele pode acessar

212 * Um prompt do sistema descrevendo o papel e comportamento do agente

213 </Step>

214</Steps>

215 

216<Tip>

217 Dicas:

218 

219 * Crie subagents específicos do projeto em `.claude/agents/` para compartilhamento em equipe

220 * Use campos `description` descritivos para permitir delegação automática

221 * Limite o acesso a ferramentas ao que cada subagent realmente precisa

222 * Consulte a [documentação de subagents](/pt/sub-agents) para exemplos detalhados

223</Tip>

224 

225***

226 

227## Usar Plan Mode para análise segura de código

228 

229Plan Mode instrui Claude a criar um plano analisando a base de código com operações somente leitura, perfeito para explorar bases de código, planejar alterações complexas ou revisar código com segurança. Em Plan Mode, Claude usa [`AskUserQuestion`](/pt/tools-reference) para reunir requisitos e esclarecer seus objetivos antes de propor um plano.

230 

231### Quando usar Plan Mode

232 

233* **Implementação multi-etapa**: Quando seu recurso requer fazer edições em muitos arquivos

234* **Exploração de código**: Quando você quer pesquisar a base de código completamente antes de alterar qualquer coisa

235* **Desenvolvimento interativo**: Quando você quer iterar na direção com Claude

236 

237### Como usar Plan Mode

238 

239**Ative Plan Mode durante uma sessão**

240 

241Você pode mudar para Plan Mode durante uma sessão usando **Shift+Tab** para percorrer os modos de permissão.

242 

243Se você estiver em Normal Mode, **Shift+Tab** primeiro muda para Auto-Accept Mode, indicado por `⏵⏵ accept edits on` na parte inferior do terminal. Um **Shift+Tab** subsequente mudará para Plan Mode, indicado por `⏸ plan mode on`.

244 

245**Inicie uma nova sessão em Plan Mode**

246 

247Para iniciar uma nova sessão em Plan Mode, use a flag `--permission-mode plan`:

248 

249```bash theme={null}

250claude --permission-mode plan

251```

252 

253**Execute consultas "headless" em Plan Mode**

254 

255Você também pode executar uma consulta em Plan Mode diretamente com `-p` (ou seja, em ["modo headless"](/pt/headless)):

256 

257```bash theme={null}

258claude --permission-mode plan -p "Analyze the authentication system and suggest improvements"

259```

260 

261### Exemplo: Planejando uma refatoração complexa

262 

263```bash theme={null}

264claude --permission-mode plan

265```

266 

267```text theme={null}

268I need to refactor our authentication system to use OAuth2. Create a detailed migration plan.

269```

270 

271Claude analisa a implementação atual e cria um plano abrangente. Refine com acompanhamentos:

272 

273```text theme={null}

274What about backward compatibility?

275```

276 

277```text theme={null}

278How should we handle database migration?

279```

280 

281<Tip>Pressione `Ctrl+G` para abrir o plano em seu editor de texto padrão, onde você pode editá-lo diretamente antes de Claude prosseguir.</Tip>

282 

283Quando você aceita um plano, Claude automaticamente nomeia a sessão a partir do conteúdo do plano. O nome aparece na barra de prompt e no seletor de sessão. Se você já definiu um nome com `--name` ou `/rename`, aceitar um plano não o sobrescreverá.

284 

285### Configure Plan Mode como padrão

286 

287```json theme={null}

288// .claude/settings.json

289{

290 "permissions": {

291 "defaultMode": "plan"

292 }

293}

294```

295 

296Consulte a [documentação de configurações](/pt/settings#available-settings) para mais opções de configuração.

297 

298***

299 

300## Trabalhar com testes

301 181 

302Suponha que você precise adicionar testes para código não coberto.182Suponha que você precise adicionar testes para código não coberto.

303 183 

333 213 

334***214***

335 215 

336## Criar pull requests216### Criar pull requests

337 217 

338Você pode criar pull requests pedindo ao Claude diretamente ("create a pr for my changes"), ou guiar Claude através disso passo a passo:218Você pode criar pull requests pedindo ao Claude diretamente ("create a pr for my changes"), ou guiar Claude através disso passo a passo:

339 219 

357 </Step>237 </Step>

358</Steps>238</Steps>

359 239 

360Quando você cria uma PR usando `gh pr create`, a sessão é automaticamente vinculada a essa PR. Você pode retomá-la mais tarde com `claude --from-pr <number>`.240Quando você cria uma PR usando `gh pr create`, a sessão é automaticamente vinculada a essa PR. Para retornar a ela mais tarde, execute `claude --from-pr <number>` ou cole a URL da PR no seletor [`/resume`](/pt/sessions#use-the-session-picker).

361 241 

362<Tip>242<Tip>

363 Revise a PR gerada por Claude antes de enviar e peça ao Claude para destacar riscos ou considerações potenciais.243 Revise a PR gerada por Claude antes de enviar e peça ao Claude para destacar riscos ou considerações potenciais.

364</Tip>244</Tip>

365 245 

366## Lidar com documentação246### Lidar com documentação

367 247 

368Suponha que você precise adicionar ou atualizar documentação para seu código.248Suponha que você precise adicionar ou atualizar documentação para seu código.

369 249 

403 283 

404***284***

405 285 

406## Trabalhar em notas e pastas não-código286### Trabalhar em notas e pastas não-código

407 287 

408Claude Code funciona em qualquer diretório. Execute-o dentro de um cofre de notas, uma pasta de documentação ou qualquer coleção de arquivos markdown para pesquisar, editar e reorganizar conteúdo da mesma forma que você faria com código.288Claude Code funciona em qualquer diretório. Execute-o dentro de um cofre de notas, uma pasta de documentação ou qualquer coleção de arquivos markdown para pesquisar, editar e reorganizar conteúdo da mesma forma que você faria com código.

409 289 

411 291 

412***292***

413 293 

414## Trabalhar com imagens294### Trabalhar com imagens

415 295 

416Suponha que você precise trabalhar com imagens em sua base de código e queira ajuda do Claude para analisar o conteúdo da imagem.296Suponha que você precise trabalhar com imagens em sua base de código e queira ajuda do Claude para analisar o conteúdo da imagem.

417 297 

471 351 

472***352***

473 353 

474## Referenciar arquivos e diretórios354### Referenciar arquivos e diretórios

475 355 

476Use @ para incluir rapidamente arquivos ou diretórios sem esperar que Claude os leia.356Use @ para incluir rapidamente arquivos ou diretórios sem esperar que Claude os leia.

477 357 

512 392 

513***393***

514 394 

515## Usar pensamento estendido (thinking mode)395### Executar Claude em um cronograma

516 

517[Pensamento estendido](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) é ativado por padrão, dando ao Claude espaço para raciocinar através de problemas complexos passo a passo antes de responder. Este raciocínio é visível em modo verboso, que você pode ativar com `Ctrl+O`. Durante pensamento estendido, o spinner mostra dicas de progresso inline como "still thinking" e "almost done thinking" para indicar que Claude está trabalhando ativamente.

518 

519Além disso, [modelos que suportam esforço](/pt/model-config#adjust-effort-level) usam raciocínio adaptativo: em vez de um orçamento de token de pensamento fixo, o modelo decide dinamicamente se e quanto pensar com base em sua configuração de nível de esforço e na tarefa em questão. Raciocínio adaptativo permite que Claude responda mais rápido a prompts rotineiros e reserve pensamento mais profundo para etapas que se beneficiam dele.

520 

521Pensamento estendido é particularmente valioso para decisões arquitetônicas complexas, bugs desafiadores, planejamento de implementação multi-etapa e avaliação de compensações entre diferentes abordagens.

522 

523<Note>

524 Frases como "think", "think hard" e "think more" são interpretadas como instruções de prompt regulares e não alocam tokens de pensamento.

525</Note>

526 

527### Configurar thinking mode

528 

529Pensamento é ativado por padrão, mas você pode ajustá-lo ou desativá-lo.

530 

531| Escopo | Como configurar | Detalhes |

532| ------------------------------ | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

533| **Nível de esforço** | Execute `/effort`, ajuste em `/model`, ou defina [`CLAUDE_CODE_EFFORT_LEVEL`](/pt/env-vars) | Controle a profundidade de pensamento em [modelos suportados](/pt/model-config#adjust-effort-level) |

534| **Palavra-chave `ultrathink`** | Inclua "ultrathink" em qualquer lugar em seu prompt | Adiciona uma instrução em contexto dizendo ao modelo para raciocinar mais nesse turno. Não altera o nível de esforço em si; consulte [Ajustar nível de esforço](/pt/model-config#adjust-effort-level) para isso |

535| **Atalho de alternância** | Pressione `Option+T` (macOS) ou `Alt+T` (Windows/Linux) | Alterne pensamento ligado/desligado para a sessão atual (todos os modelos). Pode exigir [configuração de terminal](/pt/terminal-config) para ativar atalhos de tecla Option |

536| **Padrão global** | Use `/config` para alternar thinking mode | Define seu padrão em todos os projetos (todos os modelos).<br />Salvo como `alwaysThinkingEnabled` em `~/.claude/settings.json` |

537| **Limitar orçamento de token** | Defina a variável de ambiente [`MAX_THINKING_TOKENS`](/pt/env-vars) | Limite o orçamento de pensamento para um número específico de tokens. Em modelos com raciocínio adaptativo, apenas `0` se aplica a menos que raciocínio adaptativo seja desativado. Exemplo: `export MAX_THINKING_TOKENS=10000` |

538 

539Para visualizar o processo de pensamento do Claude, pressione `Ctrl+O` para alternar o modo verboso e veja o raciocínio interno exibido como texto em itálico cinzento.

540 

541### Como funciona o pensamento estendido

542 

543Pensamento estendido controla quanto raciocínio interno Claude realiza antes de responder. Mais pensamento fornece mais espaço para explorar soluções, analisar casos extremos e autocorrigir erros.

544 

545Em [modelos que suportam esforço](/pt/model-config#adjust-effort-level), pensamento usa raciocínio adaptativo: o modelo aloca dinamicamente tokens de pensamento com base no nível de esforço que você seleciona. Esta é a forma recomendada de ajustar a compensação entre velocidade e profundidade de raciocínio. Se você quiser que Claude pense mais ou menos do que seu nível de esforço produziria de outra forma, você também pode dizer isso diretamente em seu prompt ou em `CLAUDE.md`.

546 

547Com modelos mais antigos, pensamento usa um orçamento fixo de tokens extraído de sua alocação de saída. O orçamento varia por modelo; consulte [`MAX_THINKING_TOKENS`](/pt/env-vars) para limites por modelo. Você pode limitar o orçamento com essa variável de ambiente, ou desativar pensamento inteiramente via `/config` ou a alternância `Option+T`/`Alt+T`.

548 

549Em modelos com raciocínio adaptativo, `MAX_THINKING_TOKENS` só se aplica quando definido como `0` para desativar pensamento, ou quando `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` reverte o modelo para o orçamento fixo. `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` se aplica apenas a Opus 4.6 e Sonnet 4.6. Opus 4.7 sempre usa raciocínio adaptativo e não suporta um orçamento de pensamento fixo. Consulte [variáveis de ambiente](/pt/env-vars).

550 

551<Warning>

552 Você é cobrado por todos os tokens de pensamento usados, mesmo quando resumos de pensamento são redatados. Em modo interativo, pensamento aparece como um stub recolhido por padrão. Defina `showThinkingSummaries: true` em `settings.json` para mostrar resumos completos.

553</Warning>

554 

555***

556 

557## Retomar conversas anteriores

558 

559Ao iniciar Claude Code, você pode retomar uma sessão anterior:

560 

561* `claude --continue` continua a conversa mais recente no diretório atual

562* `claude --resume` abre um seletor de conversa ou retoma por nome

563* `claude --from-pr 123` retoma sessões vinculadas a uma pull request específica

564 

565De dentro de uma sessão ativa, use `/resume` para mudar para uma conversa diferente.

566 

567Quando a sessão selecionada é antiga e grande o suficiente que relê-la consumiria uma parte substancial de seus limites de uso, `--resume`, `--continue` e `/resume` oferecem retomar a partir de um resumo em vez de carregar a transcrição completa. Este prompt não está disponível no Amazon Bedrock, Google Cloud Vertex AI ou Microsoft Foundry.

568 

569As sessões são armazenadas por diretório de projeto. Por padrão, o seletor `/resume` mostra sessões interativas do worktree atual, com atalhos de teclado para ampliar a lista para outros worktrees ou projetos, pesquisar, visualizar e renomear. Consulte [Use o seletor de sessão](#use-the-session-picker) abaixo para a referência completa de atalhos.

570 

571Quando você seleciona uma sessão de outro worktree do mesmo repositório, Claude Code a retoma diretamente sem exigir que você mude de diretórios primeiro. Selecionar uma sessão de um projeto não relacionado copia um comando `cd` e resume para sua área de transferência em vez disso.

572 

573Retomar por nome resolve em todo o repositório atual e seus worktrees. Tanto `claude --resume <name>` quanto `/resume <name>` procuram uma correspondência exata e a retomam diretamente, mesmo que a sessão viva em um worktree diferente.

574 

575Quando o nome é ambíguo, `claude --resume <name>` abre o seletor com o nome pré-preenchido como um termo de pesquisa. `/resume <name>` de dentro de uma sessão relata um erro em vez disso, então execute `/resume` sem argumento para abrir o seletor e escolher.

576 

577Sessões criadas por `claude -p` ou invocações SDK não aparecem no seletor, mas você ainda pode retomar uma passando seu ID de sessão diretamente para `claude --resume <session-id>`.

578 

579### Nomeie suas sessões

580 

581Dê nomes descritivos às sessões para encontrá-las mais tarde. Esta é uma prática recomendada ao trabalhar em múltiplas tarefas ou recursos.

582 

583<Steps>

584 <Step title="Nomeie a sessão">

585 Nomeie uma sessão na inicialização com `-n`:

586 

587 ```bash theme={null}

588 claude -n auth-refactor

589 ```

590 

591 Ou use `/rename` durante uma sessão, que também mostra o nome na barra de prompt:

592 

593 ```text theme={null}

594 /rename auth-refactor

595 ```

596 

597 Você também pode renomear qualquer sessão do seletor: execute `/resume`, navegue até uma sessão e pressione `Ctrl+R`.

598 </Step>

599 

600 <Step title="Retome por nome mais tarde">

601 Da linha de comando:

602 

603 ```bash theme={null}

604 claude --resume auth-refactor

605 ```

606 

607 Ou de dentro de uma sessão ativa:

608 

609 ```text theme={null}

610 /resume auth-refactor

611 ```

612 </Step>

613</Steps>

614 

615### Use o seletor de sessão

616 

617O comando `/resume` (ou `claude --resume` sem argumentos) abre um seletor de sessão interativo com estes recursos:

618 

619**Atalhos de teclado no seletor:**

620 

621| Atalho | Ação |

622| :-------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

623| `↑` / `↓` | Navegue entre sessões |

624| `→` / `←` | Expanda ou recolha sessões agrupadas |

625| `Enter` | Selecione e retome a sessão destacada |

626| `Space` | Visualize o conteúdo da sessão. `Ctrl+V` também funciona em terminais que não o capturam como colar |

627| `Ctrl+R` | Renomeie a sessão destacada |

628| `/` ou qualquer caractere imprimível diferente de `Space` | Entre no modo de pesquisa e filtre sessões |

629| `Ctrl+A` | Mostre sessões de todos os projetos nesta máquina. Pressione novamente para restaurar o repositório atual |

630| `Ctrl+W` | Mostre sessões de todos os worktrees do repositório atual. Pressione novamente para restaurar o worktree atual. Mostrado apenas em repositórios com múltiplos worktrees |

631| `Ctrl+B` | Filtre para sessões do seu branch git atual. Pressione novamente para mostrar sessões de todos os branches |

632| `Esc` | Saia do seletor ou modo de pesquisa |

633 

634**Organização de sessão:**

635 

636O seletor exibe sessões com metadados úteis:

637 

638* Nome da sessão se definido, caso contrário o resumo da conversa ou primeiro prompt do usuário

639* Tempo decorrido desde a última atividade

640* Contagem de mensagens

641* Branch git (se aplicável)

642* Caminho do projeto, mostrado após ampliar para todos os projetos com `Ctrl+A`

643 

644Sessões bifurcadas (criadas com `/branch`, `/rewind`, ou `--fork-session`) são agrupadas sob sua sessão raiz, facilitando encontrar conversas relacionadas.

645 

646<Tip>

647 Dicas:

648 

649 * **Nomeie sessões cedo**: Use `/rename` ao iniciar trabalho em uma tarefa distinta: é muito mais fácil encontrar "payment-integration" do que "explain this function" mais tarde

650 * Use `--continue` para acesso rápido à sua conversa mais recente no diretório atual

651 * Use `--resume session-name` quando você sabe qual sessão precisa

652 * Use `--resume` (sem um nome) quando você precisa navegar e selecionar

653 * Para scripts, use `claude --continue --print "prompt"` para retomar em modo não interativo

654 * Pressione `Space` no seletor para visualizar uma sessão antes de retomá-la

655 * A conversa retomada começa com o mesmo modelo e configuração do original

656 

657 Como funciona:

658 

659 1. **Armazenamento de Conversa**: Todas as conversas são automaticamente salvas localmente com seu histórico de mensagens completo

660 2. **Desserialização de Mensagem**: Ao retomar, todo o histórico de mensagens é restaurado para manter contexto

661 3. **Estado de Ferramenta**: O uso de ferramenta e resultados da conversa anterior são preservados

662 4. **Restauração de Contexto**: A conversa retoma com todo o contexto anterior intacto

663</Tip>

664 

665***

666 

667## Executar sessões paralelas de Claude Code com Git worktrees

668 

669Ao trabalhar em múltiplas tarefas ao mesmo tempo, você precisa que cada sessão do Claude tenha sua própria cópia da base de código para que as alterações não colidam. Git worktrees resolvem isso criando diretórios de trabalho separados que cada um tem seus próprios arquivos e branch, enquanto compartilham o mesmo histórico de repositório e conexões remotas. Isso significa que você pode ter Claude trabalhando em um recurso em um worktree enquanto corrige um bug em outro, sem que nenhuma sessão interfira com a outra.

670 

671Use a flag `--worktree` (`-w`) para criar um worktree isolado e iniciar Claude nele. O valor que você passa se torna o nome do diretório worktree e nome do branch:

672 

673```bash theme={null}

674# Inicie Claude em um worktree nomeado "feature-auth"

675# Cria .claude/worktrees/feature-auth/ com um novo branch

676claude --worktree feature-auth

677 

678# Inicie outra sessão em um worktree separado

679claude --worktree bugfix-123

680```

681 

682Se você omitir o nome, Claude gera um automaticamente:

683 

684```bash theme={null}

685# Auto-gera um nome como "bright-running-fox"

686claude --worktree

687```

688 

689Worktrees são criados em `<repo>/.claude/worktrees/<name>` e fazem branch a partir do branch remoto padrão, que é para onde `origin/HEAD` aponta. O branch worktree é nomeado `worktree-<name>`.

690 

691O branch base não é configurável através de um flag ou configuração do Claude Code. `origin/HEAD` é uma referência armazenada em seu diretório `.git` local que Git definiu uma vez quando você clonou. Se o branch padrão do repositório mudar mais tarde no GitHub ou GitLab, seu `origin/HEAD` local continua apontando para o antigo, e worktrees farão branch a partir daí. Para ressincronizar sua referência local com o que o remoto atualmente considera seu padrão:

692 

693```bash theme={null}

694git remote set-head origin -a

695```

696 

697Este é um comando Git padrão que apenas atualiza seu diretório `.git` local. Nada no servidor remoto muda. Se você quiser que worktrees façam base em um branch específico em vez do padrão do remoto, defina-o explicitamente com `git remote set-head origin your-branch-name`.

698 

699Para controle total sobre como worktrees são criados, incluindo escolher uma base diferente por invocação, configure um [hook WorktreeCreate](/pt/hooks#worktreecreate). O hook substitui a lógica padrão `git worktree` do Claude Code inteiramente, para que você possa buscar e fazer branch a partir de qualquer ref que você precise.

700 

701Você também pode pedir ao Claude para "work in a worktree" ou "start a worktree" durante uma sessão, e ele criará um automaticamente.

702 

703### Worktrees de subagent

704 

705Subagents também podem usar isolamento de worktree para trabalhar em paralelo sem conflitos. Peça ao Claude para "use worktrees for your agents" ou configure em um [subagent personalizado](/pt/sub-agents#supported-frontmatter-fields) adicionando `isolation: worktree` ao frontmatter do agente. Cada subagent obtém seu próprio worktree que é automaticamente limpo quando o subagent termina sem alterações.

706 

707### Limpeza de worktree

708 

709Quando você sai de uma sessão de worktree, Claude lida com limpeza com base em se você fez alterações:

710 

711* **Sem alterações**: o worktree e seu branch são removidos automaticamente

712* **Alterações ou commits existem**: Claude o solicita para manter ou remover o worktree. Manter preserva o diretório e branch para que você possa retornar mais tarde. Remover exclui o diretório worktree e seu branch, descartando todas as alterações não confirmadas e commits

713 

714Worktrees de subagent órfãos por uma falha ou uma execução paralela interrompida são removidos automaticamente na inicialização uma vez que são mais antigos do que sua configuração [`cleanupPeriodDays`](/pt/settings#available-settings), desde que não tenham alterações não confirmadas, nenhum arquivo não rastreado e nenhum commit não enviado. Worktrees que você cria com `--worktree` nunca são removidos por esta varredura.

715 

716Para limpar worktrees fora de uma sessão do Claude, use [gerenciamento manual de worktree](#manage-worktrees-manually).

717 

718<Tip>

719 Adicione `.claude/worktrees/` ao seu `.gitignore` para evitar que o conteúdo do worktree apareça como arquivos não rastreados em seu repositório principal.

720</Tip>

721 

722### Copiar arquivos gitignored para worktrees

723 

724Git worktrees são checkouts frescos, então eles não incluem arquivos não rastreados como `.env` ou `.env.local` do seu repositório principal. Para copiar automaticamente esses arquivos quando Claude cria um worktree, adicione um arquivo `.worktreeinclude` à raiz do seu projeto.

725 

726O arquivo usa sintaxe `.gitignore` para listar quais arquivos copiar. Apenas arquivos que correspondem a um padrão e também são gitignored são copiados, então arquivos rastreados nunca são duplicados.

727 

728```text .worktreeinclude theme={null}

729.env

730.env.local

731config/secrets.json

732```

733 

734Isso se aplica a worktrees criados com `--worktree`, worktrees de subagent e sessões paralelas no [aplicativo desktop](/pt/desktop#work-in-parallel-with-sessions).

735 

736### Gerenciar worktrees manualmente

737 

738Para mais controle sobre localização de worktree e configuração de branch, crie worktrees com Git diretamente. Isso é útil quando você precisa fazer checkout de um branch existente específico ou colocar o worktree fora do repositório.

739 

740```bash theme={null}

741# Crie um worktree com um novo branch

742git worktree add ../project-feature-a -b feature-a

743 

744# Crie um worktree com um branch existente

745git worktree add ../project-bugfix bugfix-123

746 

747# Inicie Claude no worktree

748cd ../project-feature-a && claude

749 

750# Limpe quando terminar

751git worktree list

752git worktree remove ../project-feature-a

753```

754 

755Saiba mais na [documentação oficial de Git worktree](https://git-scm.com/docs/git-worktree).

756 

757<Tip>

758 Lembre-se de inicializar seu ambiente de desenvolvimento em cada novo worktree de acordo com seu projeto. Dependendo de sua stack, isso pode incluir executar instalação de dependência (`npm install`, `yarn`), configurar ambientes virtuais ou seguir o processo de configuração padrão do seu projeto.

759</Tip>

760 

761### Controle de versão não-git

762 

763Isolamento de worktree funciona com git por padrão. Para outros sistemas de controle de versão como SVN, Perforce ou Mercurial, configure [hooks WorktreeCreate e WorktreeRemove](/pt/hooks#worktreecreate) para fornecer lógica personalizada de criação e limpeza de worktree. Quando configurados, esses hooks substituem o comportamento padrão do git quando você usa `--worktree`, então [`.worktreeinclude`](#copy-gitignored-files-to-worktrees) não é processado. Copie quaisquer arquivos de configuração local dentro de seu script de hook em vez disso.

764 

765Para coordenação automatizada de sessões paralelas com tarefas compartilhadas e mensagens, consulte [equipes de agentes](/pt/agent-teams).

766 

767***

768 

769## Obtenha notificações quando Claude precisa de sua atenção

770 

771Quando você inicia uma tarefa de longa duração e muda para outra janela, você pode configurar notificações de desktop para saber quando Claude termina ou precisa de sua entrada. Isso usa o evento de hook `Notification` [hook event](/pt/hooks-guide#get-notified-when-claude-needs-input), que dispara sempre que Claude está esperando permissão, ocioso e pronto para um novo prompt, ou completando autenticação.

772 

773<Steps>

774 <Step title="Adicione o hook às suas configurações">

775 Abra `~/.claude/settings.json` e adicione um hook `Notification` que chama o comando de notificação nativa da sua plataforma:

776 

777 <Tabs>

778 <Tab title="macOS">

779 ```json theme={null}

780 {

781 "hooks": {

782 "Notification": [

783 {

784 "matcher": "",

785 "hooks": [

786 {

787 "type": "command",

788 "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"

789 }

790 ]

791 }

792 ]

793 }

794 }

795 ```

796 </Tab>

797 

798 <Tab title="Linux">

799 ```json theme={null}

800 {

801 "hooks": {

802 "Notification": [

803 {

804 "matcher": "",

805 "hooks": [

806 {

807 "type": "command",

808 "command": "notify-send 'Claude Code' 'Claude Code needs your attention'"

809 }

810 ]

811 }

812 ]

813 }

814 }

815 ```

816 </Tab>

817 

818 <Tab title="Windows">

819 ```json theme={null}

820 {

821 "hooks": {

822 "Notification": [

823 {

824 "matcher": "",

825 "hooks": [

826 {

827 "type": "command",

828 "command": "powershell.exe -Command \"[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude Code needs your attention', 'Claude Code')\""

829 }

830 ]

831 }

832 ]

833 }

834 }

835 ```

836 </Tab>

837 </Tabs>

838 

839 Se seu arquivo de configurações já tiver uma chave `hooks`, mescle a entrada `Notification` nela em vez de sobrescrever. Você também pode pedir ao Claude para escrever o hook para você descrevendo o que você quer no CLI.

840 </Step>

841 

842 <Step title="Opcionalmente, estreite o matcher">

843 Por padrão, o hook dispara em todos os tipos de notificação. Para disparar apenas para eventos específicos, defina o campo `matcher` para um destes valores:

844 

845 | Matcher | Dispara quando |

846 | :--------------------- | :------------------------------------------------------------ |

847 | `permission_prompt` | Claude precisa que você aprove um uso de ferramenta |

848 | `idle_prompt` | Claude terminou e está esperando seu próximo prompt |

849 | `auth_success` | Autenticação completa |

850 | `elicitation_dialog` | Um servidor MCP abre um formulário de elicitação |

851 | `elicitation_complete` | Um formulário de elicitação MCP é enviado ou descartado |

852 | `elicitation_response` | Uma resposta de elicitação MCP é enviada de volta ao servidor |

853 </Step>

854 

855 <Step title="Verifique o hook">

856 Digite `/hooks` e selecione `Notification` para confirmar que o hook aparece. Selecioná-lo mostra o comando que será executado. Para testá-lo de ponta a ponta, peça ao Claude para executar um comando que requer permissão e mude para longe do terminal, ou peça ao Claude para disparar uma notificação diretamente.

857 </Step>

858</Steps>

859 

860Para o esquema de evento completo e tipos de notificação, consulte a [referência de Notificação](/pt/hooks#notification).

861 

862***

863 

864## Usar Claude como um utilitário estilo unix

865 

866### Adicione Claude ao seu processo de verificação

867 

868Suponha que você queira usar Claude Code como um linter ou revisor de código.

869 

870**Adicione Claude ao seu script de compilação:**

871 

872```json theme={null}

873// package.json

874{

875 ...

876 "scripts": {

877 ...

878 "lint:claude": "claude -p 'you are a linter. please look at the changes vs. main and report any issues related to typos. report the filename and line number on one line, and a description of the issue on the second line. do not return any other text.'"

879 }

880}

881```

882 

883<Tip>

884 Dicas:

885 

886 * Use Claude para revisão de código automatizada em seu pipeline CI/CD

887 * Personalize o prompt para verificar problemas específicos relevantes ao seu projeto

888 * Considere criar múltiplos scripts para diferentes tipos de verificação

889</Tip>

890 

891### Pipe in, pipe out

892 

893Suponha que você queira canalizar dados para Claude e obter dados de volta em um formato estruturado.

894 

895**Canalize dados através do Claude:**

896 

897```bash theme={null}

898cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt

899```

900 

901<Tip>

902 Dicas:

903 

904 * Use pipes para integrar Claude em scripts shell existentes

905 * Combine com outras ferramentas Unix para fluxos de trabalho poderosos

906 * Considere usar `--output-format` para saída estruturada

907</Tip>

908 

909### Controlar formato de saída

910 

911Suponha que você precise da saída do Claude em um formato específico, especialmente ao integrar Claude Code em scripts ou outras ferramentas.

912 

913<Steps>

914 <Step title="Use formato de texto (padrão)">

915 ```bash theme={null}

916 cat data.txt | claude -p 'summarize this data' --output-format text > summary.txt

917 ```

918 

919 Isso produz apenas a resposta de texto simples do Claude (comportamento padrão).

920 </Step>

921 

922 <Step title="Use formato JSON">

923 ```bash theme={null}

924 cat code.py | claude -p 'analyze this code for bugs' --output-format json > analysis.json

925 ```

926 

927 Isso produz um array JSON de mensagens com metadados incluindo custo e duração.

928 </Step>

929 

930 <Step title="Use formato JSON de streaming">

931 ```bash theme={null}

932 cat log.txt | claude -p 'parse this log file for errors' --output-format stream-json

933 ```

934 

935 Isso produz uma série de objetos JSON em tempo real conforme Claude processa a solicitação. Cada mensagem é um objeto JSON válido, mas a saída inteira não é JSON válido se concatenado.

936 </Step>

937</Steps>

938 

939<Tip>

940 Dicas:

941 

942 * Use `--output-format text` para integrações simples onde você apenas precisa da resposta do Claude

943 * Use `--output-format json` quando você precisa do log de conversa completo

944 * Use `--output-format stream-json` para saída em tempo real de cada turno de conversa

945</Tip>

946 

947***

948 

949## Executar Claude em um cronograma

950 396 

951Suponha que você queira que Claude lide com uma tarefa automaticamente em uma base recorrente, como revisar PRs abertas todas as manhãs, auditar dependências semanalmente ou verificar falhas de CI durante a noite.397Suponha que você queira que Claude lide com uma tarefa automaticamente em uma base recorrente, como revisar PRs abertas todas as manhãs, auditar dependências semanalmente ou verificar falhas de CI durante a noite.

952 398 

965 411 

966***412***

967 413 

968## Pergunte ao Claude sobre suas capacidades414### Pergunte ao Claude sobre suas capacidades

969 415 

970Claude tem acesso integrado à sua documentação e pode responder perguntas sobre seus próprios recursos e limitações.416Claude tem acesso integrado à sua documentação e pode responder perguntas sobre seus próprios recursos e limitações.

971 417 

972### Perguntas de exemplo418#### Perguntas de exemplo

973 419 

974```text theme={null}420```text theme={null}

975can Claude Code create pull requests?421can Claude Code create pull requests?

1009 455 

1010***456***

1011 457 

458## Retomar conversas anteriores

459 

460Quando uma tarefa abrange múltiplas sessões, retome de onde parou em vez de re-explicar o contexto. Claude Code salva cada conversa localmente.

461 

462```bash theme={null}

463claude --continue

464```

465 

466Isso retoma a sessão mais recente no diretório atual; se não houver uma ainda, ele imprime `No conversation found to continue` e sai. Use `claude --resume` para escolher de uma lista, ou `/resume` de dentro de uma sessão em execução. Consulte [Gerenciar sessões](/pt/sessions) para nomeação, ramificação e referência completa do seletor.

467 

468## Executar sessões paralelas com worktrees

469 

470Trabalhe em um recurso em um terminal enquanto Claude corrige um bug em outro, sem que as edições colidam. Cada worktree é um checkout separado em seu próprio branch.

471 

472```bash theme={null}

473claude --worktree feature-auth

474```

475 

476Execute o mesmo comando com um nome diferente em um segundo terminal para iniciar uma sessão paralela isolada. Consulte [Worktrees](/pt/worktrees) para limpeza, `.worktreeinclude` e suporte a VCS não-git. Para monitorar sessões paralelas de uma tela em vez de terminais separados, consulte [agentes em segundo plano](/pt/agent-view).

477 

478## Planejar antes de editar

479 

480Para alterações que você quer revisar antes de tocarem o disco, mude para plan mode. Claude lê arquivos e propõe um plano, mas não faz edições até que você aprove.

481 

482```bash theme={null}

483claude --permission-mode plan

484```

485 

486Você também pode pressionar `Shift+Tab` durante uma sessão para alternar para plan mode. Consulte [Plan mode](/pt/permission-modes#analyze-before-you-edit-with-plan-mode) para o fluxo de aprovação e edição do plano em seu editor de texto.

487 

488## Delegar pesquisa para subagents

489 

490Explorar uma base de código grande preenche seu contexto com leituras de arquivo. Delegue a exploração para que apenas os achados retornem.

491 

492```text theme={null}

493use a subagent to investigate how our auth system handles token refresh

494```

495 

496O subagent lê arquivos em sua própria janela de contexto e relata um resumo. Consulte [Subagents](/pt/sub-agents) para definir agentes personalizados com suas próprias ferramentas e prompts.

497 

498## Canalizar Claude em scripts

499 

500Execute Claude de forma não interativa para CI, hooks de pré-commit ou processamento em lote. Stdin e stdout funcionam como qualquer ferramenta Unix.

501 

502```bash theme={null}

503git log --oneline -20 | claude -p "summarize these recent commits"

504```

505 

506Consulte [Modo não interativo](/pt/headless) para formatos de saída, flags de permissão e padrões de fan-out.

507 

1012## Próximos passos508## Próximos passos

1013 509 

1014<CardGroup cols={2}>510<CardGroup cols={2}>

1016 Padrões para aproveitar ao máximo Claude Code512 Padrões para aproveitar ao máximo Claude Code

1017 </Card>513 </Card>

1018 514 

1019 <Card title="Como Claude Code funciona" icon="gear" href="/pt/how-claude-code-works">515 <Card title="Gerenciar sessões" icon="rotate-left" href="/pt/sessions">

1020 Entenda o loop agentic e gerenciamento de contexto516 Retomar, nomear e ramificar conversas

1021 </Card>517 </Card>

1022 518 

1023 <Card title="Estender Claude Code" icon="puzzle-piece" href="/pt/features-overview">519 <Card title="Worktrees" icon="code-branch" href="/pt/worktrees">

1024 Adicione skills, hooks, MCP, subagents e plugins520 Executar sessões paralelas isoladas

1025 </Card>521 </Card>

1026 522 

1027 <Card title="Implementação de referência" icon="code" href="https://github.com/anthropics/claude-code/tree/main/.devcontainer">523 <Card title="Estender Claude Code" icon="puzzle-piece" href="/pt/features-overview">

1028 Clone a implementação de referência do contêiner de desenvolvimento524 Adicionar skills, hooks, MCP, subagents e plugins

1029 </Card>525 </Card>

1030</CardGroup>526</CardGroup>