Use Cases
Essa página cobre casos de uso completos — do setup ao fluxo rodando. Não é inventário de feature, é receita de workflow. A ideia é pegar um caso, entender a estrutura, e adaptar pro seu contexto.
Scrum Master Agent — GitHub Projects
Esse é um dos casos que mais impressionam quem vê pela primeira vez. Você configura o Claude pra ler o board do GitHub Projects, movimentar tasks, escrever e refinar itens, e resumir o estado do sprint. Um agente que age como Scrum Master — sem precisar de servidor dedicado, sem infraestrutura, rodando do seu terminal.
O que o agente faz
- Lê o board e entende o estado atual de cada coluna
- Move tasks entre colunas (Todo → In Progress → In Review → Done)
- Escreve e melhora descrições de issues (clareza, critérios de aceite, contexto técnico)
- Gera resumo de sprint daily
- Sugere priorização baseada no que está bloqueado ou parado há muito tempo
- Cria novas tasks a partir de uma descrição informal
Pré-requisito: GitHub CLI autenticado
gh auth login
gh auth status
E ter o projeto criado no GitHub. Para pegar o número do projeto:
gh project list --owner <seu-usuario-ou-org>
MCP server do GitHub (opcional mas recomendado)
O gh CLI cobre bastante coisa, mas o MCP server do GitHub dá acesso mais rico ao Projects V2 via GraphQL:
claude mcp add github -- npx -y @modelcontextprotocol/server-github
Exige GITHUB_TOKEN com escopo project:
export GITHUB_TOKEN=ghp_...
Ou no .claude/settings.json:
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_TOKEN": "ghp_..."
}
}
}
}
Subagente: scrum-master
Crie .claude/agents/scrum-master.md:
---
name: scrum-master
description: Gerencia o board do GitHub Projects. Use quando precisar mover tasks, escrever ou melhorar issues, gerar resumo do sprint, ou priorizar itens do backlog.
tools: Bash
model: sonnet
---
Você é um Scrum Master técnico. Você conhece o contexto do projeto e tem acesso ao GitHub Projects via `gh` CLI.
## Suas responsabilidades
- Manter o board organizado e atualizado
- Garantir que issues têm descrição clara, critérios de aceite e contexto suficiente pra um dev começar sem perguntas
- Identificar blockers e itens parados
- Resumir o estado do sprint de forma objetiva
## Padrões de qualidade pra issues
Uma boa issue tem:
- **Título**: ação + objeto (ex: "Implementar autenticação JWT no endpoint /login")
- **Contexto**: por que essa task existe, qual problema resolve
- **Critérios de aceite**: lista verificável do que "pronto" significa
- **Notas técnicas** (se relevante): onde mexer, dependências, riscos
## Comandos disponíveis
```bash
# Listar projetos
gh project list --owner <org>
# Ver itens do projeto
gh project item-list <número> --owner <org> --format json
# Criar issue
gh issue create --title "..." --body "..." --label "..."
# Editar issue
gh issue edit <número> --body "..."
# Adicionar comentário
gh issue comment <número> --body "..."
# Ver detalhes de uma issue
gh issue view <número>
# Mover item no projeto (requer GraphQL via gh api)
gh api graphql -f query='
mutation {
updateProjectV2ItemFieldValue(
input: {
projectId: "<PROJECT_ID>"
itemId: "<ITEM_ID>"
fieldId: "<STATUS_FIELD_ID>"
value: { singleSelectOptionId: "<OPTION_ID>" }
}
) { projectV2Item { id } }
}
'
Sempre confirme com o usuário antes de mover tasks ou editar issues. Mostre o que vai fazer antes de executar.
### Skill: daily-standup
`.claude/skills/daily-standup/SKILL.md`:
```yaml
---
name: daily-standup
description: Gera resumo do estado atual do sprint para daily standup
disable-model-invocation: true
allowed-tools: Bash(gh *)
---
Gere um resumo do sprint para a daily standup.
## Coleta de dados
Execute os seguintes comandos:
1. `gh project item-list $ARGUMENTS --owner <org> --format json` — itens do board
2. `gh pr list --state open --json title,author,reviewDecision,isDraft` — PRs em aberto
3. `gh issue list --label "bug" --state open --json title,assignees,createdAt` — bugs abertos
## Formato do resumo
Organize assim:
**Em andamento (In Progress)**
- Liste cada item com assignee e há quantos dias está nessa coluna
**Em review (In Review)**
- PRs aguardando review com autor e se já tem aprovações
**Bloqueado / Parado**
- Itens em Todo há mais de 3 dias sem movimento
- Issues sem assignee
**Concluído recentemente**
- Fechado nos últimos 2 dias
**Riscos do sprint**
- O que pode não ser entregue e por quê
Seja objetivo. Uma linha por item quando possível.
Uso: /daily-standup 42 (onde 42 é o número do projeto)
Skill: refine-issue
.claude/skills/refine-issue/SKILL.md:
---
name: refine-issue
description: Melhora a qualidade de uma issue do GitHub — adiciona contexto, critérios de aceite e notas técnicas
disable-model-invocation: true
allowed-tools: Bash(gh *) Bash(git log *) Bash(git grep *) Read Glob Grep
---
Refine a issue #$ARGUMENTS para melhorar a qualidade antes de entrar no sprint.
## Passos
1. `gh issue view $ARGUMENTS` — leia a issue atual
2. Analise o que falta: contexto, critérios de aceite, notas técnicas
3. Busque no codebase arquivos relevantes para enriquecer o contexto técnico
4. Escreva uma versão melhorada seguindo o padrão:
---
**Contexto**
[Por que essa task existe. Qual problema resolve. Referência a issue pai ou PRD se houver.]
**O que fazer**
[Descrição clara e objetiva da implementação esperada.]
**Critérios de aceite**
- [ ] ...
- [ ] ...
- [ ] ...
**Notas técnicas**
- Arquivos relevantes: `src/...`
- Dependências: ...
- Riscos: ...
---
5. Mostre o diff entre a versão atual e a proposta
6. Pergunte se aprova antes de editar
7. Se aprovado: `gh issue edit $ARGUMENTS --body "..."`
Uso: /refine-issue 87
Skill: create-task
.claude/skills/create-task/SKILL.md:
---
name: create-task
description: Cria uma nova issue no GitHub a partir de uma descrição informal
disable-model-invocation: true
allowed-tools: Bash(gh *)
---
Crie uma nova issue no GitHub a partir da descrição: "$ARGUMENTS"
## Passos
1. Entenda o que foi pedido
2. Se a descrição for vaga, faça no máximo 2 perguntas de clarificação
3. Escreva a issue no formato padrão do projeto:
**Título**: curto, ação + objeto
**Body**:
- Contexto (por que existe)
- O que fazer
- Critérios de aceite (checklist)
- Notas técnicas (se já souber)
4. Mostre o que vai criar e aguarde aprovação
5. Crie com: `gh issue create --title "..." --body "..." --project <projeto>`
Uso: /create-task "precisamos de rate limiting no endpoint de login"
Sessão interativa — modo agente
Quando você quer deixar o Claude conduzir uma sessão completa de refinamento do backlog:
Você é um Scrum Master. Temos um sprint começando na próxima segunda.
Acesse o GitHub Projects #42 (org: minha-empresa), leia o estado atual do board,
e me ajude a:
1. Identificar issues mal descritas que um dev não conseguiria começar sem perguntar
2. Priorizar as 5 mais importantes pro sprint
3. Refinar as 3 piores issues antes de eu encerrar hoje
Confirme comigo antes de editar qualquer coisa.
O Claude usa o gh CLI, lê as issues, lê o codebase pra dar contexto técnico, e propõe as melhorias uma por uma pra você aprovar.
Automação via routine agendada
Se quiser o resumo de sprint automático toda manhã:
/schedule
Nome: daily-standup-summary
Horário: toda segunda a sexta às 9h
Tarefa: Execute `/daily-standup 42` no projeto minha-empresa/meu-repo e
envie o resultado como comentário na issue pinned de tracking do sprint.
O Claude roda na infra da Anthropic, sem precisar do seu computador ligado.
Onboarding Automático de Dev
Quando um dev novo entra no time, o tempo gasto explicando o projeto é enorme. Esse use case cria um agente de onboarding que responde dúvidas sobre o codebase de forma contextualizada.
Skill: onboarding
.claude/skills/onboarding/SKILL.md:
---
name: onboarding
description: Guia um dev novo no projeto, respondendo dúvidas sobre arquitetura, padrões e como fazer as primeiras contribuições
context: fork
agent: Explore
---
Você está ajudando um desenvolvedor novo a entender o projeto.
Para cada dúvida do usuário:
1. Leia os arquivos relevantes antes de responder
2. Explique com exemplos reais do codebase (cite arquivo e linha)
3. Mostre o padrão que o time usa, não o padrão genérico da linguagem
4. Sugira o próximo passo ou o que mais vale entender
Tópicos comuns para cobrir quando o dev pedir uma visão geral:
- Estrutura de pastas e o que fica em cada lugar
- Como rodar localmente (setup, env vars, banco)
- Fluxo de uma request do endpoint até o banco
- Como adicionar um novo endpoint seguindo o padrão existente
- Como rodar testes e o que cada tipo cobre
- Processo de PR: branch naming, commit format, quem revisa
Seja objetivo. Um dev sênior não precisa de tutorial básico — precisa entender as decisões e os padrões específicos desse projeto.
Uso: /onboarding → o dev faz perguntas livremente
Análise de Impacto antes de Refatoração
Antes de refatorar algo grande, você precisa saber o que vai ser afetado. Esse use case usa subagent pra mapear dependências sem poluir o contexto da sua sessão de implementação.
Prompt direto
Use um subagente pra mapear o impacto de renomear a função `processPayment`
em `src/payment/processor.ts`.
Quero saber:
- Quantos arquivos a chamam diretamente
- Se algum teste mockaria esse nome
- Se aparece em algum arquivo de config ou doc
- Quais serviços externos dependem do comportamento atual
Traga um relatório antes de eu começar a refatoração.
Skill: impact-analysis
.claude/skills/impact-analysis/SKILL.md:
---
name: impact-analysis
description: Mapeia o impacto de uma mudança antes de implementar — dependências, chamadores, testes, documentação
context: fork
agent: Explore
---
Faça uma análise de impacto para: $ARGUMENTS
Investigue:
1. **Dependências diretas**: quem chama, importa ou usa o que vai mudar
2. **Testes**: quais testes cobrem isso, quais mockariam, quais precisariam mudar
3. **Configuração**: aparece em arquivos de config, env, ou infraestrutura?
4. **Documentação**: referenciado em docs, CLAUDE.md, README?
5. **Contratos externos**: APIs expostas, tipos exportados, eventos emitidos
Organize o relatório por severidade:
- **Quebra garantida**: vai parar de compilar/funcionar sem mudança explícita
- **Provável impacto**: provavelmente precisa de ajuste
- **Vale verificar**: pode ser afetado, confirme
Inclua caminhos de arquivo e nomes de função específicos.
Uso: /impact-analysis "renomear processPayment para executePayment em src/payment/processor.ts"
Agente de Incident Response
Quando o alarme toca em produção e você precisa investigar rápido.
Skill: incident
.claude/skills/incident/SKILL.md:
---
name: incident
description: Conduz investigação de incidente em produção — analisa logs, identifica causa raiz, sugere mitigação
disable-model-invocation: true
allowed-tools: Bash(gh *) Bash(git *) Bash(kubectl *) Bash(aws *) Read Glob Grep
---
## Incidente: $ARGUMENTS
Conduza a investigação seguindo esse roteiro:
### 1. Coletar contexto
- Qual serviço está afetado?
- Quando começou? (horário exato se souber)
- Qual o sintoma observado (erro, lentidão, indisponibilidade)?
### 2. Investigar mudanças recentes
```bash
git log --oneline -20 # o que mudou recentemente
gh pr list --state merged --limit 10 # PRs que foram pro ar
3. Correlacionar com o código
- Leia os arquivos do serviço afetado
- Procure pelo padrão de erro reportado no código
4. Hipóteses
Liste as 3 hipóteses mais prováveis ordenadas por probabilidade, com justificativa baseada no código.
5. Próximos passos
Para cada hipótese: qual comando ou verificação confirma ou descarta.
6. Mitigação imediata
Se a causa for confirmada, o que pode ser feito agora pra reduzir impacto (rollback, feature flag, config change) antes do fix definitivo.
Seja rápido e direto. Em incidente, clareza vale mais que completude.
Uso: `/incident "gateway de pagamento retornando 503 desde 14:30"`
---
## Documentação Automática
Documentação é a coisa que todo dev sabe que deveria fazer e ninguém quer fazer. Esse use case cobre os três cenários mais comuns: gerar docs de código que não tem nenhuma, manter docs em sincronia com o código conforme ele evolui, e escrever guias técnicos a partir do codebase.
### O problema real
Código sem doc é ruim. Doc desatualizada é pior — ela mente. O que funciona é documentação **gerada a partir do código real**, revisada por humano, e atualizada automaticamente quando o código muda.
### Skill: generate-docs
Gera documentação para um módulo, arquivo ou função específica, lendo o código real antes de escrever qualquer coisa.
`.claude/skills/generate-docs/SKILL.md`:
```yaml
---
name: generate-docs
description: Gera documentação técnica para um arquivo, módulo ou função a partir do código real
context: fork
agent: Explore
allowed-tools: Read Glob Grep Bash(git log *) Write Edit
---
Gere documentação para: $ARGUMENTS
## Como trabalhar
1. Leia o arquivo ou módulo solicitado por completo
2. Leia também os arquivos que ele importa (um nível de profundidade)
3. Leia os testes relacionados — eles revelam o comportamento esperado e os edge cases
4. Analise o histórico: `git log --oneline -- <arquivo>` mostra a evolução e intenção
## O que documentar
Para cada função/método/classe pública, escreva:
- **O que faz**: uma linha, sem rodeio
- **Parâmetros**: tipo, o que representa, valores especiais (`null`, `undefined`, array vazio)
- **Retorno**: o que volta e em que formato
- **Erros**: o que pode lançar e quando
- **Exemplo**: um uso real, não inventado — use os testes como base
## Formatos suportados
- **JSDoc/TSDoc** para TypeScript/JavaScript
- **Docstring** para Python
- **GoDoc** para Go
- **Markdown** para guias e READMEs
## Regras
- Não documente o óbvio. `// incrementa o contador` acima de `counter++` é ruído.
- Documente o não-óbvio: side effects, ordenação que importa, estado que precisa existir, comportamento em concorrência.
- Se o código é confuso, diga isso e sugira clarificação antes de documentar.
- Mostre o resultado antes de salvar. Aguarde aprovação.
Uso: /generate-docs src/payment/processor.ts
Skill: sync-docs
Compara a documentação existente com o código atual e identifica o que ficou defasado.
.claude/skills/sync-docs/SKILL.md:
---
name: sync-docs
description: Compara documentação existente com o código e atualiza o que ficou desatualizado
disable-model-invocation: true
allowed-tools: Read Glob Grep Bash(git log *) Bash(git diff *) Edit
---
Sincronize a documentação com o estado atual do código em: $ARGUMENTS
## Passos
1. Leia a documentação existente (README, docs/, comentários no código)
2. Leia o código atual dos módulos documentados
3. Compare: `git log --oneline -30 -- $ARGUMENTS` mostra o que mudou recentemente
## O que verificar
Para cada item documentado:
- **Assinatura de função**: parâmetros, tipos e retorno ainda batem?
- **Comportamento**: a descrição ainda descreve o que o código faz?
- **Exemplos**: ainda rodam? Ainda refletem o uso típico?
- **Links e referências**: apontam para arquivos/funções que ainda existem?
- **Seções inteiras**: cobrem features que foram removidas ou renomeadas?
## Saída
Gere um relatório com três seções:
**Desatualizado** — doc existe mas o código mudou (mostre a diferença)
**Faltando** — código novo que não tem documentação
**Obsoleto** — doc de algo que foi removido
Para cada item desatualizado ou faltando: mostre o patch proposto.
Aguarde aprovação antes de aplicar qualquer mudança.
Uso: /sync-docs src/api/
Skill: write-readme
Gera ou reescreve o README de um projeto ou módulo a partir do que existe no codebase — sem inventar nada.
.claude/skills/write-readme/SKILL.md:
---
name: write-readme
description: Gera ou reescreve README de um projeto ou submódulo a partir do codebase real
context: fork
agent: Explore
allowed-tools: Read Glob Grep Bash(git log *) Write
---
Escreva o README para: $ARGUMENTS
## Como trabalhar
Leia antes de escrever. Nessa ordem:
1. `package.json` / `pyproject.toml` / `go.mod` — nome, versão, scripts, dependências
2. Arquivos de entrypoint (`src/index.ts`, `main.go`, `app.py`)
3. Testes — revelam os casos de uso reais e o comportamento esperado
4. `.env.example` ou arquivos de config — variáveis e configuração necessária
5. `Dockerfile` ou `docker-compose.yml` — como rodar
6. Git log — contexto histórico do que o projeto faz
## Estrutura do README
```markdown
# Nome do Projeto
Uma linha descrevendo o que é e pra que serve.
## Requisitos
Lista de dependências com versões mínimas.
## Instalação
Comandos exatos, copiáveis, que funcionam.
## Configuração
Variáveis de ambiente necessárias com descrição e exemplo.
## Como usar
Exemplos reais dos casos de uso principais.
## Desenvolvimento
Como rodar localmente, como rodar testes, como fazer build.
## Arquitetura (opcional)
Só se a estrutura não for óbvia. Diagrama textual ou descrição das camadas.
Regras
- Cada comando no README deve ser testável. Se não puder verificar, sinalize.
- Não inclua seções vazias ou genéricas ("Contributing: PRs welcome").
- Prefira exemplos curtos e concretos a descrições longas.
- Se encontrar inconsistência entre o código e o que parece ser a intenção, aponte antes de escrever.
Mostre o resultado antes de salvar o arquivo.
Uso: `/write-readme .` (projeto inteiro) ou `/write-readme src/auth/` (módulo)
### Workflow: documentação pós-merge automática
Via GitHub Actions, toda vez que um PR é mergeado em `main`, o Claude verifica se a documentação precisa de atualização:
```yaml
# .github/workflows/doc-sync.yml
name: Doc Sync
on:
push:
branches: [main]
paths:
- 'src/**'
jobs:
sync:
runs-on: ubuntu-latest
permissions:
contents: write
pull-requests: write
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Check docs
uses: anthropics/claude-code-action@v1
with:
claude_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
direct_prompt: |
Arquivos em src/ foram modificados nesse push.
1. Compare os arquivos alterados com a documentação existente em docs/
2. Identifique o que ficou desatualizado
3. Se houver desatualização: atualize os arquivos de doc e abra um PR
com título "docs: sync with changes from <commit-sha>"
4. Se não houver nada desatualizado: não faça nada
Seja conservador — só atualize o que claramente mudou de comportamento.
O resultado: todo merge em main que muda código dispara uma verificação. Se a doc ficou pra trás, um PR de atualização é aberto automaticamente.
Routine agendada: auditoria semanal de docs
/schedule
Nome: weekly-doc-audit
Horário: toda segunda às 8h
Tarefa: Rode /sync-docs src/ no projeto minha-empresa/meu-repo.
Se encontrar itens desatualizados ou faltando, crie uma issue no GitHub
com título "docs: auditoria semanal — itens para atualizar"
e liste os itens encontrados com os arquivos afetados.
Uma issue toda segunda com o estado atual da documentação. O time decide o que priorizar no sprint.
Documentação de API — OpenAPI/Swagger
Para projetos com endpoints REST, o Claude consegue gerar ou atualizar a spec OpenAPI lendo as rotas diretamente:
Leia todos os arquivos em src/routes/ e gere uma spec OpenAPI 3.1 completa.
Para cada endpoint:
- Leia o schema de validação de input (Zod, Joi, class-validator)
- Leia o tipo de retorno
- Leia os testes do endpoint pra entender os casos de erro
- Documente: path, method, request body, query params, responses (sucesso e erro)
Salve em docs/openapi.yml e valide que o YAML é válido.
Economia de Tokens na Prática
Os princípios gerais de economia de tokens estão em Dicas de Desenvolvimento. Essa seção cobre os workflows concretos — hooks, skills e padrões de sessão que reduzem custo sem sacrificar qualidade.
Por que isso importa em time
Em uso individual, token é só dinheiro. Em time, token é dinheiro multiplicado pelo número de devs, mais latência, mais qualidade degradada quando a janela enche. Um hook mal configurado ou uma sessão "kitchen sink" que todo dev repete vira $500/mês jogados fora.
O custo médio é ~$13 por dev por dia ativo. Times que chegam em $30+ quase sempre têm um dos três problemas: output verboso entrando cru no contexto, CLAUDE.md inflado, ou sessões longas sem /clear.
Hook: filtrar output de testes
O maior desperdício individual. npm test com 500 testes produz milhares de linhas — e o Claude precisa de no máximo as linhas de falha.
~/.claude/hooks/filter-test-output.sh:
#!/bin/bash
input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command // ""')
# Só intercepta comandos de teste
if ! echo "$cmd" | grep -qE '^(npm test|pnpm test|yarn test|pytest|go test|jest|vitest)'; then
echo "{}"
exit 0
fi
# Reescreve o comando pra filtrar só falhas
filtered="$cmd 2>&1 | grep -A 10 -E '(FAIL|FAILED|ERROR|✗|×|error TS)' | head -150"
echo "{
\"hookSpecificOutput\": {
\"hookEventName\": \"PreToolUse\",
\"permissionDecision\": \"allow\",
\"updatedInput\": { \"command\": \"$filtered\" }
}
}"
Registro no ~/.claude/settings.json (global, funciona em todos os projetos):
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "~/.claude/hooks/filter-test-output.sh"
}
]
}
]
}
}
Impacto: 10.000 linhas de output viram 50–150. Multiplicado por cada execução de teste numa sessão, a diferença é absurda.
Hook: filtrar output de lint
Mesma ideia pro ESLint/Biome/Prettier:
~/.claude/hooks/filter-lint-output.sh:
#!/bin/bash
input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command // ""')
if ! echo "$cmd" | grep -qE '(eslint|biome|prettier|tsc)'; then
echo "{}"
exit 0
fi
# Mantém só erros e warnings, não os arquivos limpos
filtered="$cmd 2>&1 | grep -E '(error|warning|✖|⚠)' | head -100"
echo "{
\"hookSpecificOutput\": {
\"hookEventName\": \"PreToolUse\",
\"permissionDecision\": \"allow\",
\"updatedInput\": { \"command\": \"$filtered\" }
}
}"
Hook: limitar output de find e ls
#!/bin/bash
input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command // ""')
if ! echo "$cmd" | grep -qE '^(find|ls -la|ls -R)'; then
echo "{}"
exit 0
fi
# Limita a 200 linhas
filtered="$cmd 2>&1 | head -200"
echo "{
\"hookSpecificOutput\": {
\"hookEventName\": \"PreToolUse\",
\"permissionDecision\": \"allow\",
\"updatedInput\": { \"command\": \"$filtered\" }
}
}"
Skill: contexto enxuto para investigação
Em vez do Claude ler 40 arquivos e jogar tudo na janela principal, delega pra subagente e recebe só o resumo.
.claude/skills/investigate/SKILL.md:
---
name: investigate
description: Investiga um trecho do codebase e devolve resumo compacto — preserva o contexto principal
context: fork
agent: Explore
---
Investigue: $ARGUMENTS
Leia os arquivos relevantes, rastreie dependências e entenda o comportamento atual.
Retorne um relatório em no máximo 400 palavras:
1. **O que existe**: arquivos principais, responsabilidades, padrões usados
2. **Comportamento atual**: o que o código faz, edge cases relevantes
3. **Dependências**: o que importa e o que é importado por outros módulos
4. **Pontos de atenção**: código complexo, TODOs, comportamentos não-óbvios
Cite arquivos e linhas específicas. Seja denso — esse relatório vai alimentar uma implementação.
Uso: /investigate "como o sistema de autenticação lida com refresh de token"
O subagente lê o que precisar. A janela principal recebe 400 palavras.
Padrão de sessão: spec antes de implementar
O padrão que mais economiza token em features grandes. Em vez de deixar o Claude explorar e implementar na mesma sessão (acumulando leitura de arquivo + tentativas + correções na janela), você separa em duas sessões:
Sessão 1 — spec:
Quero implementar [descrição].
Antes de qualquer código:
1. Investigue como funcionalidades similares estão implementadas nesse projeto
2. Me entreviste sobre edge cases, integrações e trade-offs que eu possa não ter considerado
3. Escreva um SPEC.md com: objetivo, abordagem técnica, arquivos que vão mudar, critérios de aceite
Não escreva nenhum código ainda.
Sessão 2 — implementação (contexto limpo):
claude -n "feat/nome-da-feature"
Implemente o que está em SPEC.md. Siga os critérios de aceite à risca.
Rode os testes ao final. Se algum falhar, corrija antes de me chamar.
Por quê economiza: a exploração da sessão 1 não polui a sessão 2. A implementação começa com contexto limpo e um spec por escrito como referência, em vez de tentar reconstruir decisões a partir de uma conversa longa.
CLAUDE.md enxuto: o que vai e o que não vai
CLAUDE.md carrega em toda sessão. Cada linha custa token em cada mensagem. O que fica aqui precisa valer o custo.
Vai no CLAUDE.md:
## Build
- `pnpm dev` — servidor local
- `pnpm test` — testes (vitest)
- `pnpm lint` — ESLint + Biome
- `pnpm build` — produção
## Padrões que o Claude não vai adivinhar
- Handlers em `src/routes/`, lógica em `src/services/`
- Tipagem compartilhada em `src/types/index.ts`
- Nunca `any` — usa `unknown` + type guard
- Zod em todo input externo (API e formulário)
## Git
- Conventional Commits obrigatório
- PR sempre contra `develop`
Não vai no CLAUDE.md:
# NÃO FAZ ISSO ❌
## Arquitetura
[500 linhas explicando cada pasta do projeto]
## Boas práticas
- Escreva código limpo
- Use nomes descritivos
- Não esqueça de testar
## Como usar React
[Tutorial de React que o modelo já sabe]
Regra: se o Claude descobriria lendo o código, não coloca. Se você colocaria em qualquer projeto, não coloca. Se mudou no mês passado, provavelmente vai mudar de novo — não coloca.
Checklist de sessão eficiente
Para colar no CLAUDE.md do time como lembrete:
## Como usar o Claude Code aqui
Antes de cada sessão:
- [ ] `/clear` se mudou de tarefa
- [ ] Use plan mode (`Shift+Tab`) pra mudanças em mais de 3 arquivos
- [ ] Dê critério de verificação: "rode os testes e corrija falhas"
Durante:
- [ ] `/cost` se sentir que a sessão ficou pesada
- [ ] `Esc` pra parar e redirecionar, não fique esperando ele terminar errado
- [ ] Se corrigiu 2x o mesmo problema: `/clear` e começa de novo
Modelos:
- Sonnet → coding geral (padrão)
- Opus → arquitetura, debugging difícil, decisões complexas
- Haiku → subagents de sumarização e classificação simples
Auditoria de custo por sessão
# Ver custo da sessão atual
/cost
# Exportar histórico de uso (via API)
claude -p "liste as 10 sessões mais caras do último mês" --output-format json
Se um dev está consistentemente acima de $30/dia, o mais comum é:
- Sessões longas sem
/clearentre tarefas diferentes - CLAUDE.md com mais de 300 linhas
- Output de teste ou lint entrando cru sem filtro de hook
- Uso de Opus em tarefas que Sonnet resolve
Conclusão
Esses casos têm uma estrutura em comum: uma skill pra acionar o workflow, um subagente pra trabalho pesado que não deve poluir o contexto principal, e ferramentas CLI (gh, kubectl, aws) que o Claude usa nativamente sem overhead de MCP.
O padrão pra criar o seu próprio use case:
- Descreve o workflow em linguagem natural
- Identifica quais CLIs ou MCPs dão acesso ao sistema externo
- Cria a skill com os
allowed-toolscertos edisable-model-invocation: truese tem side effects - Testa interativamente primeiro, depois automatiza
Qualquer coisa que você faz repetidamente e segue uma sequência de passos — é candidato a virar skill.
Anterior: Git e Workflows de Desenvolvimento
Referências: