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>
