You ask Claude to refactor a function. Simple enough. But three minutes pass and it's still working, reading files, running commands, reading more files. What exactly is happening during all that time? The answer is both simpler and more mechanical than most people expect, and understanding it changes everything about how you interact with Claude Code.

Você pede ao Claude para refatorar uma função. Simples o suficiente. Mas três minutos passam e ele ainda está trabalhando, lendo arquivos, executando comandos, lendo mais arquivos. O que exatamente está acontecendo durante todo esse tempo? A resposta é ao mesmo tempo mais simples e mais mecânica do que a maioria das pessoas espera, e entendê-la muda tudo sobre como você interage com o Claude Code.

At the core of Claude Code is something called the QueryEngine. Its job is deceptively simple: take everything that needs to go to the Claude API — your message, the system prompt, any memory files, all prior tool results — bundle it into a single request, send it, and handle what comes back. What makes it interesting is what happens when Claude's response includes a tool call. The QueryEngine executes the tool, appends the result to the conversation, and then sends the whole thing back to the API again. And again. It keeps looping until Claude returns a response with no tool calls in it.

This is the core loop, and it's the most important thing to understand about Claude Code. Every single tool use — reading a file, running a bash command, searching for a pattern — is a complete round trip to the Claude API. Claude sees the current state of everything, decides what to do next, the engine does it, and Claude sees the result. There is no background processing and there is no Claude thinking while tools run. It is a strict sequence: Claude decides, tool runs, Claude sees result, Claude decides again.

The implication that surprises most people: if Claude reads ten files to complete your task, that's ten separate API calls, each one sending the full accumulated context. The tenth call sends your original message, plus the system prompt, plus memory files, plus the results of all nine previous tool calls. This is why long tasks consume so many tokens, because context grows with every step and every step sends the full accumulated conversation.

No coração do Claude Code está algo chamado QueryEngine. Seu trabalho é enganosamente simples: pegar tudo que precisa ir para a API do Claude — sua mensagem, o prompt do sistema, quaisquer arquivos de memória e todos os resultados de ferramentas anteriores — empacotar tudo numa única requisição, enviar e lidar com o que volta. O que o torna interessante é o que acontece quando a resposta do Claude inclui uma chamada de ferramenta. O QueryEngine executa a ferramenta, anexa o resultado à conversa e então envia tudo de volta para a API novamente. E de novo. O ciclo se repete até que o Claude retorne uma resposta sem chamadas de ferramentas.

Esse é o loop central, e é a coisa mais importante para entender sobre o Claude Code. Cada uso de ferramenta — ler um arquivo, executar um comando bash ou procurar um padrão — é uma viagem de ida e volta completa para a API do Claude. O Claude vê o estado atual de tudo, decide o que fazer a seguir, o motor executa e o Claude vê o resultado. Não há processamento em segundo plano nem Claude pensando enquanto as ferramentas executam. É uma sequência estrita: Claude decide, ferramenta executa, Claude vê resultado, Claude decide novamente.

A implicação que surpreende a maioria das pessoas: se o Claude lê dez arquivos para completar sua tarefa, são dez chamadas de API separadas, cada uma enviando o contexto acumulado completo. A décima chamada envia sua mensagem original mais o prompt do sistema mais os arquivos de memória mais os resultados de todas as nove chamadas de ferramentas anteriores. É por isso que tarefas longas consomem tantos tokens: o contexto cresce a cada passo e cada passo envia tudo.

Everything in Claude's context window is measured in tokens. A token is roughly 3–4 characters of text, not words or lines, but chunks of characters the model processes. Your message is tokens. Claude's responses are tokens. Every file it reads is tokens. Every bash command output is tokens. The entire conversation history from the moment you opened the session is tokens. The context window is the shared budget for all of it, and every step of the tool loop draws from that same budget.

Understanding the specific thresholds matters because they determine exactly what happens when the budget runs low. These aren't soft guidelines; they're hard-coded trigger points in the source. The auto-compaction fires at contextWindow − 13,000 tokens, roughly 87% full. This is intentional: the system needs room to write the summary itself, so it starts the compaction before the window is actually full. Once compaction runs, your session is summarized and continues, but you'll notice a qualitative shift in what Claude remembers.

The circuit-breaker is a lesser-known mechanism that prevents runaway generation. It fires when Claude has run three or more consecutive tool calls and the last two steps each generated fewer than 500 tokens of new content. In practice, this catches Claude spinning its wheels by making tiny, low-value tool calls in a loop. When it fires, Claude stops and surfaces the situation to you. The fix is simple: just say "continue." This resets the counter and Claude picks up where it left off. Knowing this exists means you'll never spend five minutes wondering what went wrong when Claude suddenly stops mid-task.

Tudo na janela de contexto do Claude é medido em tokens. Um token tem aproximadamente 3–4 caracteres de texto, não palavras ou linhas, mas pedaços de caracteres que o modelo processa. Sua mensagem são tokens. As respostas do Claude são tokens. Cada arquivo que ele lê são tokens. Cada saída de comando bash são tokens. Todo o histórico da conversa desde o momento em que você abriu a sessão são tokens. A janela de contexto é o orçamento compartilhado para tudo isso, e cada passo do loop de ferramentas retira do mesmo orçamento.

Entender os limites específicos importa porque eles determinam exatamente o que acontece quando o orçamento fica baixo. Esses não são guias suaves; são pontos de gatilho fixos no código-fonte. A compactação automática dispara em contextWindow − 13.000 tokens, aproximadamente 87% cheio. Isso é intencional: o sistema precisa de espaço para escrever o próprio resumo, então começa a compactação antes que a janela esteja realmente cheia. Quando a compactação executa, sua sessão é resumida e continua, mas você vai notar uma mudança qualitativa no que o Claude lembra.

O circuit-breaker é um mecanismo menos conhecido que previne geração descontrolada. Ele dispara quando o Claude executou três ou mais chamadas de ferramentas consecutivas e os últimos dois passos geraram menos de 500 tokens de conteúdo novo cada. Na prática, isso pega o Claude rodando em círculos ao fazer chamadas de ferramentas pequenas e de baixo valor em loop. Quando dispara, o Claude para e apresenta a situação para você. A correção é simples: apenas diga "continue." Isso reinicia o contador e o Claude retoma de onde parou. Saber que isso existe significa que você nunca vai passar cinco minutos se perguntando o que deu errado quando o Claude para de repente no meio de uma tarefa.

Before you send your first message, Claude Code has already done a surprising amount of work. The startup sequence takes a git snapshot of your repository: current branch, main branch name, user identity, the last 5 commits, and working tree status. All of this is fetched in parallel using the --no-optional-locks flag so it doesn't interfere with any lock files you might have. This snapshot becomes part of the system prompt, so Claude knows what branch you're on before you say a word.

There are two things about this snapshot that catch people off guard. First: it's memoized for the entire session. If you switch branches, commit new code, or stage files after the session starts, Claude doesn't know. Its mental model of your git state is frozen at startup time. If your working tree changes in ways that matter to your task, explicitly run git status or git diff via the Bash tool to give Claude a fresh, accurate picture mid-session.

Second: the git snapshot is hard-truncated at 2,000 characters. In a large repository with many branches, many recent commits with long messages, or a working tree with numerous changed files, that 2,000-character limit will silently cut off the snapshot. Claude won't know it's missing information; it'll just work with whatever fit. This is why, in large repositories, it's good practice to explicitly describe your current working context at the start of a session rather than assuming Claude already knows.

Antes de você enviar sua primeira mensagem, o Claude Code já fez uma quantidade surpreendente de trabalho. A sequência de inicialização tira um snapshot do git do seu repositório: branch atual, nome do branch principal, identidade do usuário, os últimos 5 commits e status da árvore de trabalho. Tudo isso é buscado em paralelo usando a flag --no-optional-locks para não interferir com arquivos de lock que você possa ter. Esse snapshot se torna parte do prompt do sistema, então o Claude sabe em qual branch você está antes de você dizer uma palavra.

Há duas coisas sobre esse snapshot que pegam as pessoas de surpresa. Primeiro: ele é guardado em cache para a sessão inteira. Se você trocar de branch, fazer commit de novo código ou fazer stage de arquivos depois que a sessão começa, o Claude não sabe. Seu modelo mental do estado do git está congelado no momento da inicialização. Se sua árvore de trabalho muda de maneiras que importam para sua tarefa, execute explicitamente git status ou git diff via ferramenta Bash para dar ao Claude uma visão atualizada e precisa no meio da sessão.

Segundo: o snapshot do git é truncado em 2.000 caracteres. Em um repositório grande com muitos branches, muitos commits recentes com mensagens longas ou uma árvore de trabalho com muitos arquivos modificados, esse limite de 2.000 caracteres vai silenciosamente cortar o snapshot. O Claude não vai saber que está faltando informação; vai apenas trabalhar com o que coube. É por isso que, em repositórios grandes, é uma boa prática descrever explicitamente seu contexto de trabalho atual no início de uma sessão, em vez de assumir que o Claude já sabe.

You start a new Claude Code session and carefully explain your entire project architecture. An hour later, after a compaction, Claude seems to have forgotten key details. Meanwhile, your colleague opens Claude in the same repo and it immediately knows the project conventions. What's going on? Claude Code has three completely different kinds of memory, and each one works differently, persists differently, and requires a different approach to use effectively.

Você inicia uma nova sessão do Claude Code e explica cuidadosamente toda a arquitetura do seu projeto. Uma hora depois, após uma compactação, o Claude parece ter esquecido detalhes importantes. Enquanto isso, seu colega abre o Claude no mesmo repositório e ele imediatamente conhece as convenções do projeto. O que está acontecendo? O Claude Code tem três tipos completamente diferentes de memória, e cada um funciona de forma diferente, persiste de forma diferente e requer uma abordagem diferente para ser usado com eficácia.

The first kind is in-session context: everything that's happened in the current conversation, including your messages, Claude's responses, and all tool results. This is the fastest and richest memory because it's right there in the context window, so Claude can refer back to anything from earlier in the session with perfect fidelity. The catch is that it's entirely ephemeral. Close the session and it's gone, and as we saw in Chapter 1, it's bounded by the context window; once that fills, the oldest content gets compressed away.

The second kind is CLAUDE.md files, which are persistent text files that live on disk and are loaded automatically at startup. These files survive across sessions, they're shareable with your team when committed to the repo, and they don't compete with your working context the way in-session conversation does. Think of them as the long-term memory that Claude brings into every session. The tradeoff is that they're static: Claude reads them at startup but doesn't automatically update them during a session unless you explicitly ask it to.

The third kind is the results from tool calls made during a session: the contents of files Claude has read, the output of commands it's run, the results of searches it's done. These get added to the context window as the session progresses. They're valuable because they represent Claude's active working knowledge of your specific files right now. But they're volatile: they live in the context, and when compaction happens, their specific details — exact line numbers, precise content — are often lost in the summary, even if the high-level conclusions survive.

