Conteúdo Detalhado
🔧 Refatorando Arquivo Grande sem Estourar Contexto
Service de 2000 linhas, dividir em regiões, plan mode, checkpoints, /compact entre regiões. 6 passos executáveis com prompts prontos.
Você abre um service.ts de 2000 linhas pela primeira vez. Se começar refatorando direto, vai editar às cegas e estourar sessão.
Entra em plan mode, pede leitura estruturada: responsabilidade, blocos lógicos, dependências externas. Lista, não prose.
Mapa mental do arquivo em ~2k tokens de output. Base para todos os passos seguintes sem releituras.
Refatorar o arquivo inteiro numa tacada só é suicídio — estoura contexto, quebra testes, perde trabalho.
Pedir ao Claude para propor 4–6 regiões ordenadas por risco crescente, com objetivo e tamanho estimado para cada.
Plano executável em etapas. Você escolhe o ritmo. Risco baixo primeiro = confiança acumulada.
Claude tende a "continuar ajudando" além do escopo, tocando em código que não pediu. Isso suja o contexto.
Comando explícito: execute a região X, não toque em nada fora dela, ao terminar pare. Checkpoint obrigatório antes da próxima.
Escopo controlado. Cada região vira um commit independente, reversível. Context rot controlado.
Pular testes entre regiões = descobrir 5 bugs acumulados no final, sem saber qual região quebrou o quê.
"Rode os testes. Se passarem, commit. Se falharem, me diga antes de consertar." Mensagem padrão refactor(service): região X — descrição.
Reversibilidade garantida. git bisect resolve qualquer regressão em segundos.
Após 2–3 regiões, contexto já está em 40%+ da janela. Se continuar, próximas regiões saem piores por atenção diluída.
/compact mantenha foco em arquitetura e decisões, pode resumir tentativas. Preserva o que importa, descarta iterações.
Contexto volta a 10–15%. Próximas regiões saem com qualidade igual às primeiras.
Acabou a refatoração. Se simplesmente fechar, perde a memória do que foi decidido e por quê.
Handoff estruturado (template da Trilha 3), commit final com resumo, /clear ou nova sessão para próxima tarefa.
Continuidade — amanhã outra pessoa (ou você) pega o fio sem reconstruir contexto do zero.
🐛 Debug em Projeto Que Nunca Vi
"O botão X não funciona" num repo desconhecido. Subagentes para explorar, hipóteses ordenadas, fix + teste + docs. 6 passos.
Explorar código desconhecido na sessão principal polui tudo — dezenas de arquivos lidos antes de você ter uma hipótese.
Delega a um subagente Explore: achar onde "botão X" é renderizado e todos os handlers. Só caminhos + resumo de 5 linhas.
Contexto principal recebe apenas o destilado (~500 tokens) em vez de 50k de arquivos brutos.
Sem reproduzir o bug você está debugando baseado em relato, não em fato. Qualquer fix vira suposição.
"Quais comandos rodar para reproduzir o bug localmente? Só a sequência, sem explicação." Roda. Vê o bug com os próprios olhos.
Sinal binário: fix funcionou ou não. Sem ambiguidade.
Chutar hipóteses aleatórias = mexer em código à toa. Cada tentativa errada suja o contexto e pode introduzir regressão.
Lista 3–5 hipóteses ordenadas. Para cada: razão + como testar. Força o Claude a raciocinar antes de agir.
Plano de investigação. Em 80% dos casos, a hipótese 1 acerta — resolve rápido.
Testar duas hipóteses juntas = se resolver, você não sabe qual foi. Se quebrar, idem.
"Vamos testar a hipótese 1. Que alteração mínima confirma ou descarta?" Mínima = 1–3 linhas, reversível.
Método científico. Cada iteração produz informação clara, não ruído.
Identificou a causa. Aplicar o fix sem cobrir com teste = regressão na próxima refatoração.
"Aplique o fix. Rode o teste do botão X. Se passar, commit com mensagem descritiva." Teste primeiro, fix depois.
Bug fechado com proteção anti-regressão. Mensagem de commit conta a história.
Daqui a 3 meses, alguém vai cair no mesmo bug (ou similar). Sem nota, refaz a investigação inteira.
Nota curta em docs/debugging.md: onde está o código, o que era o bug, como reconhecer se reaparecer. Máx 10 linhas.
Memória organizacional. Próximo debug começa do passo 3, não do zero.
📚 Documentando Código Legado em 3 Sessões
Projeto grande sem docs. Divisão em 3 sessões com handoff entre cada uma. Subagentes paralelos, CLAUDE.md, cálculo de custo real.
Repo grande, sem docs. Se tentar documentar tudo numa sessão só, estoura em 30 minutos.
Sessão dedicada a inventário: árvore, módulos raiz, fluxo principal, stack. Produto: ARCHITECTURE.md < 80 linhas.
Artefato durável que orienta as próximas 2 sessões. Investigação concentrada em 1 arquivo.
Inventário pronto. Continuar na mesma sessão = carregar toda a exploração do repo para a próxima tarefa.
"Produza handoff estruturado. Vou limpar sessão e abrir nova." O ARCHITECTURE.md é o handoff principal.
Sessão 2 começa com contexto zero + 1 arquivo curto. Qualidade máxima para a próxima etapa.
Documentar 5 módulos em série = sessão longa, contexto acumula, qualidade cai no 4º.
5 subagentes em paralelo, um por módulo. Cada um produz docs/[modulo].md. Você só orquestra.
Paralelismo real. Tempo de 5× vira 1×. Contexto principal fica ~5k tokens, não 50k.
Subagentes não se falam — podem escrever o mesmo conceito de 5 jeitos diferentes.
"Leia os 5 arquivos e me diga: está consistente? Falta algo?" Ajustes rápidos. Handoff para sessão 3.
Docs harmonizados sem reescrever. Sessão 2 fecha limpa.
Docs de módulo existem. Falta o "como começar": setup, convenções, onde achar o quê.
CONTRIBUTING.md (humanos) + CLAUDE.md curto < 100 linhas (agentes). Convenções consistentes nos dois.
Onboarding de humano e agente resolvido. Próximo contribuidor começa em minutos, não horas.
Fluxo em 3 sessões: ~180k tokens de input. Fluxo em 1 sessão: ~900k com context rot no fim.
Calcular: US$ 1,20 vs US$ 6,00 com Sonnet 4.6. 5× mais barato e melhor qualidade.
Prova numérica. Split de sessão não é capricho — é economia mensurável.
🌟 Awesome Lists — Bibliotecas Curadas
6 repositórios com milhares de skills, plugins, agents e comandos para Claude Code. Mapa do ecossistema — comece aqui quando precisar de algo pronto.
A awesome list mais abrangente de Claude Code. Categorizada por: skills, hooks, slash commands, agent orchestrators, applications e plugins.
Antes de reinventar a roda. Procure aqui primeiro quando pensar "será que já existe um...".
Toolkit extenso: 135 agents, 35 skills curadas (+400k via SkillKit), 42 commands, 176+ plugins, 20 hooks, 15 rules, 7 templates, 14 MCP configs, 26 companion apps.
Quando quiser um "starter pack" robusto pronto para copiar. Ideal para equipes montando um ambiente padrão.
Lista focada em skills — a mecânica nova que permite empacotar capacidades específicas carregadas sob demanda. Organizada por caso de uso.
Quando /skill list parecer vazio. Aqui você encontra skills para formato de docs, revisão, design, automação.
Coleção com 1000+ skills compatíveis com Claude Code, Codex, Gemini CLI, Cursor e outros. Inclui skills oficiais de times como Anthropic, Google Labs, Vercel, Stripe, Cloudflare.
Se você alterna entre CLIs, ou quer skills mantidas por empresas (não só comunidade). É o catálogo mais amplo.
Lista da Composio focada em skills, recursos e ferramentas para customizar workflows com Claude AI. Foco em integrações com APIs externas.
Quando o caso de uso envolve integração com serviços (Slack, GitHub, Linear, Notion). A Composio mantém conectores nativos.
Coleção automatizada de métricas de adoção de plugins Claude Code em repositórios GitHub — atualizada via workflows n8n. Você vê o que a comunidade realmente usa.
Para decidir entre dois plugins com funcionalidade parecida. "Quantas pessoas realmente adotaram?" vira um filtro objetivo.