Escopo é parte da resposta

O problema

Um time descobre que uma instrução funciona bem — "sempre rode o linter antes de finalizar uma edição" — e a coloca no CLAUDE.md do projeto. Três semanas depois, um desenvolvedor trabalhando num script isolado, sem nenhuma dependência de lint configurada, vê o Claude tentando rodar um linter que não existe naquele contexto. A instrução era boa. O escopo estava errado.

Esse é o erro mais comum em configuração de Claude Code: tratar toda instrução como se devesse valer em todo lugar, o tempo todo. A prova testa exatamente essa habilidade — não se você sabe que CLAUDE.md existe, mas se você sabe decidir onde uma instrução, comando ou regra deveria viver.

Quatro escopos, quatro respostas diferentes

Claude Code tem uma hierarquia de configuração com escopos concêntricos, e cada um responde a uma pergunta diferente:

• Usuário (~/.claude/) — "isso é uma preferência minha, que eu quero em todo projeto que eu tocar?" Comandos pessoais e atalhos ficam aqui.
• Projeto (.claude/ no repositório, versionado) — "isso é uma convenção da equipe, que qualquer pessoa trabalhando neste repo deveria seguir?" CLAUDE.md do projeto, comandos compartilhados e Skills do time vivem aqui.
• Regra específica de caminho (arquivo markdown em .claude/rules/ com um paths glob no frontmatter YAML) — "isso só se aplica quando estou mexendo numa parte específica do código?" A regra de lint do exemplo acima deveria ter sido uma regra com paths: ["src/api/**"], não uma linha solta no CLAUDE.md geral.
• Sessão/efêmero — instruções que só fazem sentido para a tarefa que está rodando agora, e não deveriam sobreviver além dela.

A pergunta que resolve a maioria dos cenários de prova sobre este tópico não é "essa instrução é boa?" — quase sempre é. É "essa instrução é válida em todo escopo onde ela vai aparecer?" Uma instrução útil no escopo errado ainda é uma falha de configuração, mesmo que o conteúdo dela esteja certo.

Skills: escopo, mas também contrato

Uma Skill (.claude/skills/<nome>/SKILL.md) formaliza essa mesma lógica de escopo em um pacote reutilizável. O frontmatter YAML de uma Skill carrega decisões estruturais que valem a pena memorizar:

• context: fork — a Skill roda em um contexto isolado, então o que ela descobre não polui a sessão principal por padrão.
• allowed-tools — a Skill só pode usar as ferramentas explicitamente listadas, mesmo que a sessão que a invocou tenha acesso a mais.
• argument-hint — documenta o formato esperado de entrada, reduzindo invocação ambígua.

O erro comum aqui é tratar allowed-tools como documentação em vez de como controle: uma Skill de "revisar código" que lista Bash em allowed-tools sem necessidade real amplia a superfície de risco sem ganho correspondente. A pergunta de projeto é sempre "quais ferramentas essa Skill precisa para cumprir o contrato dela?", não "quais ferramentas seria conveniente ter disponíveis".

CI headless: saída estruturada, não julgamento de terminal

Rodar Claude Code de forma não interativa em CI (-p ou --print, com --output-format json) muda a natureza do problema: não existe mais um humano olhando a saída em tempo real para interpretar nuance. Isso tem duas consequências de design:

1. A saída precisa ser estruturada o suficiente para que outro processo (um step de pipeline, um bot de revisão) tome decisão automatizada a partir dela — não um resumo em prosa que só um humano entenderia.
2. Uma execução headless que muda código de produção sem uma revisão independente separada é um risco, mesmo que o resultado pareça correto. O padrão maduro usa duas passagens: uma que gera a mudança, outra — sessão separada, sem o contexto de como a primeira "decidiu" — que revisa evidência antes de aprovar.

O distrator típico de cenário aqui é propor CI headless como suficiente sozinho, sem revisão independente, porque "o --output-format json já garante qualidade". Formato estruturado garante que a saída é parseável. Não garante que ela está certa.

Coloque em prática

O laboratório desta lição pede pra você auditar um conjunto de instruções espalhadas em escopos diferentes (usuário, projeto, regra de caminho) e classificar cada uma: está no escopo certo, deveria subir, deveria descer, ou deveria virar uma regra paths-específica.