O primeiro tipo é o contexto em sessão: tudo que aconteceu na conversa atual, incluindo suas mensagens, as respostas do Claude e todos os resultados de ferramentas. Essa é a memória mais rápida e mais rica porque está ali mesmo na janela de contexto, então o Claude pode se referir a qualquer coisa anterior da sessão com fidelidade perfeita. O problema é que ela é efêmera. Feche a sessão e ela some. E como vimos no Capítulo 1, ela é limitada pela janela de contexto: quando essa enche, o conteúdo mais antigo é comprimido.

O segundo tipo são os arquivos CLAUDE.md, que são arquivos de texto persistentes que vivem no disco e são carregados automaticamente na inicialização. Esses arquivos sobrevivem entre sessões, são compartilháveis com sua equipe quando commitados no repositório e não competem com seu contexto de trabalho da mesma forma que a conversa em sessão faz. Pense neles como a memória de longo prazo que o Claude traz para cada sessão. A contrapartida é que eles são estáticos: o Claude os lê na inicialização mas não os atualiza automaticamente durante uma sessão a menos que você peça explicitamente.

O terceiro tipo são os resultados das chamadas de ferramentas feitas durante uma sessão: o conteúdo de arquivos que o Claude leu, a saída de comandos que executou e os resultados de buscas que fez. Esses são adicionados à janela de contexto conforme a sessão progride. São valiosos porque representam o conhecimento de trabalho ativo do Claude sobre seus arquivos específicos agora mesmo. Mas são voláteis: vivem no contexto e quando a compactação acontece, seus detalhes específicos — números de linha exatos, conteúdo preciso — são frequentemente perdidos no resumo, mesmo que as conclusões de alto nível sobrevivam.

CLAUDE.md files are loaded via a scope cascade at startup. Claude Code looks in the repository root, then walks up through parent directories, and finally checks your user home directory at ~/.claude/CLAUDE.md. More specific files override broader ones when instructions conflict, which means your project-level CLAUDE.md can override your global preferences for that particular repo. This makes sense in practice: you might have a global preference for verbose explanations, but a specific project where brevity is king.

There's an effective size limit of 25KB for CLAUDE.md. Files under 25KB are loaded eagerly at startup and are always present. Files over that limit are loaded lazily, meaning Claude loads them only when it judges the content to be relevant to the current task. Large CLAUDE.md files don't actually guarantee that all their content is available in every session. If you have critical instructions, keep the file small and focused.

The question of what to put in CLAUDE.md comes down to one test: is this something you have to explain at the start of every new session? Project architecture decisions belong there. Coding conventions for this specific codebase belong there. The fact that you use PostgreSQL with Prisma and that the connection string format is non-obvious belongs there. What doesn't belong: information that changes frequently (current sprint goals, ticket numbers), secrets (connection strings with passwords), or huge lists of files (Claude can find files; it doesn't need a map).

Os arquivos CLAUDE.md são carregados via uma cascata de escopos na inicialização. O Claude Code procura na raiz do repositório, depois sobe pelos diretórios pai e finalmente verifica seu diretório home de usuário em ~/.claude/CLAUDE.md. Arquivos mais específicos substituem os mais amplos quando as instruções conflitam, o que significa que seu CLAUDE.md do nível do projeto pode substituir suas preferências globais para aquele repositório específico. Faz sentido na prática: você pode ter uma preferência global por explicações detalhadas, mas um projeto específico onde a brevidade é fundamental.

Existe um limite de tamanho efetivo de 25KB para o CLAUDE.md. Arquivos abaixo de 25KB são pré-carregados na inicialização e estão sempre presentes. Arquivos acima desse limite são carregados de forma lazy, ou seja, o Claude os carrega apenas quando julga que o conteúdo é relevante para a tarefa atual. Arquivos CLAUDE.md grandes não garantem que todo o seu conteúdo esteja disponível em cada sessão. Se você tem instruções críticas, mantenha o arquivo pequeno e focado.

A questão do que colocar no CLAUDE.md se resume a um teste: isso é algo que você tem que explicar no início de cada nova sessão? Decisões de arquitetura do projeto têm lugar aqui. Convenções de codificação para essa base de código específica também. O fato de que você usa PostgreSQL com Prisma e que o formato da string de conexão não é óbvio também. O que não vai aqui: informações que mudam frequentemente (objetivos do sprint atual, números de ticket), segredos (strings de conexão com senhas) ou listas enormes de arquivos (o Claude pode encontrar arquivos; ele não precisa de um mapa).

When auto-compaction runs at roughly 87% context, it uses up to 20,000 output tokens to summarize everything that's happened in the session. That sounds like a lot, since 20,000 tokens is roughly 15,000 words of text. But a long working session can generate far more content than that, so the summarizer has to make choices about what to keep and what to discard.

What survives compaction: high-level decisions, architecture choices, named files and their roles, explicit conclusions you've stated, and the general direction of the work. The summarizer is good at preserving "what we decided" content. What gets lost: exact tool output (the specific lines of code that were in that file), intermediate reasoning steps that didn't lead to a conclusion, specific line numbers from earlier references, and the fine-grained back-and-forth of problem-solving.

The strategic implication is important: if something matters, state it explicitly as a conclusion before you move on. Don't just let Claude figure it out from context. Say "We've decided to use event sourcing for the audit log because replay capability is a hard requirement." That kind of declarative statement is exactly what the summarizer preserves. A five-second habit of explicit conclusions will save you the frustration of Claude seeming to forget important decisions after a compaction.

Quando a compactação automática executa em ~87% de contexto, ela usa até 20.000 tokens de saída para resumir tudo que aconteceu na sessão. Isso parece muito, já que 20.000 tokens é aproximadamente 15.000 palavras de texto. Mas uma sessão de trabalho longa pode gerar muito mais conteúdo do que isso, então o processo de resumo tem que fazer escolhas sobre o que manter e o que descartar.

O que sobrevive à compactação: decisões de alto nível, escolhas de arquitetura, arquivos nomeados e seus papéis, conclusões explícitas que você declarou e a direção geral do trabalho. O processo de resumo é bom em preservar o conteúdo de "o que decidimos". O que se perde: conteúdo exato de saída de ferramentas (as linhas específicas de código que estavam naquele arquivo), passos intermediários de raciocínio que não levaram a uma conclusão, números de linha específicos de referências anteriores e o vai-e-vem detalhado da resolução de problemas.

A implicação estratégica é importante: se algo importa, declare-o explicitamente como conclusão antes de seguir em frente. Não deixe o Claude apenas descobrir pelo contexto. Diga "Decidimos usar event sourcing para o log de auditoria porque a capacidade de replay é um requisito obrigatório." Esse tipo de declaração explícita é exatamente o que o processo de resumo preserva. Um hábito de cinco segundos de conclusões explícitas vai te poupar da frustração de o Claude parecer esquecer decisões importantes após uma compactação.

You ask Claude to read a large log file to find an error. It seems to succeed, but its answer is wrong. The file had 50,000 lines. What actually happened? Understanding the tool system — not just what tools exist, but how they work mechanically — is the difference between trusting Claude's tool results and knowing when to verify them.

Você pede ao Claude para ler um arquivo de log grande para encontrar um erro. Parece que funciona, mas a resposta está errada. O arquivo tinha 50.000 linhas. O que realmente aconteceu? Entender o sistema de ferramentas — não apenas quais ferramentas existem, mas como elas funcionam mecanicamente — é a diferença entre confiar nos resultados das ferramentas do Claude e saber quando verificá-los.

Tools are not magic. They're structured function calls: Claude (the language model) requests a tool call by name and with specific arguments, the Claude Code host process intercepts that request, executes the corresponding operation, and appends the result to the conversation context. From Claude's perspective, it asked for something and got an answer. From your computer's perspective, a specific piece of code ran with specific inputs and produced a specific output.

This distinction matters because it means Claude doesn't run code. It requests code to be run and reasons about the result. Claude has no direct access to your filesystem, your shell, or your network; all of those things are mediated through the tool layer. When Claude reads a file, it's asking the host process to read the file and hand it the content. When Claude runs a bash command, it's asking the host process to spawn a shell, run the command, capture the output, and hand it back. Claude reasons about results rather than producing them.

The available tools break into categories by what they do. Read, Write, Edit, and Glob deal with the filesystem directly. Bash gives Claude access to your shell environment. Grep provides fast content search without reading entire files. WebSearch and WebFetch connect to the internet. Agent spawns sub-agents for parallel work (covered in Chapter 8). MCP tools are extensions that you or your organization define, which are custom operations that Claude can call exactly like built-in tools. Each tool produces a result that gets appended to context, and each result counts against the context budget.

Ferramentas não são mágica. São chamadas de função estruturadas: o Claude (o modelo de linguagem) solicita uma chamada de ferramenta pelo nome e com argumentos específicos, o processo host do Claude Code intercepta essa solicitação, executa a operação correspondente e anexa o resultado ao contexto da conversa. Da perspectiva do Claude, ele pediu algo e recebeu uma resposta. Da perspectiva do seu computador, um pedaço específico de código executou com entradas específicas e produziu uma saída específica.

Essa distinção importa porque significa que o Claude não executa código. Ele solicita que código seja executado e raciocina sobre o resultado. O Claude não tem acesso direto ao seu sistema de arquivos, ao seu shell ou à sua rede; todas essas coisas são mediadas pela camada de ferramentas. Quando o Claude lê um arquivo, ele está pedindo ao processo host para ler o arquivo e entregar o conteúdo. Quando o Claude executa um comando bash, ele está pedindo ao processo host para criar um shell, executar o comando, capturar a saída e entregá-la de volta. O Claude raciocina sobre resultados em vez de produzi-los.

As ferramentas disponíveis se dividem em categorias pelo que fazem. Read, Write, Edit e Glob lidam com o sistema de arquivos diretamente. Bash dá ao Claude acesso ao seu ambiente de shell. Grep fornece busca rápida de conteúdo sem ler arquivos inteiros. WebSearch e WebFetch conectam-se à internet. Agent cria sub-agentes para trabalho paralelo (abordado no Capítulo 8). Ferramentas MCP são extensões que você ou sua organização definem, sendo operações customizadas que o Claude pode chamar exatamente como ferramentas embutidas. Cada ferramenta produz um resultado que é anexado ao contexto e cada resultado conta contra o orçamento de contexto.

Every tool result has a hard cap of 100KB per result. When a file or command output exceeds 100KB, it is truncated at that boundary and the truncated content is what gets added to context. This is not an error: Claude receives no error message, it doesn't know the content was truncated, and it simply sees what fit within the limit and reasons as if that's the complete content.

This is why reading a large log file gives wrong results. A 50,000-line log file is almost certainly larger than 100KB. Claude reads the first roughly 100KB, finds no error in that portion, and concludes the error isn't there (or offers something plausible based on partial content). The fix isn't to read more carefully; it's to pre-filter before reading. Use grep via Bash to extract the relevant lines first, then read those. Or use the Grep tool directly, which is designed to return targeted results rather than full file contents. Never read large files raw when you're looking for specific information.

The 100KB limit applies per tool call result, not per file. You can work around it for some cases by reading a file in chunks: read lines 1–500, then 501–1000, and so on. But for log files and command output, filtering is almost always the right answer. Claude can tell you what grep pattern to use, so you don't have to figure it out yourself. Just ask: "What grep command should I run to find the relevant error lines in this log file?"

Cada resultado de ferramenta tem um limite fixo de 100KB por resultado. Quando um arquivo ou saída de comando excede 100KB, ele é truncado nesse limite e o conteúdo truncado é o que é adicionado ao contexto. Isso não é um erro: o Claude não recebe mensagem de erro, ele não sabe que o conteúdo foi truncado e simplesmente vê o que coube dentro do limite, raciocinando como se esse fosse o conteúdo completo.

É por isso que ler um arquivo de log grande dá resultados errados. Um arquivo de log com 50.000 linhas quase certamente é maior que 100KB. O Claude lê os primeiros ~100KB, não encontra erro nessa porção e conclui que o erro não está lá (ou sugere algo plausível baseado em conteúdo parcial). A correção não é ler com mais cuidado; é pré-filtrar antes de ler. Use grep via Bash para extrair as linhas relevantes primeiro, depois leia essas. Ou use a ferramenta Grep diretamente, que é projetada para retornar resultados direcionados em vez do conteúdo completo do arquivo. Nunca leia arquivos grandes crus quando você está procurando informação específica.

O limite de 100KB se aplica por resultado de chamada de ferramenta, não por arquivo. Você pode contornar isso para alguns casos lendo um arquivo em pedaços: leia as linhas 1–500, depois 501–1000, e assim por diante. Mas para arquivos de log e saída de comando, filtrar é quase sempre a resposta certa. O Claude pode te dizer qual padrão de grep usar, então você não precisa descobrir sozinho. Apenas pergunte: "Qual comando grep devo executar para encontrar as linhas de erro relevantes neste arquivo de log?"

The Bash tool doesn't give Claude unlimited shell access. It runs through a security layer that checks every command against the permission system before executing it. The details of that permission system are covered in Chapter 4, but there are two things about the Bash tool specifically that are useful to know now, independent of permissions.

First: Bash commands have a default timeout. Long-running commands — building large projects, running a full test suite, waiting for a server to start — will be interrupted when they exceed the timeout. The default is configurable via the BASH_DEFAULT_TIMEOUT_MS environment variable, and there's a maximum ceiling at BASH_MAX_TIMEOUT_MS. If Claude is running a command and it seems to have stopped producing output, a timeout is the likely culprit. Claude can request an extended timeout for specific commands, and you'll see it pass a timeout parameter when it does so.

Second: not all bash operations are equally efficient. Read, Grep, and Glob have dedicated native implementations that use an indexed file registry, making them fast and nearly free in terms of overhead. When Claude uses the Bash tool to run find or grep instead of using the native tools, it's slower and more expensive. If you notice Claude using shell-based file search when it could use the dedicated Glob or Grep tools, gently suggest the native tool instead. It's not a big deal in isolation, but it adds up in long sessions.

A ferramenta Bash não dá ao Claude acesso irrestrito ao shell. Ela passa por uma camada de segurança que verifica cada comando contra o sistema de permissões antes de executá-lo. Os detalhes desse sistema de permissões são abordados no Capítulo 4, mas há duas coisas sobre a ferramenta Bash especificamente que são úteis de saber agora, independentemente das permissões.

Primeiro: comandos Bash têm um timeout padrão. Comandos de longa duração — construir projetos grandes, executar uma suíte de testes completa ou esperar um servidor iniciar — serão interrompidos quando excederem o timeout. O timeout padrão é configurável via variável de ambiente BASH_DEFAULT_TIMEOUT_MS, e há um teto máximo em BASH_MAX_TIMEOUT_MS. Se o Claude está executando um comando e parece ter parado de produzir saída, um timeout é o culpado mais provável. O Claude pode solicitar um timeout estendido para comandos específicos, e você vai vê-lo passar um parâmetro de timeout quando fizer isso.

Segundo: nem todas as operações bash são igualmente eficientes. Read, Grep e Glob têm implementações nativas dedicadas que usam um registro de arquivos indexado, sendo rápidas e quase gratuitas em termos de overhead. Quando o Claude usa a ferramenta Bash para executar find ou grep em vez de usar as ferramentas nativas, é mais lento e mais caro. Se você notar o Claude usando busca de arquivos baseada em shell quando poderia usar as ferramentas dedicadas Glob ou Grep, sugira suavemente que ele use a ferramenta nativa. Não é grande coisa isoladamente, mas se acumula em sessões longas.

You're running Claude in auto-approve mode on a cleanup task. You step away for coffee. When you come back, it has deleted files you didn't intend to delete. Or the opposite: you have auto-approve turned off for safety, but it keeps prompting you for permission on commands that are obviously safe, and you're clicking "yes" dozens of times per session. Both problems come from the same root cause: not understanding how the permission system actually decides what to ask about and what to just do.

Você está executando o Claude no modo de aprovação automática em uma tarefa de limpeza. Você sai para tomar um café. Quando volta, ele deletou arquivos que você não pretendia deletar. Ou o oposto: você tem a aprovação automática desligada por segurança, mas ele continua pedindo permissão para comandos que são obviamente seguros, e você está clicando "sim" dezenas de vezes por sessão. Ambos os problemas vêm da mesma causa raiz: não entender como o sistema de permissões realmente decide sobre o que perguntar e o que simplesmente fazer.

Every tool call Claude wants to make passes through five evaluation layers, checked in order from most restrictive to most permissive. The first layer that produces a definitive answer wins, and higher layers cannot be overridden by lower ones. Understanding this order is the key to both understanding why Claude gets blocked when you don't expect it and how to configure things so it doesn't.

Layer 1 is hardcoded blocks: things that are never allowed, regardless of any setting you change. These include operations like writing to system directories, deleting the root filesystem, and other operations where the damage potential is so high that no user configuration should be able to enable them. You can't override these, and you shouldn't want to. Layer 2 is your user-level settings at ~/.claude/settings.json, which are your global personal rules that apply in every Claude Code session on your machine. Layer 3 is project-level settings at .claude/settings.json in the repo. These apply only to sessions opened in that project and can be committed so the whole team shares them.

Layer 4 is session grants: permissions you've explicitly granted during the current session by answering "yes" to a permission prompt. These are ephemeral; they last for the session and disappear when you close it. Layer 5 is the auto-approval classifier, which uses pattern matching and ML heuristics to decide whether a command is safe enough to approve without asking. This is the layer that handles the obviously safe cases — running tests, reading files, linting code — without bothering you every time.

Cada chamada de ferramenta que o Claude quer fazer passa por cinco camadas de avaliação, verificadas em ordem da mais restritiva para a mais permissiva. A primeira camada que produz uma resposta definitiva vence, e camadas superiores não podem ser substituídas por camadas inferiores. Entender essa ordem explica por que o Claude é bloqueado quando você não espera — e como configurar as coisas para evitar que isso aconteça.

A Camada 1 são bloqueios fixos: coisas que nunca são permitidas, independentemente de qualquer configuração que você mude. Isso inclui operações como escrever em diretórios do sistema, deletar o sistema de arquivos raiz e outras operações onde o potencial de dano é tão alto que nenhuma configuração do usuário deveria poder habilitá-las. Você não pode substituir essas regras e não deveria querer. A Camada 2 são suas configurações de nível de usuário em ~/.claude/settings.json, que são suas regras pessoais globais aplicadas em todas as sessões do Claude Code na sua máquina. A Camada 3 são configurações de nível de projeto em .claude/settings.json no repositório. Essas se aplicam apenas a sessões abertas naquele projeto e podem ser commitadas para que toda a equipe as compartilhe.

A Camada 4 são concessões de sessão: permissões que você concedeu explicitamente durante a sessão atual respondendo "sim" a um prompt de permissão. Essas são efêmeras; duram pela sessão e desaparecem quando você a fecha. A Camada 5 é o classificador de aprovação automática, que usa correspondência de padrões e heurísticas de ML para decidir se um comando é seguro o suficiente para aprovar sem perguntar. Essa é a camada que lida com os casos obviamente seguros — executar testes, ler arquivos, fazer lint do código — sem incomodar você toda vez.

The auto-approval classifier handles the bulk of everyday Claude Code operations. It combines pattern matching with ML judgment to categorize every command Claude wants to run before it runs. The classifier is deliberately conservative, designed to have far more false positives (asking when it doesn't need to) than false negatives (approving when it shouldn't). A false positive costs you a click; a false negative can cost you a file.

The patterns that reliably get auto-approved are read-only operations and conventional development workflows: reading files, running your test suite, running your linter, building the project. These are things that produce output but don't permanently alter system state in dangerous ways. The patterns that reliably trigger confirmation prompts are deletes, writes to paths outside the project directory, network calls, system state changes (installing packages, changing system config), and anything involving pipes and redirections that obscure what's really happening.

One useful mental model: the classifier asks "if this goes wrong, can it be undone?" Read-only operations always pass. Operations that make local, reversible changes often pass. Operations that could be irreversible or that reach outside the project boundary are much more likely to prompt. This isn't a perfect model of the classifier's actual logic, but it's accurate enough to predict its behavior in most situations.

O classificador de aprovação automática lida com a maior parte das operações cotidianas do Claude Code. Ele combina correspondência de padrões com julgamento de ML para categorizar cada comando que o Claude quer executar antes de executá-lo. O classificador é deliberadamente conservador, projetado para ter muito mais falsos positivos (perguntar quando não precisa) do que falsos negativos (aprovar quando não deveria). Um falso positivo te custa um clique; um falso negativo pode te custar um arquivo.

Os padrões que confiavelmente obtêm aprovação automática são operações somente leitura e fluxos de trabalho de desenvolvimento convencionais: ler arquivos, executar sua suíte de testes, executar seu linter e construir o projeto. São coisas que produzem saída mas não alteram permanentemente o estado do sistema de formas perigosas. Os padrões que confiavelmente disparam prompts de confirmação são exclusões, escritas em caminhos fora do diretório do projeto, chamadas de rede, mudanças de estado do sistema (instalar pacotes, mudar configuração do sistema) e qualquer coisa envolvendo pipes e redirecionamentos que obscurecem o que está realmente acontecendo.

Um modelo mental útil: o classificador pergunta "se isso der errado, pode ser desfeito?" Operações somente leitura sempre passam. Operações que fazem mudanças locais e reversíveis frequentemente passam. Operações que poderiam ser irreversíveis ou que alcançam fora do limite do projeto são muito mais propensas a gerar prompts. Esse não é um modelo perfeito da lógica real do classificador, mas é preciso o suficiente para prever seu comportamento na maioria das situações.

The two settings files, ~/.claude/settings.json (global) and .claude/settings.json (project), let you encode your preferences permanently rather than answering prompts every session. The most useful fields for day-to-day work are allowedTools and blockedTools. allowedTools contains a list of tool calls that should always be auto-approved without prompting in this context. blockedTools contains tool calls that should never run; Claude will be told it doesn't have access to those tools.

For a JavaScript project, for example, you might add Bash(npm test) and Bash(npm run lint) to the project-level allowedTools. Now Claude can run your tests and lint your code without any prompts, every session, for everyone on the team who uses the project settings. You've encoded your judgment once and stopped answering the same question repeatedly. The granularity goes down to specific commands, so you're not opening up all Bash access, just the specific operations you've decided are safe.

The project settings file is worth committing to your repository. It makes Claude Code immediately configured correctly for any team member who clones the repo. Think of it like .eslintrc or .prettierrc: it encodes team conventions so individuals don't have to configure things manually. Combined with a well-written CLAUDE.md, a good .claude/settings.json makes Claude Code feel like it was custom-built for your specific project from the first session.

Os dois arquivos de configuração, ~/.claude/settings.json (global) e .claude/settings.json (projeto), permitem que você codifique suas preferências permanentemente em vez de responder a prompts em cada sessão. Os campos mais úteis para o trabalho diário são allowedTools e blockedTools. allowedTools contém uma lista de chamadas de ferramentas que sempre devem ser aprovadas automaticamente sem prompt neste contexto. blockedTools contém chamadas de ferramentas que nunca devem executar; o Claude será informado de que não tem acesso a essas ferramentas.

Para um projeto JavaScript, por exemplo, você pode adicionar Bash(npm test) e Bash(npm run lint) ao allowedTools de nível de projeto. Agora o Claude pode executar seus testes e fazer lint do seu código sem nenhum prompt, em cada sessão, para todos na equipe que usam as configurações do projeto. Você codificou seu julgamento uma vez e parou de responder a mesma pergunta repetidamente. A granularidade vai até comandos específicos, então você não está abrindo todo o acesso Bash, apenas as operações específicas que você decidiu serem seguras.

O arquivo de configurações do projeto vale a pena commitar no seu repositório. Ele faz o Claude Code ser imediatamente configurado corretamente para qualquer membro da equipe que clonar o repositório. Pense nisso como .eslintrc ou .prettierrc: codifica convenções da equipe para que os indivíduos não tenham que configurar coisas manualmente. Combinado com um CLAUDE.md bem escrito, um bom .claude/settings.json faz o Claude Code parecer que foi construído sob medida para o seu projeto específico desde a primeira sessão.

You've been working with Claude for two hours on a large refactor. The work is going well. Then, without warning, Claude's responses start getting slightly vaguer. It's still helpful, but it seems to have lost some of the fine-grained context from earlier. What happened, and could you have prevented it? Yes, almost certainly. Long session management is one of the highest-leverage skills in Claude Code, and it's almost entirely about understanding the compaction math before it happens to you.

Você está trabalhando com o Claude por duas horas em um grande refactor. O trabalho está indo bem. Então, sem aviso, as respostas do Claude começam a ficar ligeiramente mais vagas. Ainda é útil, mas parece ter perdido parte do contexto minucioso de antes. O que aconteceu — e dava para ter evitado? Quase certamente. O gerenciamento de sessões longas é uma das habilidades de maior impacto no Claude Code, e é quase inteiramente sobre entender a matemática da compactação antes que ela aconteça com você.

Auto-compaction triggers at contextWindow − 13,000 tokens, roughly 87% of the available context. The 13,000-token buffer isn't arbitrary: the compaction process itself needs to write a summary, and that summary can be up to 20,000 tokens long (in practice it almost never exceeds 17,000). If compaction triggered at 100%, there'd be no room to write the summary, so the system starts early, leaving room for the summarizer to do its job.

Understanding the 87% trigger is useful because it means you can predict roughly when compaction will happen in a long session. A 200K context model (like Claude 3.5 Sonnet) will auto-compact around 187,000 tokens. If your session is generating tokens at a steady rate, say 2,000 tokens per exchange, you have roughly 93 exchanges before compaction hits. That sounds like a lot, but a session with heavy file reading and bash output can burn through context much faster than conversational exchanges.

The most important thing to understand about compaction is that you should not wait for it to happen automatically. The auto-compaction trigger is a safety net, not a recommended workflow. When you let it happen automatically, the timing is determined by the context rather than by you, and it might fire in the middle of a complex operation at the worst possible moment for continuity. Use the /compact command to compact manually at natural breakpoints: end of a feature, end of a debugging session, before switching to a different area of the codebase. When you compact on your terms, you can prime the summary with the context you care about preserving.

A compactação automática dispara em contextWindow − 13.000 tokens, aproximadamente 87% do contexto disponível. O buffer de 13.000 tokens não é arbitrário: o processo de compactação em si precisa escrever um resumo, e esse resumo pode ter até 20.000 tokens de comprimento (na prática quase nunca passa de 17.000). Se a compactação disparasse a 100%, não haveria espaço para escrever o resumo, então o sistema começa cedo, deixando espaço para o processo de resumo fazer seu trabalho.

Entender o gatilho de 87% é útil porque significa que você pode prever aproximadamente quando a compactação acontecerá em uma sessão longa. Um modelo com contexto de 200K (como o Claude 3.5 Sonnet) vai compactar automaticamente em torno de 187.000 tokens. Se sua sessão está gerando tokens a uma taxa constante, digamos 2.000 tokens por troca, você tem aproximadamente 93 trocas antes da compactação atingir. Isso parece muito, mas uma sessão com leitura pesada de arquivos e saída de bash pode queimar contexto muito mais rápido do que trocas conversacionais.

A coisa mais importante para entender sobre compactação é que você não deve esperar ela acontecer automaticamente. O gatilho de compactação automática é uma rede de segurança, não um fluxo de trabalho recomendado. Quando você deixa acontecer automaticamente, quem decide o momento é o contexto, não você, e pode disparar no meio de uma operação complexa no pior momento possível para continuidade. Use o comando /compact para compactar manualmente em pontos de interrupção naturais: fim de uma funcionalidade, fim de uma sessão de depuração ou antes de mudar para uma área diferente da base de código. Quando você compacta nos seus termos, pode preparar o resumo com o contexto que você se importa em preservar.

Prompt caching is an Anthropic API feature that Claude Code uses automatically. When a request's prefix (the beginning of the context) exactly matches a recent request, the cached tokens cost roughly one-tenth of normal input token pricing. In a long session where you're sending dozens of messages with a growing shared prefix (system prompt, conversation history), cache hits translate directly into lower costs and often faster responses.

The cache key is the system prompt plus the first N messages of the conversation, which is the stable prefix that hasn't changed since the last request. As long as you keep sending messages without changing the prefix, cache hits accumulate. The cache TTL is approximately five minutes: if you go quiet for five minutes without sending a message, the cache may expire and your next message will need to re-warm it. In practice, this means an active coding session stays cached, while a session where you periodically step away will re-warm periodically.

The biggest cache-breaker that developers run into is editing CLAUDE.md mid-session. Since CLAUDE.md content is part of the system prompt, any edit to it changes the system prompt, which invalidates the cache key and forces a full re-computation on the next request. One small CLAUDE.md edit mid-session means you lose the cache for the rest of the session. The rule of thumb is simple: edit your CLAUDE.md before you start the session, not during. If you discover something that needs to be captured in CLAUDE.md while working, note it somewhere and update the file after the session ends.

O cache de prompt é um recurso da API da Anthropic que o Claude Code usa automaticamente. Quando o prefixo de uma requisição (o início do contexto) corresponde exatamente a uma requisição recente, os tokens em cache custam aproximadamente um décimo do preço normal de tokens de entrada. Em uma sessão longa onde você está enviando dezenas de mensagens com um prefixo compartilhado crescente (prompt do sistema, histórico da conversa), as ocorrências de cache se traduzem diretamente em custos mais baixos e frequentemente respostas mais rápidas.

A chave de cache é o prompt do sistema mais as primeiras N mensagens da conversa, que é o prefixo estável que não mudou desde a última requisição. Contanto que você continue enviando mensagens sem mudar o prefixo, as ocorrências de cache se acumulam. O TTL do cache é de aproximadamente cinco minutos: se você ficar quieto por cinco minutos sem enviar uma mensagem, o cache pode expirar e sua próxima mensagem precisará aquecê-lo novamente. Na prática, isso significa que uma sessão de codificação ativa permanece em cache, enquanto sessões com pausas longas perdem o cache e precisam reaquecer.

O maior destruidor de cache que os desenvolvedores encontram é editar o CLAUDE.md no meio de uma sessão. Como o conteúdo do CLAUDE.md faz parte do prompt do sistema, qualquer edição nele muda o prompt do sistema, o que invalida a chave de cache e força um recálculo completo na próxima requisição. Uma pequena edição no CLAUDE.md no meio de uma sessão significa que você perde o cache pelo resto da sessão. A regra prática é simples: edite seu CLAUDE.md antes de iniciar a sessão, não durante. Se você descobrir algo que precisa ser capturado no CLAUDE.md durante o trabalho, anote em algum lugar e atualize o arquivo depois que a sessão terminar.

A well-designed long session follows a simple rhythm: work in focused phases, compact at the end of each phase, and restate the current goal at the start of each new phase. This rhythm means you're always working in a clean context with just the right amount of history, the summarizer sees a natural stopping point with a clear set of conclusions, and the next phase starts with a crisp statement of what you're doing next.

At the start of a session, especially one you're continuing from earlier work, explicitly state the current state. Don't assume Claude picked up everything from the CLAUDE.md. Say: "We're working on the payment service. We've already completed the Stripe webhook handler (in services/stripe/webhook.ts). Next, we need to implement the refund flow." This costs you thirty seconds and saves Claude potentially many tool calls re-orienting itself. It also primes any future compaction summary with accurate, explicit current state.

For very long tasks that span multiple days or multiple sessions, treat each session as a discrete unit with an explicit handoff. At the end of a session, ask Claude to write a handoff note: what was accomplished, what decisions were made, and what the next steps are. Paste that handoff note at the start of the next session. It's a manual version of what CLAUDE.md does automatically, optimized for the specific in-progress state of an ongoing task. Combined with a well-maintained CLAUDE.md, this pattern makes multi-session work almost seamless.

Uma sessão longa bem projetada segue um ritmo simples: trabalhe em fases focadas, compacte ao final de cada fase e reafirme o objetivo atual no início de cada nova fase. Esse ritmo significa que você está sempre trabalhando em um contexto limpo com a quantidade certa de histórico, o processo de resumo encontra um ponto de parada natural com um conjunto claro de conclusões e a próxima fase começa com uma declaração nítida do que você está fazendo a seguir.

No início de uma sessão, especialmente uma que você está continuando de um trabalho anterior, declare explicitamente o estado atual. Não assuma que o Claude pegou tudo do CLAUDE.md. Diga: "Estamos trabalhando no serviço de pagamento. Já concluímos o handler de webhook do Stripe (em services/stripe/webhook.ts). A seguir, precisamos implementar o fluxo de reembolso." Isso custa trinta segundos e evita que o Claude gaste chamadas de ferramentas se reorientando. Também prepara qualquer resumo de compactação futuro com estado atual preciso e explícito.

Para tarefas muito longas que abrangem vários dias ou várias sessões, trate cada sessão como uma unidade discreta com um handoff explícito. No final de uma sessão, peça ao Claude para escrever uma nota de handoff: o que foi realizado, quais decisões foram tomadas e quais são os próximos passos. Cole essa nota de handoff no início da próxima sessão. É uma versão manual do que o CLAUDE.md faz automaticamente, otimizada para o estado específico em andamento de uma tarefa contínua. Combinado com um CLAUDE.md bem mantido, esse padrão torna o trabalho em múltiplas sessões quase contínuo.

