O guia de setup do Claude Code que mudou minha forma de trabalhar

Ontem, um vencedor de hackathon da Anthropic compartilhou publicamente seu guia de configuração do Claude Code, e eu apliquei tudo na hora. Passei o dia inteiro nisso, e a diferença foi real.

O guia é do affaan (@affaanmustafa), que usa o Claude Code diariamente há 10 meses. Lendo a configuração dele, meu primeiro pensamento foi: “O que eu estava fazendo esse tempo todo?”

O guia está disponível como repositório no GitHub, e a mensagem central é clara: não é sobre ter mais, é sobre ter exatamente o que você precisa.

A janela de contexto de 200K é um mito - o número real é 70K

A janela de contexto de 200K do Claude Code é um máximo teórico. Se você carrega servidores MCP e plugins demais, o contexto utilizável cai para cerca de 70K.

A abordagem do affaan:

1. Configurar 14 servidores MCP, mas ativar apenas 5-6 por projeto.
2. Manter menos de 80 ferramentas habilitadas ao mesmo tempo.

A config real dele inclui GitHub, Supabase, Vercel, Railway, a série Cloudflare, ClickHouse e mais - 14 servidores no total. Mas ele desabilita explicitamente os que não está usando via disabledMcpServers. Depois que adotei esse padrão, a qualidade das respostas melhorou visivelmente.

Skills vs Hooks vs Subagentes - a separação de responsabilidades é o que importa

Esses três conceitos confundem no começo, mas a distinção faz toda a diferença.

• Skills: Ficam em ~/.claude/skills. Executam um fluxo de trabalho inteiro com um único comando como /refactor-clean.
• Hooks: Automação baseada em eventos. Formatar automaticamente com Prettier ao editar arquivos .ts, alertar sobre console.log, e por aí vai. O plugin hookify permite gerar hooks por conversa.
• Subagentes: Ficam em ~/.claude/agents. Papéis dedicados como planner, architect, tdd-guide e security-reviewer que executam tarefas delegadas.

O affaan posiciona hooks em três pontos de execução - PreToolUse, PostToolUse e Stop - automatizando formatação, verificação de tipos e auditorias de segurança. Esse padrão também foi endossado por Boris Cherny.

mgrep e Git Worktrees são divisores de águas

As dicas práticas mais impactantes do guia:

mgrep

Mais preciso que o ripgrep, com suporte integrado a busca na web. Um único comando como /mgrep 'function handleSubmit' pesquisa arquivos locais e a web ao mesmo tempo.

Git Worktrees

Quando você trabalha em várias funcionalidades ao mesmo tempo, crie checkouts independentes e rode o Claude Code em cada um. Também dá para usar /fork para ramificar conversas. Existe um debate em andamento sobre se worktrees ou clones de repositório são a melhor abordagem - ambos têm prós e contras dependendo do seu workflow.

Editor Zed

Construído em Rust, então continua leve. O Agent Panel acompanha as modificações de arquivos do Claude em tempo real, e CMD+Shift+R executa comandos customizados na hora.

Estrutura de regras para manter consistência

Modularize ~/.claude/rules por responsabilidade:

• security.md - Sem segredos hardcoded
• coding-style.md - Imutabilidade, diretrizes de estrutura de arquivos
• testing.md - Fluxo TDD, cobertura mínima de 80%
• git-workflow.md - Formato de mensagem de commit
• performance.md - Critérios de seleção de modelo

Adicione regras como “nunca commitar console.log” aqui, e depois reforce com um hook Stop que audita suas alterações. Erros desaparecem quando a automação pega antes de ir pra produção.

Os princípios centrais

O affaan destila sua filosofia em cinco princípios:

• Trate a configuração como fine-tuning, não como arquitetura. Ajustes pequenos e direcionados valem mais que reformas radicais.
• A janela de contexto é preciosa. Desabilite tudo que não estiver usando ativamente.
• Aproveite a execução paralela. Use /fork e worktrees para rodar agentes simultaneamente.
• Automatize o trabalho repetitivo. Hooks eliminam etapas manuais que te atrasam.
• Limite o escopo dos subagentes. Dê a cada agente uma responsabilidade estreita e bem definida.

Configuração excessiva é contraproducente. Manter ativas apenas as ferramentas que você realmente usa - isso sim é produtividade de verdade. Subtrair é a parte mais difícil pra maioria das pessoas, e esse guia é um lembrete forte disso.

Uma nota pessoal: para automação de browser, achei o agent-browser da Vercel muito mais estável que o Playwright e ferramentas similares mencionadas no guia original. A velocidade e a variedade de tarefas que ele resolve estão em outro patamar.

O setup completo está disponível no repositório do affaan no GitHub. Em vez de copiar tudo de uma vez, entenda o raciocínio por trás de cada escolha e adapte ao seu próprio workflow. É aí que está o valor de verdade.