Every time you start a new Claude Code session for your project, you spend the first few minutes explaining the same things: "We use conventional commits. We never commit directly to main. Our test command is npm run test:unit. The database is PostgreSQL and we use Prisma." Wouldn't it be great if Claude just knew all of that already? Skills are exactly that mechanism: reusable, automatically-loaded instruction sets that give Claude project or task-specific expertise from the moment a session starts.

Toda vez que você inicia uma nova sessão do Claude Code para o seu projeto, você passa os primeiros minutos explicando as mesmas coisas: "Usamos conventional commits. Nunca commitamos diretamente na main. Nosso comando de teste é npm run test:unit. O banco de dados é PostgreSQL e usamos Prisma." Não seria ótimo se o Claude já soubesse tudo isso? Skills são exatamente esse mecanismo: conjuntos de instruções reutilizáveis e carregados automaticamente que dão ao Claude expertise específica de projeto ou tarefa desde o momento em que a sessão começa.

A skill is a Markdown file with YAML frontmatter. The frontmatter provides a name and a description, and the body contains the actual instructions. Skills live in one of two places: ~/.claude/skills/ for personal skills that apply everywhere, or .claude/skills/ inside a repository for project-specific skills that your whole team shares. When Claude starts a session, it scans the available skills and their descriptions to decide which ones are relevant to the current task.

The description field is the activation trigger. Claude reads every skill's description and compares it against the current request. If a skill's description matches what you're trying to do, that skill gets loaded into context and Claude follows its instructions. A well-written description is specific and action-oriented: "Use when writing or reviewing database migration files using Prisma" will activate reliably when you're working with Prisma migrations. "Database stuff" will match almost everything and almost nothing, depending on Claude's judgment.

Think of a skill like a recipe card. You write the recipe once — the ingredients, the steps, the tricky bits — and whenever Claude is about to cook that dish, it reads the card first. The recipe card doesn't need to be in the conversation or in CLAUDE.md; it just needs to exist in the skills directory with a good description, and Claude will find it when it's relevant. This is the key advantage over CLAUDE.md: skills are lazy-loaded, so they only consume context when they're actually needed.

Uma skill é um arquivo Markdown com frontmatter YAML. O frontmatter fornece um nome e uma descrição, e o corpo contém as instruções reais. Skills ficam em um de dois lugares: ~/.claude/skills/ para skills pessoais que se aplicam em todo lugar, ou .claude/skills/ dentro de um repositório para skills específicas de projeto que toda a sua equipe compartilha. Quando o Claude inicia uma sessão, ele verifica as skills disponíveis e suas descrições para decidir quais são relevantes para a tarefa atual.

O campo de descrição é o gatilho de ativação. O Claude lê a descrição de cada skill e a compara com a solicitação atual. Se a descrição de uma skill corresponde ao que você está tentando fazer, essa skill é carregada no contexto e o Claude segue suas instruções. Uma descrição bem escrita é específica e orientada a ação: "Use ao escrever ou revisar arquivos de migração de banco de dados usando Prisma" vai ativar confiavelmente quando você está trabalhando com migrações Prisma. "Coisas de banco de dados" vai corresponder a quase tudo e quase nada, dependendo do julgamento do Claude.

Pense em uma skill como um cartão de receita. Você escreve a receita uma vez — os ingredientes, os passos, as partes complicadas — e sempre que o Claude está prestes a cozinhar esse prato, ele lê o cartão primeiro. O cartão de receita não precisa estar na conversa nem no CLAUDE.md; só precisa existir no diretório de skills com uma boa descrição, e o Claude vai encontrá-la quando for relevante. Essa é a vantagem chave sobre o CLAUDE.md: skills são carregadas de forma lazy, então consomem contexto apenas quando são realmente necessárias.

Skills are not loaded at startup like CLAUDE.md files. They're evaluated lazily: Claude first sees only the skill names and their description fields (the frontmatter), not the full body. Based on the descriptions, Claude decides which skills are relevant to the current task and loads only those. This means you can have a large library of skills without worrying about context bloat, because skills that don't apply to the current task simply don't consume any context tokens.

Once a skill is loaded, it stays loaded for the rest of the session. If you're working on database migrations and the migration skill loads, it will remain in context even if you switch to a different task mid-session. This is generally the right behavior, since once Claude has expertise for a topic, it keeps it. But it also means that in very long sessions with many different task types, the accumulated loaded skills can start to consume meaningful context. This is another reason to compact at natural breakpoints: a fresh phase starts with only the skills that are actually relevant.

Skills are also inherited by sub-agents in multi-agent scenarios (covered in Chapter 8). When the coordinator spawns a worker, the worker inherits the loaded skills from the parent session. This means your project conventions — your commit message format, your test patterns, your code style rules — flow naturally into parallel sub-tasks without you having to think about it. Write the skill once, and it applies everywhere, including in agent subtasks.

Skills não são carregadas na inicialização como arquivos CLAUDE.md. Elas são avaliadas de forma lazy: o Claude primeiro vê apenas os nomes das skills e seus campos de descrição (o frontmatter), não o corpo completo. Com base nas descrições, o Claude decide quais skills são relevantes para a tarefa atual e carrega apenas essas. Isso significa que você pode ter uma grande biblioteca de skills sem se preocupar com inchaço de contexto, porque skills que não se aplicam à tarefa atual simplesmente não consomem tokens de contexto.

Uma vez que uma skill é carregada, ela permanece carregada pelo resto da sessão. Se você está trabalhando em migrações de banco de dados e a skill de migração carrega, ela permanecerá no contexto mesmo se você mudar para uma tarefa diferente no meio da sessão. Esse é geralmente o comportamento certo, já que uma vez que o Claude tem expertise para um tópico, ele a mantém. Mas também significa que em sessões muito longas com muitos tipos diferentes de tarefas, as skills carregadas acumuladas podem começar a consumir contexto significativo. Essa é outra razão para compactar em pontos de interrupção naturais: uma nova fase começa com apenas as skills que são realmente relevantes.

Skills também são herdadas por sub-agentes em cenários multi-agente (abordado no Capítulo 8). Quando o coordenador cria um trabalhador, o trabalhador herda as skills carregadas da sessão pai. Isso significa que as convenções do seu projeto — seu formato de mensagem de commit, seus padrões de teste e suas regras de estilo de código — fluem naturalmente para subtarefas paralelas sem você ter que pensar sobre isso. Escreva a skill uma vez, e ela se aplica em todo lugar, incluindo em subtarefas de agentes.

The most common mistake when writing skills is being too broad. A skill called "Project conventions" with a description of "General rules for this project" is almost useless: it loads for everything and gets crowded out by more specific skills, or worse, it loads every time and fills context with generic instructions when Claude doesn't need them. The better approach is to split broad skills into specific, focused ones: one skill for commit conventions, one for test writing patterns, one for database migration rules, and one for API endpoint structure.

In the skill body, write actionable instructions, not philosophy. "Use descriptive variable names" is philosophy; Claude already knows that. "In this codebase, all database query functions follow the pattern findUserBy*(), createUser*(), updateUser*(), deleteUser*()" is actionable because it tells Claude exactly what to do in a specific situation. Worked examples are especially powerful. A skill that says "here's an example of a well-formed migration file in this project" and then shows an actual example is worth three paragraphs of rules.

Version your skills with your codebase. Keep project skills in .claude/skills/ and commit them to the repository. Update them when conventions change. When you add a new framework or change a naming convention, update the skill at the same time you update the code: it's the same kind of living documentation as your README and it pays the same kind of dividends. A well-maintained skills library is one of the things that makes Claude Code feel like a true team member who actually knows your project rather than a generic assistant you have to brief every time.

O erro mais comum ao escrever skills é ser muito amplo. Uma skill chamada "Convenções do projeto" com uma descrição de "Regras gerais para este projeto" é quase inútil: ela carrega para tudo e é superada por skills mais específicas, ou pior, carrega toda vez e preenche o contexto com instruções genéricas quando o Claude não precisa delas. A abordagem melhor é dividir skills amplas em específicas e focadas: uma skill para convenções de commit, uma para padrões de escrita de testes, uma para regras de migração de banco de dados e uma para estrutura de endpoint de API.

No corpo da skill, escreva instruções acionáveis, não filosofia. "Use nomes de variáveis descritivos" é filosofia; o Claude já sabe isso. "Nesta base de código, todas as funções de consulta ao banco de dados seguem o padrão findUserBy*(), createUser*(), updateUser*(), deleteUser*()" é acionável porque diz ao Claude exatamente o que fazer em uma situação específica. Exemplos práticos são especialmente poderosos. Uma skill que diz "aqui está um exemplo de um arquivo de migração bem formado neste projeto" e então mostra um exemplo real vale três parágrafos de regras.

Versione suas skills com sua base de código. Mantenha skills de projeto em .claude/skills/ e faça commit delas no repositório. Atualize-as quando as convenções mudarem. Quando você adicionar um novo framework ou mudar uma convenção de nomenclatura, atualize a skill ao mesmo tempo que atualiza o código: é o mesmo tipo de documentação viva que seu README e paga o mesmo tipo de dividendos. Uma biblioteca de skills bem mantida é uma das coisas que faz o Claude Code parecer um verdadeiro membro da equipe que realmente conhece o seu projeto em vez de um assistente genérico que você precisa instruir a cada vez.

You want Claude to automatically run your linter every time it edits a TypeScript file. Or log every bash command it runs. Or get a desktop notification when a long task finishes. You could remember to ask Claude to do these things every session, but you'd rather set it up once and have it happen automatically, forever. That's exactly what hooks are for.

Você quer que o Claude execute automaticamente seu linter toda vez que ele edita um arquivo TypeScript. Ou registrar cada comando bash que ele executa. Ou receber uma notificação na área de trabalho quando uma tarefa longa terminar. Você poderia lembrar de pedir ao Claude para fazer essas coisas em cada sessão, mas preferiria configurar uma vez e ter isso acontecendo automaticamente, para sempre. É exatamente para isso que os hooks existem.

Hooks are shell commands that Claude Code runs automatically at specific points in its lifecycle. You define them in your settings.json, either global (~/.claude/settings.json) or project-level (.claude/settings.json), and they fire every time the trigger condition is met without Claude needing to decide to run them. Claude doesn't schedule hooks, doesn't choose when to run them, and can't be asked to skip them. They run because the event happened, full stop.

This is a fundamentally different model from asking Claude to do something. When you ask Claude to run your linter after editing, it might forget, decide it's not necessary in this case, or do it for a few edits and then miss one. A hook can't forget. The hook fires when the trigger fires, full stop. This determinism is what makes hooks valuable for quality gates, logging, and notifications. They're promises you make to yourself that the system enforces.

Hooks are also useful for things Claude can't do by itself. Sending a desktop notification requires native OS access that Claude doesn't have from inside the tool loop. Logging to a structured log file that persists across sessions requires writing outside Claude's normal scope. Integrating with external systems (posting to Slack, updating a tracker) requires access that Claude might not have, or that you don't want to give it general access to. Hooks handle all of these because they're just shell commands running on your machine with your full permissions.

Hooks são comandos shell que o Claude Code executa automaticamente em pontos específicos do seu ciclo de vida. Você os define no seu settings.json, seja global (~/.claude/settings.json) ou de nível de projeto (.claude/settings.json), e eles disparam toda vez que a condição de gatilho é atendida, sem o Claude precisar decidir executá-los. O Claude não agenda hooks, não escolhe quando executá-los e não pode ser pedido para pulá-los. Eles executam porque o evento aconteceu, ponto final.

Esse é um modelo fundamentalmente diferente de pedir ao Claude para fazer algo. Quando você pede ao Claude para executar seu linter depois de editar, ele pode esquecer, decidir que não é necessário neste caso ou fazer isso em algumas edições e então perder uma. Um hook não pode esquecer. O hook dispara quando o gatilho dispara, ponto final. Esse determinismo é o que torna os hooks valiosos para gates de qualidade, logging e notificações. São promessas que você faz a si mesmo que o sistema cumpre.

Hooks também são úteis para coisas que o Claude não consegue fazer sozinho. Enviar uma notificação na área de trabalho requer acesso nativo ao SO que o Claude não tem de dentro do loop de ferramentas. Registrar em um arquivo de log estruturado que persiste entre sessões requer escrever fora do escopo normal do Claude. Integrar com sistemas externos (postar no Slack, atualizar um tracker) requer acesso que o Claude pode não ter, ou que você não quer dar a ele acesso geral. Hooks lidam com tudo isso porque são apenas comandos shell sendo executados na sua máquina com suas permissões completas.

Each hook type fires at a different point in Claude's activity cycle. Choosing the right hook type for a given use case is as important as writing the hook command itself. The wrong type fires at the wrong time and either does too much, too little, or creates feedback loops that are hard to debug.

Cada tipo de hook dispara em um ponto diferente no ciclo de atividade do Claude. Escolher o tipo de hook certo para um caso de uso específico é tão importante quanto escrever o comando do hook em si. O tipo errado dispara no momento errado e faz demais, de menos, ou cria loops de feedback difíceis de depurar.

Hooks fire on every matching event by default, which is sometimes exactly what you want (log every bash command) and sometimes way too broad (run the linter after every single file write, even if you're just writing a log or a temp file). The if: field lets you add conditions so a hook only fires when specific criteria are met. You can filter by tool name, by the output content, or by the exit code of the tool call.

A practical example: you want to run TypeScript type-checking after Claude edits a .ts file, but not after it writes a .json config or a .md documentation file. You'd set up a PostToolUse hook with if: { tool: "Write", output_contains: ".ts" }, which fires only when the Write tool was used and the result contains a .ts path. Combined with the command to run tsc --noEmit, you get automatic type-checking on every TypeScript edit without any noise from non-TypeScript writes.

One important caution: hooks run synchronously, and a PostToolUse hook that itself uses a tool (like running a bash command) will trigger another PostToolUse event. Without careful if: conditions, this creates a circular loop: write file → hook runs lint → lint is a bash command → PostToolUse fires again → hook runs lint again → infinite loop. The fix is to use specific if: conditions that won't match the hook's own tool calls. Keep hook scripts fast and specific, and test them with simple cases before relying on them in production sessions.

Hooks disparam em cada evento correspondente por padrão, o que às vezes é exatamente o que você quer (registrar cada comando bash) e às vezes é abrangente demais (executar o linter após cada escrita de arquivo, mesmo se você estiver apenas escrevendo um log ou um arquivo temporário). O campo if: permite adicionar condições para que um hook só dispare quando critérios específicos são atendidos. Você pode filtrar por nome de ferramenta, pelo conteúdo da saída ou pelo código de saída da chamada de ferramenta.

Um exemplo prático: você quer executar a verificação de tipos TypeScript depois que o Claude edita um arquivo .ts, mas não depois que ele escreve um config .json ou um arquivo de documentação .md. Você configuraria um hook PostToolUse com if: { tool: "Write", output_contains: ".ts" }, que dispara apenas quando a ferramenta Write foi usada e o resultado contém um caminho .ts. Combinado com o comando para executar tsc --noEmit, você obtém verificação automática de tipos em cada edição TypeScript sem ruído de escritas não-TypeScript.

Uma precaução importante: hooks executam de forma síncrona, e um hook PostToolUse que ele mesmo usa uma ferramenta (como executar um comando bash) vai disparar outro evento PostToolUse. Sem condições if: cuidadosas, isso cria um loop circular: escrever arquivo → hook executa lint → lint é um comando bash → PostToolUse dispara novamente → hook executa lint novamente → loop infinito. A correção é usar condições if: específicas que não vão corresponder às chamadas de ferramentas do próprio hook. Mantenha scripts de hook rápidos e específicos e teste-os com casos simples antes de confiar neles em sessões de produção.

You need to add tests to 30 different files, refactor 10 components, and update the documentation, all as part of the same feature. A single Claude session would take all day, and the context would fill up long before you're done. Is there a better way? Yes, but it comes with tradeoffs that are important to understand before you reach for it.

Você precisa adicionar testes a 30 arquivos diferentes, refatorar 10 componentes e atualizar a documentação, tudo como parte da mesma feature. Uma única sessão do Claude levaria o dia todo, e o contexto encheria muito antes de você terminar. Existe uma forma melhor? Sim, mas ela vem com tradeoffs que são importantes de entender antes de você recorrer a ela.

Multi-agent in Claude Code means one Claude instance (the coordinator) spawning other Claude instances (the workers) to handle parallel subtasks. The coordinator doesn't do the implementation work: it plans the overall approach, decides which work can be parallelized, dispatches subtasks to workers, monitors their progress, and integrates their results when they complete. Each worker runs in its own isolated context, with its own context window, tool access, and session state. Workers don't share state with each other; they only share results with the coordinator through what they return.

The isolation is both a feature and a constraint. It's a feature because workers can't interfere with each other's reasoning: there's no shared state to corrupt and no context contamination between parallel tasks. A worker working on ComponentA.tsx has no knowledge of what the worker working on ComponentB.tsx is doing, and that's fine as long as those two components don't need to be coordinated. The isolation becomes a constraint when tasks do need coordination. If two workers need to agree on a shared interface or both need to modify the same file, you either need the coordinator to handle that coordination explicitly, or you need to restructure the work so those tasks aren't parallelized.

Each worker is identified by a unique task prefix that the coordinator assigns. This prefix is embedded in the worker's tool call names so the coordinator can attribute each result back to the correct worker when integrating. Think of it as a job ticket number: when the worker says "I finished task-7," the coordinator knows exactly which subtask that result belongs to and how to incorporate it into the overall work.

Multi-agente no Claude Code significa uma instância do Claude (o coordenador) criando outras instâncias do Claude (os trabalhadores) para lidar com subtarefas paralelas. O coordenador não faz o trabalho de implementação: ele planeja a abordagem geral, decide qual trabalho pode ser paralelizado, despacha subtarefas para trabalhadores, monitora seu progresso e integra seus resultados quando eles completam. Cada trabalhador executa em seu próprio contexto isolado, com sua própria janela de contexto, acesso a ferramentas e estado de sessão. Os trabalhadores não compartilham estado entre si; eles só compartilham resultados com o coordenador através do que retornam.

O isolamento é tanto um recurso quanto uma restrição. É um recurso porque os trabalhadores não podem interferir no raciocínio uns dos outros: não há estado compartilhado para corromper e nenhuma contaminação de contexto entre tarefas paralelas. Um trabalhador trabalhando em ComponentA.tsx não tem conhecimento do que o trabalhador trabalhando em ComponentB.tsx está fazendo, e tudo bem contanto que esses dois componentes não precisem ser coordenados. O isolamento se torna uma restrição quando as tarefas precisam de coordenação. Se dois trabalhadores precisam concordar sobre uma interface compartilhada ou ambos precisam modificar o mesmo arquivo, você precisa que o coordenador lide com essa coordenação explicitamente ou precisa reestruturar o trabalho para que essas tarefas não sejam paralelizadas.

Cada trabalhador é identificado por um prefixo de tarefa único que o coordenador atribui. Esse prefixo é incorporado nos nomes das chamadas de ferramentas do trabalhador para que o coordenador possa atribuir cada resultado de volta ao trabalhador correto ao integrar. Pense nisso como um número de ticket de trabalho: quando o trabalhador diz "terminei a tarefa-7," o coordenador sabe exatamente a qual subtarefa esse resultado pertence e como incorporá-lo ao trabalho geral.

To use coordinator mode, give Claude a task that explicitly involves parallel work, such as "add unit tests to each of these 30 files simultaneously" or "refactor these three independent modules in parallel." Claude will recognize the parallelism and propose using sub-agents. You can also trigger it explicitly by saying "use parallel agents for this" or by using the Agent tool directly in your request. The coordinator will then break the work down, define subtasks with clear boundaries, and spawn workers for each one.

Workers have a restricted tool set compared to the coordinator. They can't spawn more agents, which means there is strictly one level of coordinator-worker and no infinite tree structures. This is a deliberate constraint that prevents accidental cost explosions. Workers can't modify session-level state directly; they work within their own context and return results. The coordinator receives worker results and integrates them, which may include resolving conflicts when workers touch overlapping parts of the codebase.

The integration step is where most multi-agent failures happen. Workers complete their individual tasks correctly, but the coordinator discovers conflicts: worker A changed an interface that worker B's code depended on, or two workers added the same utility function with slightly different implementations. This is why task decomposition matters so much. Before spawning agents, spend a moment thinking about whether the subtasks are truly independent. If they share an interface, a type definition, or a file, plan the shared pieces first and then parallelize the independent work.

Para usar o modo coordenador, dê ao Claude uma tarefa que envolve explicitamente trabalho paralelo, como "adicione testes unitários a cada um desses 30 arquivos simultaneamente" ou "refatore esses três módulos independentes em paralelo." O Claude reconhecerá o paralelismo e proporá usar sub-agentes. Você também pode acioná-lo explicitamente dizendo "use agentes paralelos para isso" ou usando a ferramenta Agent diretamente em sua solicitação. O coordenador então vai dividir o trabalho, definir subtarefas com limites claros e criar trabalhadores para cada uma.

Os trabalhadores têm um conjunto de ferramentas restrito em comparação com o coordenador. Eles não podem criar mais agentes, o que significa que existe estritamente um nível de coordenador-trabalhador, sem estruturas de árvore infinitas. Essa é uma restrição deliberada que previne explosões de custo acidentais. Os trabalhadores não podem modificar estado de nível de sessão diretamente; eles trabalham dentro de seu próprio contexto e retornam resultados. O coordenador recebe os resultados dos trabalhadores e os integra, o que pode incluir resolver conflitos quando trabalhadores tocam partes sobrepostas da base de código.

A etapa de integração é onde a maioria das falhas multi-agente acontece. Os trabalhadores completam suas tarefas individuais corretamente, mas o coordenador descobre conflitos: o trabalhador A mudou uma interface da qual o código do trabalhador B dependia, ou dois trabalhadores adicionaram a mesma função utilitária com implementações ligeiramente diferentes. É por isso que a decomposição de tarefas importa tanto. Antes de criar agentes, passe um momento pensando se as subtarefas são verdadeiramente independentes. Se elas compartilham uma interface, uma definição de tipo ou um arquivo, planeje as peças compartilhadas primeiro e depois paralelize o trabalho independente.

Multi-agent is not the answer to every large task. The overhead is real: each worker is a full Claude instance with its own startup cost, its own context window, and its own API calls. If a task could be done start-to-finish in a single session without filling the context, adding agents makes it slower and more expensive, not faster. The agent model is useful when the task has genuine parallelism — multiple independent subtasks that can be worked on simultaneously — and when the total work is large enough that the parallelism savings outweigh the overhead.

Good fits for agents: adding tests to 30 independent files (each file is a self-contained task), migrating a schema across many independent models, updating documentation for separate modules, and generating boilerplate for many similar components. Bad fits: tasks that require a shared decision to be made first (designing a shared API interface), tasks where each step depends on the previous step's result (sequential pipeline work), and tasks that are fundamentally small (adding one test file, fixing one bug).

A useful rule of thumb: if you'd describe the work as "do X for each of these N things" where N is greater than 5 and each X is independent, agents are likely the right choice. If you'd describe it as "do A, then B, then C" — sequential work — a single session is almost certainly better. When in doubt, start with a single session. You can always escalate to agents if context fills up; you can't easily de-escalate agents that have already done half the work.

Multi-agente não é a resposta para toda tarefa grande. O overhead é real: cada trabalhador é uma instância completa do Claude com seu próprio custo de inicialização, sua própria janela de contexto e suas próprias chamadas de API. Se uma tarefa pudesse ser feita do início ao fim em uma única sessão sem encher o contexto, adicionar agentes a torna mais lenta e mais cara, não mais rápida. O modelo de agentes é útil quando a tarefa tem paralelismo genuíno — múltiplas subtarefas independentes que podem ser trabalhadas simultaneamente — e quando o trabalho total é grande o suficiente para que as economias do paralelismo superem o overhead.

Bons candidatos para agentes: adicionar testes a 30 arquivos independentes (cada arquivo é uma tarefa autocontida), migrar um schema em muitos modelos independentes, atualizar documentação para módulos separados e gerar boilerplate para muitos componentes similares. Casos inadequados: tarefas que exigem uma decisão compartilhada antes de começar (projetar uma interface de API compartilhada), tarefas onde cada passo depende do resultado do anterior (trabalho de pipeline sequencial) e tarefas que são pequenas demais para justificar o overhead (adicionar um arquivo de teste, corrigir um bug).

Uma regra prática útil: se você descreveria o trabalho como "faça X para cada um desses N itens" onde N é maior que 5 e cada X é independente, agentes são provavelmente a escolha certa. Se você o descreveria como "faça A, então B, então C" — trabalho sequencial — uma única sessão é quase certamente melhor. Em caso de dúvida, comece com uma única sessão. Você sempre pode escalar para agentes se o contexto encher; você não pode facilmente desescalar agentes que já fizeram metade do trabalho.

Your Claude Code bill this month is three times what you expected. You used it for roughly the same number of tasks as last month. What changed, and how do you find out where the money went? The answer is almost always in the token breakdown: which tier your tokens are hitting, whether your cache is working, and whether you're accidentally generating more context than the tasks require.

Sua fatura do Claude Code este mês é três vezes o esperado. Você o usou para aproximadamente o mesmo número de tarefas do mês passado. O que mudou, e como você descobre para onde foi o dinheiro? A resposta está quase sempre no detalhamento de tokens: qual tier seus tokens estão atingindo, se seu cache está funcionando e se você está gerando acidentalmente mais contexto do que as tarefas exigem.

Token costs in Claude Code fall into three tiers, and they're priced very differently. Cached input tokens are the cheapest, roughly one-tenth the cost of new input tokens. New input tokens cost more. Output tokens are the most expensive. In a well-optimized session where you're making good use of the prompt cache, the bulk of your input tokens should be cached, and you should see that reflected in the cost breakdown. A session where you're paying full price for most input tokens is a session where the cache is broken or cold.

The cache hit depends on the conversation prefix being stable and recent. "Stable" means the system prompt and early messages haven't changed since the last request. "Recent" means the last request was within approximately five minutes (the cache TTL). As long as both conditions hold, every token in the stable prefix is a cache hit. In a long coding session where you're sending messages every few minutes, this can represent substantial savings, since the system prompt plus a growing conversation history all land at one-tenth the cost.

Claude Code shows a token breakdown per response. Get in the habit of glancing at it. The key metric is the ratio of cached input tokens to new input tokens. If you're in the middle of a long session and that ratio drops suddenly, with many new input tokens where there used to be mostly cached tokens, something broke the cache. The most common culprits: you (or a hook) edited CLAUDE.md since the session started, you switched to a different model, or there was a long pause that let the cache expire. Identify the cause and fix it for future sessions; you can't un-pay for the current one.

Os custos de tokens no Claude Code se dividem em três tiers, e eles têm preços muito diferentes. Tokens de entrada em cache são os mais baratos, aproximadamente um décimo do custo de novos tokens de entrada. Novos tokens de entrada custam mais. Tokens de saída são os mais caros. Em uma sessão bem otimizada onde você está fazendo bom uso do cache de prompt, a maior parte de seus tokens de entrada deveria estar em cache, e você deveria ver isso refletido no detalhamento de custos. Uma sessão onde você está pagando preço cheio pela maioria dos tokens de entrada é uma sessão onde o cache está quebrado ou frio.

A ocorrência de cache depende do prefixo da conversa ser estável e recente. "Estável" significa que o prompt do sistema e as primeiras mensagens não mudaram desde a última solicitação. "Recente" significa que a última solicitação foi dentro de aproximadamente cinco minutos (o TTL do cache). Enquanto ambas as condições forem verdadeiras, cada token no prefixo estável é uma ocorrência de cache. Em uma longa sessão de codificação onde você está enviando mensagens a cada poucos minutos, isso pode representar economias substanciais, já que o prompt do sistema mais um histórico de conversa crescente têm custo dez vezes menor quando estão em cache.

O Claude Code mostra um detalhamento de tokens por resposta. Crie o hábito de dar uma olhada nele. A métrica chave é a proporção de tokens de entrada em cache para novos tokens de entrada. Se você estiver no meio de uma sessão longa e essa proporção cair de repente, com muitos novos tokens de entrada onde antes havia principalmente tokens em cache, algo quebrou o cache. Os culpados mais comuns: você (ou um hook) editou o CLAUDE.md desde que a sessão começou, você mudou para um modelo diferente ou houve uma longa pausa que deixou o cache expirar. Identifique a causa e corrija para sessões futuras; você não pode desfazer o pagamento da atual.

When running Claude Code with --no-input or in a CI/CD pipeline, it operates in unattended mode. In this mode, transient failures don't immediately abort the task; Claude Code uses exponential backoff to retry. The retry sequence starts at 1 second, doubles with each attempt, and stops after 5 retries. That means a task that hits repeated transient failures can accumulate up to about 31 seconds of wait time (1 + 2 + 4 + 8 + 16) before giving up. In a CI pipeline where you're paying for build minutes, that's worth knowing.

The distinction between retried and non-retried failures matters for pipeline debugging. Network errors, rate limits, and temporary API failures are all retried because they're transient by nature and usually resolve on their own. Model refusals, permission errors, and malformed requests are not retried because these are deterministic failures that won't go away on their own. If your CI job is hanging and then failing, it's hitting transient errors and retrying. If it fails immediately, it's a deterministic error. This distinction tells you where to look when something goes wrong in an automated context.

Rate limits deserve special attention in CI. If multiple CI jobs run concurrently and all make Claude Code API calls, they'll compete for the same rate limit. The retry logic handles this gracefully: rate limit responses trigger the backoff and retry sequence. But the wall-clock time adds up. If your CI is slow because of Claude Code calls, check whether rate limit retries are the bottleneck before looking at other causes.

Ao executar o Claude Code com --no-input ou em um pipeline CI/CD, ele opera em modo sem supervisão. Nesse modo, falhas transitórias não abortam imediatamente a tarefa; o Claude Code usa backoff exponencial para retry. A sequência de retry começa em 1 segundo, dobra a cada tentativa e para após 5 retries. Isso significa que uma tarefa que atinge falhas transitórias repetidas pode acumular até cerca de 31 segundos de tempo de espera (1 + 2 + 4 + 8 + 16) antes de desistir. Em um pipeline de CI onde você está pagando por minutos de build, vale saber.

A distinção entre falhas com retry e sem retry importa para depuração de pipeline. Erros de rede, rate limits e falhas temporárias de API passam pelo retry porque são transitórios por natureza e geralmente se resolvem por conta própria. Recusas do modelo, erros de permissão e requisições malformadas não passam pelo retry porque são falhas determinísticas que não se resolvem sozinhas. Se seu job de CI está travando e depois falhando, ele está atingindo erros transitórios e tentando novamente. Se falha imediatamente, é um erro determinístico. Essa distinção te diz onde procurar quando algo dá errado em um contexto automatizado.

Rate limits merecem atenção especial em CI. Se múltiplos jobs de CI executam concorrentemente e todos fazem chamadas de API do Claude Code, eles vão competir pelo mesmo rate limit. A lógica de retry lida com isso sem problema: respostas de rate limit disparam a sequência de backoff e retry. Mas o tempo real se acumula. Se seu CI está lento por causa das chamadas do Claude Code, verifique se os retries de rate limit são o gargalo antes de procurar outras causas.

The single biggest cost optimization in Claude Code is keeping your system prompt stable and cached. The system prompt — your CLAUDE.md content plus Claude Code's built-in system instructions — is the same across every request in a session. If it's cached, every request benefits. If it's not cached (because you edited CLAUDE.md mid-session or because of a long pause), every request pays full price for re-sending that large, stable prefix. On a long session, this one factor can easily double or triple your cost.

Beyond caching, the next biggest optimization is session structure. Using --continue to resume an existing session is cheaper than starting fresh, because the warm session already has a cached prefix. Batching related changes into one session is cheaper than separate sessions for each change, because the compacted summary of earlier work is much smaller than re-explaining everything fresh. Compacting manually at natural breakpoints keeps the context lean and ensures the summarizer has clean input, which means cleaner continuation and less cost drift over a long working day.

The optimization that developers most often overlook is tool selection. The native Glob and Grep tools are nearly free in terms of cost, since they use an indexed file registry that doesn't burn API tokens the way Bash find and grep commands do. A session that uses Bash for every file search is paying more than it needs to. And for very large files, using targeted Grep to find specific content instead of reading the whole file with Read means you're adding only the relevant content to context, not 100KB of file content that Claude has to process and reason about on every subsequent turn. Measure first, then optimize. Read the token breakdown before assuming what's expensive.

A maior otimização de custo no Claude Code é manter seu prompt do sistema estável e em cache. O prompt do sistema — seu conteúdo do CLAUDE.md mais as instruções de sistema embutidas do Claude Code — é o mesmo em cada solicitação em uma sessão. Se estiver em cache, cada solicitação se beneficia. Se não estiver em cache (porque você editou o CLAUDE.md no meio da sessão ou por causa de uma longa pausa), cada solicitação paga preço cheio por reenviar esse prefixo grande e estável. Em uma sessão longa, esse único fator pode facilmente dobrar ou triplicar seu custo.

Além do cache, a próxima maior otimização é a estrutura da sessão. Usar --continue para retomar uma sessão existente é mais barato do que começar do zero, porque a sessão aquecida já tem um prefixo em cache. Agrupar mudanças relacionadas em uma sessão é mais barato do que sessões separadas para cada mudança, porque o resumo compactado do trabalho anterior é muito menor do que reexplicar tudo do zero. Compactar manualmente em pontos de interrupção naturais mantém o contexto enxuto e garante que o processo de resumo tenha material limpo para trabalhar, o que significa continuação mais limpa e menos deriva de custo ao longo de um longo dia de trabalho.

A otimização que os desenvolvedores mais frequentemente ignoram é a seleção de ferramentas. As ferramentas nativas Glob e Grep são praticamente gratuitas em termos de custo, já que usam um registro de arquivos indexado que não consome tokens de API da mesma forma que os comandos Bash find e grep. Uma sessão que usa Bash para cada busca de arquivo está pagando mais do que precisa. E para arquivos muito grandes, usar Grep direcionado para encontrar conteúdo específico em vez de ler o arquivo inteiro com Read significa que você está adicionando apenas o conteúdo relevante ao contexto, não 100KB de conteúdo de arquivo que o Claude tem que processar e raciocinar em cada turno subsequente. Meça primeiro, depois otimize. Leia o detalhamento de tokens antes de assumir o que é caro.

You've read the whole guide. Now you need a quick reference card: the things you'll actually look up in the middle of a session when something isn't working the way you expect. This chapter is designed to be scanned, not read linearly. Keep it open in a browser tab.

Você leu o guia inteiro. Agora você precisa de um cartão de referência rápida: as coisas que você vai realmente consultar no meio de uma sessão quando algo não está funcionando como você espera. Este capítulo foi projetado para ser verificado, não lido linearmente. Mantenha-o aberto em uma aba do navegador.

These environment variables let you override Claude Code's default behavior at the process level. Set them in your shell profile for persistent changes, or inline before a command for one-off overrides.

Essas variáveis de ambiente permitem que você substitua o comportamento padrão do Claude Code no nível do processo. Configure-as no seu perfil de shell para mudanças persistentes, ou inline antes de um comando para substituições pontuais.

1. Write CLAUDE.md before starting any complex session.

CLAUDE.md is the one artifact that persists across every session and every team member. A session started without it forces Claude to rediscover your project structure, conventions, and decisions from scratch, and you'll pay for that rediscovery in tokens and time, repeatedly. Five minutes writing a good CLAUDE.md at the start of a project saves hours over its lifetime.

2. Keep CLAUDE.md under 25KB and specific — generic instructions waste tokens.

The 25KB threshold is where CLAUDE.md shifts from eagerly-loaded to lazily-loaded. Beyond that limit, your instructions may not be in context when they're needed. Beyond that, generic instructions like "write clean code" consume tokens without changing behavior. Every line in CLAUDE.md should be something Claude wouldn't know or do correctly without it.

3. At session start in large repos, explicitly run git status via Bash.

The startup git snapshot is capped at 2,000 characters and memoized for the session. In a large repo, the snapshot may be silently truncated, and it definitely won't reflect any changes you make after the session starts. A quick git status at the beginning of a session gives Claude a fresh, complete picture of what's actually happening in your working tree.

4. Compact or restart at natural breakpoints — don't wait for auto-compaction to surprise you.

Auto-compaction fires at ~87% context, which is fine as a safety net but bad as a planned event. It can fire in the middle of a complex operation at the worst possible moment. Use /compact at the end of each feature or problem area. You control what goes into the summary, and the next phase starts clean.

5. When Claude stops mid-generation, say "continue" — it almost always works.

The circuit-breaker fires when Claude has made three or more low-value consecutive tool calls. It stops Claude and surfaces the situation. The word "continue" resets the continuation counter and Claude picks up where it left off. You don't need to re-explain anything. This single word has saved countless confused minutes for developers who didn't know about the circuit-breaker.

6. Give tools minimum permissions — never run full auto-approve on untrusted code.

Auto-approve is a productivity feature, not a security feature. On familiar code you've written yourself, broad auto-approve is reasonable. On unfamiliar repositories, on vendor code, or in any CI context, use explicit permissions and review what Claude wants to run before it runs. One unexpected delete in a production context costs far more than the time saved by skipping permission prompts.

7. Use sub-agents for genuinely parallel work only — overhead is real for small tasks.

Each sub-agent is a full Claude API session with startup cost, context overhead, and coordination overhead for the coordinator to integrate results. For a task you could complete in a single session, agents make it slower, not faster. Reserve agents for tasks where N is large, the subtasks are truly independent, and the work won't fit in a single context window even with compaction.

8. Keep CLAUDE.md stable during a session — editing it breaks the prompt cache.

The prompt cache key includes the system prompt, which includes CLAUDE.md content. Any mid-session edit to CLAUDE.md invalidates the cache and forces full re-computation on every subsequent request for the rest of the session. Note things you want to add during a session; write them to CLAUDE.md after the session ends. One rule: edit before or after, not during.

9. Read the token cost breakdown before optimizing — measure, don't guess.

Token optimization intuitions are often wrong. The thing you think is expensive (asking a complex question) is often cheap because it's cached. The thing you think is cheap (reading a large file "just to check") can be expensive because it adds 100KB of uncached content to context. Claude Code shows you the breakdown. Look at it, identify the actual expensive operations, then optimize those specifically.

10. When something behaves unexpectedly, the answer is usually in the source code.

Claude Code is open source, and every unexpected behavior in this guide has a specific line of code behind it. The 2,000-character git snapshot truncation, the 87% compaction trigger, the 100KB tool result cap, the circuit-breaker logic — all of it is readable. When Claude does something you don't understand and this guide doesn't explain it, the source is the authoritative answer. Check the behavior, not just the docs.

1. Escreva o CLAUDE.md antes de iniciar qualquer sessão complexa.

O CLAUDE.md é o único artefato que persiste em todas as sessões e todos os membros da equipe. Uma sessão iniciada sem ele força o Claude a redescobrir do zero a estrutura do projeto, as convenções e as decisões já tomadas — e você paga por isso em tokens e tempo, toda vez. Cinco minutos escrevendo um bom CLAUDE.md no início de um projeto economiza horas ao longo de sua vida útil.

2. Mantenha o CLAUDE.md abaixo de 25KB e específico — instruções genéricas desperdiçam tokens.

O limite de 25KB é onde o CLAUDE.md passa de pré-carregado para carregado de forma lazy. Além desse limite, suas instruções podem não estar no contexto quando necessárias. Além disso, instruções genéricas como "escreva código limpo" consomem tokens sem mudar o comportamento. Cada linha no CLAUDE.md deve ser algo que o Claude não saberia ou não faria corretamente sem ela.

3. No início de uma sessão em repositórios grandes, execute explicitamente git status via Bash.

O snapshot git de inicialização é limitado a 2.000 caracteres e guardado em cache para a sessão. Em um repositório grande, o snapshot pode ser silenciosamente truncado, e definitivamente não refletirá quaisquer mudanças que você fizer após o início da sessão. Um rápido git status no início de uma sessão dá ao Claude uma visão atualizada e completa do que está realmente acontecendo na sua árvore de trabalho.

4. Compacte ou reinicie em pontos de interrupção naturais — não espere a compactação automática te surpreender.

A compactação automática dispara em ~87% de contexto, o que é bom como rede de segurança mas ruim como evento planejado. Ela pode disparar no meio de uma operação complexa no pior momento possível. Use /compact ao final de cada feature ou área de problema. Você controla o que vai para o resumo, e a próxima fase começa limpa.

5. Quando o Claude para no meio da geração, diga "continue" — quase sempre funciona.

O circuit-breaker dispara quando o Claude fez três ou mais chamadas consecutivas de baixo valor. Ele para o Claude e apresenta a situação. A palavra "continue" reinicia o contador de continuação e o Claude retoma de onde parou. Você não precisa reexplicar nada. Essa única palavra já poupou inúmeros minutos de confusão para desenvolvedores que não sabiam do circuit-breaker.

6. Dê às ferramentas permissões mínimas — nunca execute aprovação automática total em código não confiável.

A aprovação automática é um recurso de produtividade, não um recurso de segurança. Em código familiar que você mesmo escreveu, aprovação automática ampla é razoável. Em repositórios desconhecidos, em código de fornecedor, ou em qualquer contexto de CI, use permissões explícitas e revise o que o Claude quer executar antes de executar. Uma exclusão inesperada em um contexto de produção custa muito mais do que o tempo economizado por pular prompts de permissão.

7. Use sub-agentes apenas para trabalho genuinamente paralelo — o overhead é real para tarefas pequenas.

Cada sub-agente é uma sessão completa da API do Claude com custo de inicialização, overhead de contexto, e overhead de coordenação para o coordenador integrar resultados. Para uma tarefa que você poderia completar em uma única sessão, agentes a tornam mais lenta, não mais rápida. Reserve agentes para tarefas onde N é grande, as subtarefas são verdadeiramente independentes, e o trabalho não caberá em uma única janela de contexto mesmo com compactação.

8. Mantenha o CLAUDE.md estável durante uma sessão — editá-lo quebra o cache de prompt.

A chave de cache de prompt inclui o prompt do sistema, que inclui o conteúdo do CLAUDE.md. Qualquer edição no CLAUDE.md no meio da sessão invalida o cache e força recálculo completo em cada solicitação subsequente pelo resto da sessão. Anote as coisas que quer adicionar durante uma sessão; escreva-as no CLAUDE.md depois que a sessão terminar. Uma regra: edite antes ou depois, não durante.

9. Leia o detalhamento de custo de tokens antes de otimizar — meça, não adivinhe.

As intuições de otimização de tokens frequentemente estão erradas. A coisa que você pensa que é cara (fazer uma pergunta complexa) geralmente é barata porque está em cache. A coisa que você pensa que é barata (ler um arquivo grande "só para verificar") pode ser cara porque adiciona 100KB de conteúdo sem cache ao contexto. O Claude Code mostra o detalhamento. Olhe para ele, identifique as operações realmente caras, depois otimize especificamente essas.

10. Quando algo se comporta inesperadamente, a resposta geralmente está no código-fonte.

O Claude Code é de código aberto, e cada comportamento inesperado neste guia tem uma linha específica de código por trás dele. O truncamento do snapshot git em 2.000 caracteres, o gatilho de compactação de 87%, o limite de 100KB de resultado de ferramenta, a lógica do circuit-breaker — tudo isso é legível. Quando o Claude faz algo que você não entende e este guia não explica, o código-fonte é a resposta autoritativa. Verifique o comportamento, não apenas a documentação.