O workflow com Claude Code que substituiu minha equipe

O workflow com Claude Code que substituiu minha equipe

Seis semanas atrás, assisti a uma engenheira sênior entregar um sistema completo de autenticação, uma integração de pagamentos e a reformulação de um dashboard — tudo em uma única tarde. Não eram protótipos. Não eram demos descartáveis. Código de produção, com testes, segurança de tipos e um histórico limpo no Git. Ela mantinha três sessões do Claude Code rodando simultaneamente, cada uma em seu próprio worktree, cada uma cuidando de uma funcionalidade diferente enquanto ela revisava pull requests do lote anterior.

Perguntei quanto tempo levou para construir esse fluxo de trabalho. “Cerca de uma semana de prática deliberada”, ela respondeu. “Mas a resposta real é que parei de tratar o Claude como um chatbot e comecei a tratá-lo como um engenheiro júnior que precisa de estrutura para entregar seu melhor trabalho.”

Essa perspectiva ficou comigo. Eu já usava o Claude Code há meses naquele ponto — entregando projetos, construindo sistemas de agentes, escrevendo sobre isso o tempo todo. Mas meu fluxo de trabalho ainda era, em sua maioria, reativo. Prompt, gerar, revisar, corrigir, prompt de novo. O ciclo funcionava, mas estava deixando uma produtividade enorme na mesa.

Foi então que me deparei com a análise da Maddy. Maddy é uma engenheira de software sênior que já trabalhou no Google, Amazon, IBM e Microsoft — não é alguém dado a exageros. A abordagem dela com o Claude Code não envolve prompts engenhosos ou recursos ocultos. É uma metodologia completa: nove práticas interligadas que transformam o Claude de um chatbot gerador de código em algo que funciona como uma equipe de engenharia autônoma. Passei o último mês implementando cada parte desse método, e os resultados me forçaram a repensar como estruturo cada projeto.

Aqui está o sistema, peça por peça, com tudo que aprendi tentando fazê-lo funcionar na prática.

Por Que a Maioria dos Desenvolvedores Encontra um Limite com o Claude Code

Existe um padrão que observo nas comunidades de desenvolvedores que é tão consistente que poderia ser considerado uma lei da natureza. Alguém descobre o Claude Code. Gera alguns componentes, sente a empolgação do desenvolvimento assistido por IA e começa a dizer para todo mundo que aquilo é o futuro. Duas semanas depois, está frustrado. Os bugs se multiplicam. A IA sugere funções que não existem. As janelas de contexto estouram e o Claude começa a contradizer suas próprias sugestões anteriores.

A reação padrão é culpar o modelo. “Não é inteligente o suficiente para projetos reais” ou “funciona para exemplos simples, mas não para código de produção.” Eu mesmo já disse ambas as coisas em diferentes momentos.

O verdadeiro problema quase nunca é o modelo. É a ausência de estrutura ao redor do modelo.

Pense assim: se você contratasse o engenheiro júnior mais talentoso do planeta e não desse nenhum onboarding, nenhum padrão de codificação, nenhum processo de revisão e nenhum conjunto de testes — ele produziria caos. Não por falta de habilidade, mas porque habilidade sem estrutura gera resultados inconsistentes. O Claude Code é igual. A inteligência bruta é extraordinária. Mas inteligência sem workflow produz exatamente os sintomas de que os desenvolvedores reclamam: implementações desalinhadas, aumento no número de bugs e a sensação crescente de que você está gastando mais tempo corrigindo a saída da IA do que gastaria escrevendo o código você mesmo.

A metodologia da Maddy resolve isso ao envolver o Claude Code no mesmo tipo de disciplina de engenharia que você aplicaria a uma equipe humana. Cada etapa existe para prevenir um tipo específico de falha que eu mesmo já experimentei. E o efeito composto — todas as nove práticas funcionando juntas — é o que gera os ganhos de produtividade “isso não pode ser real” que parecem marketing até você experimentar.

O porém? Você precisa implementá-las de forma deliberada. Pular etapas não só reduz o benefício — mina todo o sistema. Aprendi isso da maneira difícil quando tentei pular o modo de planejamento para tarefas “simples” e acabei gastando três horas depurando o que deveria ter sido uma funcionalidade de quinze minutos.

Passo 1: Construa um CLAUDE.md Que Realmente Funcione

Todo fluxo de trabalho estruturado do Claude Code começa com o CLAUDE.md, e a abordagem da Maddy para esse arquivo é mais disciplinada do que normalmente vejo.

Quando você executa /init em qualquer novo codebase, o Claude faz uma análise estrutural e gera esse arquivo automaticamente. Ele captura a descrição do seu projeto, a estrutura de arquivos, caminhos-chave, comandos de desenvolvimento, convenções de codificação e stack tecnológico. A versão gerada automaticamente já é um ótimo ponto de partida — dramaticamente melhor do que escrever do zero, que era o que eu fazia antes de aceitar que a autoanálise do Claude captura detalhes que eu esqueceria.

Mas é aqui que a Maddy se distancia do conselho típico: ela mantém o CLAUDE.md entre 100 e 200 linhas. Não 300. Não 500. Cem a duzentas.

Esse limite me pareceu agressivo no início. Meus próprios arquivos CLAUDE.md já tinham passado de 400 linhas em alguns projetos — decisões arquiteturais, padrões de código, trechos de exemplo, contexto histórico. Parecia completo. Na verdade, era desperdício. Cada token no CLAUDE.md é carregado em toda conversa. Um arquivo de 500 linhas consome silenciosamente uma parte significativa da sua janela de contexto antes mesmo de você digitar o primeiro prompt. Falei sobre isso em detalhes no meu guia com 50 dicas de Claude Code, mas a versão curta é: arquivos de contexto inchados são uma das principais razões para a queda de qualidade das respostas do Claude no meio da sessão.

O que deve estar no arquivo: descrição do projeto e funcionalidades principais, estrutura de arquivos e caminhos-chave, comandos de build/test/lint (para que o Claude possa validar seu próprio trabalho), convenções de codificação e stack tecnológico, e regras rígidas que o Claude nunca deve violar. O que não deve estar: exemplos de código (o Claude pode ler seu codebase real), explicações longas de decisões passadas, qualquer coisa que duplique seu README e qualquer coisa que não tenha sido relevante nas últimas duas semanas.

A restrição de 100 a 200 linhas força você a priorizar. Cada linha precisa justificar sua presença. E essa priorização implacável é exatamente o que torna a janela de contexto eficiente o suficiente para o restante deste fluxo de trabalho funcionar.

Mais uma coisa que a Maddy enfatiza e que agora pratico religiosamente: trate o CLAUDE.md como um documento vivo. Quando o Claude comete um erro e você corrige, adicione uma regra que impeça que esse erro se repita. Com o tempo, o arquivo se torna um registro destilado de cada lição que seu projeto ensinou à IA. Boris Cherny, o criador do Claude Code, faz exatamente isso com um arquivo lessons.md — toda correção vira uma regra permanente. O arquivo literalmente ensina a si mesmo a ser melhor para o seu codebase específico.

Etapa 2: Modo de Planejamento Antes de Qualquer Alteração

Esta é a prática de maior impacto em todo o fluxo de trabalho da Maddy — e justamente a que a maioria dos desenvolvedores ignora porque parece desacelerar o processo.

O modo de planejamento (ativado com Shift+Tab no CLI) instrui o Claude a analisar sua base de código e elaborar um plano de implementação antes de escrever qualquer código. Ele revisa quais arquivos precisam ser alterados, quais caminhos lógicos serão afetados, onde estão os riscos e como a mudança se encaixa na arquitetura existente. Você recebe um detalhamento claro do que o Claude pretende fazer — e, crucialmente, pode aprovar, modificar ou rejeitar esse plano antes que qualquer linha de código seja alterada.

O critério prático que adotei: use o modo de planejamento para qualquer tarefa que envolva mais de um arquivo. Para alterações em um único arquivo — renomear uma variável, corrigir um erro de digitação, adicionar um comentário — basta deixar o Claude executar diretamente. Para qualquer coisa estrutural, planeje primeiro.

Veja por que isso é tão importante na prática. Sem o modo de planejamento, o Claude às vezes escreve código perfeitamente funcional no lugar totalmente errado. Uma vez pedi para adicionar limitação de taxa a uma API e ele criou um novo arquivo de middleware em vez de adicionar ao existente, que já cuidava da autenticação. O código estava correto. A arquitetura, não. Só percebi três funcionalidades depois, quando notei que tinha duas cadeias de middleware rodando de forma independente.

Com o modo de planejamento, eu teria visto "Criar novo arquivo: middleware/rateLimiter.js" no plano e imediatamente corrigido para "Modificar arquivo existente: middleware/auth.js — adicionar lógica de limitação de taxa." Dez segundos de revisão economizaram três horas de refatoração.

O ciclo de planejar-revisar-executar que a Maddy defende — e que agora considero inegociável — funciona assim:

1. Descreva a tarefa em detalhes (quanto mais específico, melhor)
2. Ative o modo de planejamento e deixe o Claude analisar a base de código
3. Revise o plano: corrija caminhos de arquivos, questione decisões arquiteturais, adicione restrições
4. Aprove o plano e deixe o Claude executar
5. Revise o resultado em relação ao plano original

Alguns engenheiros vão além. Já vi fluxos de trabalho em que uma sessão do Claude elabora o plano e uma segunda sessão o revisa “como engenheiro sênior” antes do início da execução. Testei isso em uma migração de banco de dados complexa e a sessão de revisão identificou dois casos extremos que a sessão de planejamento não percebeu. Exagero para a maioria das tarefas. Inestimável para qualquer coisa que envolva dados de produção.

Etapa 3: Limpe o Contexto Após Cada Tarefa

Esta etapa parece simples demais para ser importante. Mas não é. Na verdade, talvez seja a prática mais subestimada de todo o fluxo de trabalho.

Após concluir cada tarefa discreta, execute /clear para redefinir a janela de contexto do Claude. Todo arquivo que o Claude lê, toda saída de comando que ele processa, cada mensagem na conversa — tudo isso se acumula em um orçamento de contexto compartilhado. Quando esse orçamento se esgota, o Claude começa a perder o fio das instruções anteriores. Os sintomas são sutis no início: código um pouco menos preciso, inconsistências ocasionais com seus padrões de codificação, sugestões que não correspondem exatamente ao que você pediu. Depois, esses problemas se acumulam até que você se vê depurando uma saída da IA que contradiz sugestões feitas por ela mesma vinte minutos antes.

Eu costumava tratar o /clear como algo a ser feito quando as coisas davam errado. Maddy trata como higiene — algo que você faz após cada tarefa bem-sucedida, antes que algo dê errado. A diferença é entre ser preventivo e ser reativo, e a abordagem preventiva é dramaticamente mais eficiente.

O fluxo de trabalho passa a ser: concluir a tarefa, verificar se está funcionando, fazer o commit e, então, /clear antes de iniciar a próxima tarefa. Folha limpa. Orçamento de contexto totalmente disponível para o próximo problema. Nenhum ruído acumulado da conversa anterior.

Uma consideração prática: se sua próxima tarefa depende fortemente do contexto da atual, você pode levar os detalhes essenciais no próximo prompt, em vez de depender da memória do Claude. "Acabei de adicionar limitação de taxa ao middleware de autenticação. Agora preciso adicionar testes correspondentes para o comportamento de limitação de taxa" fornece ao Claude exatamente o contexto necessário, sem a bagagem de tudo o que aconteceu na sessão anterior.

Só essa prática eliminou cerca de 40% dos momentos em que “o Claude está agindo estranho” que eu costumava experimentar. E ela combina perfeitamente com o modo de planejamento — você sempre começa cada tarefa com um contexto limpo e um plano deliberado, em vez de construir sobre o ruído acumulado.

Etapa 4: Comandos de Barra para Prompts Repetitivos

Todo desenvolvedor tem prompts que digita repetidamente. “Revise este código em busca de vulnerabilidades de segurança.” “Escreva testes unitários para esta função.” “Refatore isso para seguir o padrão de repositório.” Digitar essas instruções várias vezes não é apenas tedioso — isso introduz variação. Seu prompt de quinta-feira para revisão de código não será idêntico ao de segunda-feira, e essa variação gera resultados diferentes (e frequentemente piores).

Os comandos de barra resolvem isso ao transformar seus melhores prompts em gatilhos reutilizáveis. Eles são arquivos Markdown armazenados em .claude/commands/ (ou .claude/skills/ — desde o início de 2026, estes diretórios são praticamente unificados) que o Claude executa quando você digita o comando de barra correspondente.

Veja um exemplo prático. Tenho um comando chamado /security-review que contém um prompt detalhado, refinado ao longo de dezenas de iterações:

# Security Review

Revise as alterações atuais em busca de vulnerabilidades de segurança. Verifique:

1. Vetores de injeção de SQL em quaisquer consultas ao banco de dados
2. Vulnerabilidades de XSS na saída renderizada
3. Oportunidades de bypass de autenticação/autorização
4. Exposição de dados sensíveis em logs ou mensagens de erro
5. Proteção CSRF em endpoints que alteram estado
6. Lacunas de validação de entrada em dados fornecidos pelo usuário

Para cada problema encontrado:
- Classifique a gravidade (Crítico / Alto / Médio / Baixo)
- Mostre o código vulnerável
- Forneça a versão corrigida
- Explique o vetor de ataque

Se nenhum problema for encontrado, confirme que o código passou na revisão com um breve resumo.

Agora, em vez de tentar lembrar todas as seis categorias de verificação toda vez, digito /security-review e obtenho resultados consistentes e completos. O prompt já foi testado em batalha. O resultado é confiável. E economizei os três minutos que gastaria compondo a instrução de cabeça.

Maddy recomenda criar comandos de barra para todo prompt que você digitou mais de três vezes. Eu iria além — crie comandos para qualquer prompt em que a consistência seja mais importante do que a criatividade. Revisão de código, geração de testes, atualização de documentação, scaffolding de endpoints de API, planejamento de migração de banco de dados. Esses são fluxos de trabalho em que você quer resultados previsíveis e de alta qualidade todas as vezes.

Os comandos são apenas arquivos Markdown, então ficam sob controle de versão. Você pode compartilhá-los com sua equipe. Pode iterar sobre eles ao longo do tempo — e toda melhoria beneficia todas as execuções futuras. Mantenho cerca de quinze comandos de barra ativos nos meus projetos. Os três que mais uso provavelmente me economizam trinta minutos por dia.

Etapa 5: Ganchos de Validação Que Permitem ao Claude se Auto-Corrigir

É aqui que o fluxo de trabalho deixa de ser apenas “prompting estruturado” e realmente começa a parecer que você está trabalhando com um engenheiro autônomo.

Ganchos de validação são verificações automatizadas que rodam após cada edição feita pelo Claude. Construa o projeto. Execute a suíte de testes. Rode o verificador de tipos. Se algo falhar, o Claude vê a saída de erro e tenta corrigir automaticamente — sem intervenção sua. A IA entra em um ciclo de auto-correção: edita, valida, vê a falha, corrige, valida novamente, repete até que tudo passe.

Esse é o recurso que Maddy credita como a maior melhoria de qualidade individual em seu fluxo de trabalho. E Boris Cherny, criador do Claude Code, argumenta que dar ao Claude um ciclo de feedback melhora a qualidade do resultado final de duas a três vezes em comparação ao método “gerar e rezar”.

Configurar ganchos na sua configuração do Claude Code fica assim:

{
  "hooks": {
    "postEdit": [
      "npm run build",
      "npm run test",
      "npm run typecheck"
    ]
  }
}

Toda vez que o Claude modifica um arquivo, esses três comandos são executados automaticamente. Se a build quebra, o Claude vê o erro. Se um teste falha, o Claude vê qual asserção não passou e por quê. Se o verificador de tipos encontra um tipo incompatível, o Claude vê o arquivo e a linha exatos.

O principal insight: sem ganchos, o Claude verifica seu trabalho usando apenas seu próprio julgamento. O que parece razoável até você lembrar que o julgamento do Claude se degrada à medida que o contexto se enche. Testes e verificações de build são uma fonte externa de verdade que permanece precisa independentemente da pressão de contexto. Cada ciclo de vermelho para verde fornece ao Claude um feedback inequívoco, verificado por máquina, sobre o qual ele pode agir sem esperar por você.

Quero ser honesto sobre as limitações aqui. Ganchos adicionam tempo a cada ciclo de edição. Se sua suíte de testes leva 90 segundos, são 90 segundos de espera após cada alteração. Para iteração rápida em componentes de UI, onde o feedback é visual, às vezes desativo os ganchos temporariamente. Mas para qualquer coisa que envolva lógica de negócio, endpoints de API ou modelos de dados — os ganchos permanecem ativados. O tempo que eles adicionam é uma fração do tempo de depuração que eles evitam.

Mais uma nuance que a Maddy enfatiza e que validei na prática: ganchos são determinísticos. O CLAUDE.md é orientativo — o Claude o segue em cerca de 80% das vezes. Ganchos são executados 100% das vezes. Se algo precisa acontecer após toda edição, sem exceção — formatação, lint, verificações de segurança — faça disso um gancho, não uma regra do CLAUDE.md.

Etapa 6: Sessões Paralelas e Git Worktrees

É aqui que o multiplicador de produtividade fica absurdo.

A maioria dos desenvolvedores executa uma sessão do Claude Code por vez. Uma tarefa, um branch, um pipeline sequencial. Maddy executa várias sessões simultaneamente — algumas em abas do terminal, outras em painéis do IDE — cada uma lidando com uma tarefa completamente independente. O segredo para que isso funcione sem mergulhar no caos de conflitos do Git: cada sessão opera em seu próprio worktree do Git.

Um worktree é um diretório de trabalho separado vinculado ao mesmo repositório. Cada um tem seu próprio branch checado. Alterações em um não afetam os outros. O Claude Code tem suporte nativo a worktree — você pode iniciar uma sessão em seu próprio workspace isolado com um único comando.

O fluxo de trabalho prático:

1. Crie um worktree para cada feature: git worktree add ../auth-feature feature/auth
2. Abra uma sessão do Claude Code em cada worktree
3. Dê a cada sessão sua tarefa e deixe-as trabalhar de forma independente
4. Revise e faça o merge quando cada feature estiver pronta

Normalmente, executo três sessões paralelas. Mais do que isso e o tempo gasto em revisão começa a consumir o ganho de tempo. Três parece ser o ponto ideal, onde cada sessão recebe atenção suficiente sem se tornar um pesadelo de troca de contexto para mim.

A mudança de mentalidade aqui é significativa. Você deixa de se ver como um desenvolvedor que programa com ajuda da IA. Passa a se enxergar como um gerente de engenharia dirigindo uma equipe de desenvolvedores de IA. Seu trabalho não é escrever código — é planejar o trabalho, atribuí-lo às sessões certas, revisar o resultado e tomar decisões arquiteturais. A geração real de código acontece em paralelo, em múltiplos fluxos de trabalho independentes.

Se você quiser um mergulho completo sobre como configurar worktrees com o Claude Code — incluindo a pegadinha sutil onde commits podem cair no main quando você acha que estão indo para um branch de feature — escrevi um guia completo que cobre todos os casos de borda que já enfrentei.

Se preferir que alguém configure esse tipo de ambiente de desenvolvimento multi-agente para sua equipe, faço consultorias de automação de workflow. Você pode ver o que já construí em fiverr.com/s/EgxYmWD.

Etapa 7: Subagentes para Subtarefas Isoladas

Sessões paralelas lidam com funcionalidades separadas. Subagentes lidam com preocupações distintas dentro de uma única funcionalidade.

Um subagente é um agente de IA leve e isolado, criado pela sua sessão principal do Claude para tratar uma subtarefa específica. A palavra-chave é "isolado" — cada subagente recebe seu próprio prompt de sistema, suas próprias permissões de ferramentas e sua própria janela de contexto. Ele executa sua tarefa e retorna os resultados sem poluir o contexto da sessão principal.

O Claude Code vem com três tipos de subagentes integrados: Explore (somente leitura, otimizado para velocidade e custo), Plan (coleta contexto antes de apresentar uma estratégia) e um agente de uso geral que lida com tarefas que exigem tanto exploração quanto modificação.

Mas o verdadeiro poder está nos subagentes personalizados. O exemplo da Maddy que fez tudo fazer sentido para mim: criar um subagente focado em segurança que revisa alterações de código sob uma ótica de segurança enquanto a sessão principal continua desenvolvendo funcionalidades. O agente de segurança tem seu próprio prompt de sistema carregado com verificações do OWASP Top 10 e as políticas de segurança da sua organização. Ele opera de forma independente, sinaliza problemas e suas descobertas não poluem o contexto da sessão principal.

Veja como uso subagentes na prática:

• Agente de revisão de segurança: Roda em paralelo ao desenvolvimento de funcionalidades, verifica cada alteração em busca de vulnerabilidades
• Agente de documentação: Gera e atualiza a documentação conforme a base de código evolui, isolado do contexto de implementação
• Agente de geração de testes: Escreve casos de teste para funcionalidades concluídas enquanto avanço para a próxima tarefa na sessão principal

O isolamento é o que torna os subagentes fundamentalmente diferentes de simplesmente pedir ao Claude para "também verificar questões de segurança" no seu prompt principal. Essa abordagem consome contexto. Divide a atenção do Claude. E produz análises de segurança superficiais porque o modelo está tentando implementar e revisar ao mesmo tempo. Um subagente dedicado foca inteiramente na sua preocupação atribuída, com um prompt de sistema otimizado para aquela tarefa específica.

Uma coisa que aprendi na prática: subagentes funcionam melhor para tarefas claramente separáveis do fluxo principal. Se a subtarefa exige muita interação com a sessão principal — "espere, verifique este arquivo antes de eu continuar" — é melhor lidar com ela na sessão principal. Subagentes brilham quando você pode simplesmente disparar e esquecer.

Etapa 8: Skills — Codificando o Conhecimento da Sua Equipe

Comandos de barra lidam com gatilhos de ação única. Skills lidam com fluxos de trabalho de múltiplas etapas.

A distinção é importante. Um comando de barra diz “faça esta coisa”. Uma skill diz “aqui está um procedimento completo para resolver esta categoria de problema, incluindo árvores de decisão, casos extremos e critérios de qualidade”. Escrevi extensivamente sobre essa arquitetura no meu guia de skills para agentes, mas, em resumo: skills são como você codifica o conhecimento institucional em playbooks reutilizáveis e executáveis por IA.

Maddy compara isso à diferença entre dar um atalho para alguém e dar treinamento. Ambos são úteis. O treinamento é o que gera efeito composto.

Uma skill é um arquivo Markdown (armazenado em .claude/skills/) que contém um fluxo de trabalho de múltiplas etapas. Veja um exemplo resumido de uma skill de revisão de código:

# Revisão de Código Abrangente
---

## Etapa 1: Avaliação da Arquitetura
- Verifique se as alterações estão alinhadas com os padrões existentes na base de código
- Confirme se os novos arquivos estão nos diretórios corretos conforme a convenção do projeto
- Sinalize quaisquer decisões arquiteturais que precisem ser documentadas

## Etapa 2: Revisão da Lógica
- Siga o caminho feliz pelo novo código
- Identifique casos extremos que não estão sendo tratados
- Verifique a completude do tratamento de erros

## Etapa 3: Verificação de Performance
- Identifique padrões de consultas N+1
- Verifique se há re-renderizações desnecessárias em componentes React
- Confirme se existem índices no banco de dados para os novos padrões de consulta

## Etapa 4: Varredura de Segurança
- Verifique a validação de entrada em todos os dados fornecidos pelo usuário
- Confirme as verificações de autenticação/autorização
- Revise possíveis vulnerabilidades de injeção

## Etapa 5: Avaliação da Cobertura de Testes
- Verifique se os caminhos críticos possuem cobertura de testes
- Confira se os casos extremos identificados na Etapa 2 têm testes correspondentes
- Sinalize quaisquer caminhos de tratamento de erro que não estejam testados

## Formato de Saída
Para cada achado:
- **Arquivo:** [caminho]
- **Linha:** [número]
- **Gravidade:** Crítico | Alto | Médio | Baixo | Informativo
- **Achado:** [descrição]
- **Recomendação:** [correção específica]

Quando você invoca essa skill, o Claude não faz apenas uma varredura rápida. Ele executa um processo de revisão estruturado em cinco etapas que identifica categorias de problemas que uma revisão superficial deixaria passar. E como a skill está em Markdown com controle de versão, toda a sua equipe se beneficia de cada aprimoramento.

O efeito composto que Maddy descreve — e que vivenciei pessoalmente — é que as skills acumulam o conhecimento conquistado pela sua equipe ao longo do tempo. Cada caso extremo que você identifica é adicionado à skill relevante. Cada erro se transforma em uma verificação. Seis meses após adotar essa prática, suas skills contêm a expertise destilada de todos os projetos em que você trabalhou. Novos membros da equipe herdam esse conhecimento instantaneamente.

Atualmente, mantenho cerca de vinte skills nos meus projetos. As que entregam mais valor: revisão de código (processo em cinco etapas), scaffolding de endpoints de API (gera rota, controller, validação, testes e documentação em uma única passagem), planejamento de migração de banco de dados (analisa o schema existente, sugere etapas de migração, sinaliza riscos de integridade de dados) e checklist de deploy (verifica variáveis de ambiente, segredos, DNS, SSL e monitoramento antes de qualquer push para produção).

Passo 9: Servidores MCP — Estendendo o Claude Além do Seu Código

A peça final do fluxo de trabalho da Maddy conecta o Claude ao restante do seu ambiente de desenvolvimento.

Servidores MCP (Model Context Protocol) são programas independentes que expõem ferramentas e recursos ao Claude Code por meio de um protocolo padronizado. O conceito é simples: o Claude já lê arquivos e executa comandos. Os servidores MCP permitem que ele também interaja com GitHub, Slack, bancos de dados, APIs e qualquer outro serviço externo do qual seu fluxo de trabalho dependa.

A configuração prática é mais simples do que parece. Você adiciona servidores MCP com configuração de escopo — escopo user para servidores disponíveis em todos os projetos, escopo local para ferramentas por projeto, e escopo project (gravado em .mcp.json) para ferramentas compartilhadas com sua equipe via Git.

Uma coisa que me surpreendeu quando conectei servidores MCP pela primeira vez: o Claude Code não carrega todas as ferramentas de todos os servidores no contexto de uma só vez. Ele utiliza busca de ferramentas para descobrir recursos sob demanda, puxando os schemas apenas quando necessário. Isso reduz o uso de contexto em cerca de 95% em comparação com clientes que despejam todas as definições de ferramentas de uma vez. Uma decisão de design inteligente que torna viável rodar múltiplos servidores MCP sem esgotar o contexto.

Os servidores MCP que uso diariamente:

• GitHub MCP: O Claude pode ler comentários de PR, criar issues, revisar diffs e postar feedbacks de revisão — tudo sem sair da sessão do terminal
• Filesystem MCP: Operações de arquivos estendidas além do que o Claude Code suporta nativamente
• Slack MCP: Notificações quando tarefas são concluídas, alertas de erro e atualizações de status postadas diretamente nos canais do projeto

O ponto da Maddy sobre servidores MCP ressoou comigo: eles transformam o Claude de um assistente de código em algo mais próximo de um engenheiro semi-autônomo que opera em todo o seu ambiente de desenvolvimento. Quando o Claude pode ler uma issue do GitHub, planejar a implementação, escrever o código, rodar os testes, criar o PR e postar um resumo no Slack — o gargalo humano deixa de ser escrever código e passa a ser tomar decisões.

Esse é o gargalo certo para se ter.

O Efeito Composto: Por Que Todos os Nove Passos Importam Juntos

Quero ser direto sobre algo: implementar qualquer etapa isolada deste fluxo de trabalho já vai melhorar sua experiência com o Claude Code. O modo de planejamento, sozinho, já vale a leitura. Os hooks de validação, sozinhos, vão reduzir seu tempo de depuração. Os comandos de barra, sozinhos, vão tornar seu fluxo diário mais consistente.

Mas a verdadeira transformação acontece quando os nove passos funcionam como um sistema.

Veja como eles se potencializam. O CLAUDE.md oferece compreensão do projeto ao Claude. O modo de planejamento traz consciência arquitetural. O /clear previne a degradação do contexto. Os comandos de barra garantem qualidade consistente de entrada. Os hooks de validação criam ciclos automáticos de feedback. Sessões paralelas multiplicam a produtividade. Subagentes oferecem análises especializadas e isoladas. Skills codificam o conhecimento institucional. Servidores MCP expandem o alcance além do repositório de código.

Se você remover qualquer uma dessas peças, o sistema ainda funciona. Mas funciona como um carro com o pneu furado — tecnicamente operacional, mas com desempenho visivelmente comprometido. As peças foram projetadas para compensar as limitações umas das outras. O modo de planejamento detecta erros arquiteturais que o CLAUDE.md sozinho não consegue evitar. Os hooks de validação capturam erros de implementação que o modo de planejamento não prevê. A limpeza de contexto evita o tipo de degradação progressiva de qualidade que torna todo o resto menos confiável com o tempo.

O fluxo de trabalho em que me estabeleci após um mês de prática:

1. Comece cada projeto com um CLAUDE.md enxuto (menos de 150 linhas)
2. Inicie cada tarefa no modo de planejamento — revise e aprove antes da execução
3. Deixe os hooks de validação capturarem erros automaticamente durante a execução
4. Limpe o contexto após cada tarefa concluída
5. Use comandos de barra para todo fluxo repetitivo
6. Rode 2-3 sessões paralelas em features independentes via worktrees
7. Gere subagentes para revisão de segurança e geração de testes
8. Mantenha skills para fluxos multi-etapas compartilhados pela equipe
9. Conecte servidores MCP para GitHub, Slack e integrações específicas do projeto

A curva de aprendizado é real. A primeira semana de prática deliberada foi mais lenta do que meu fluxo antigo. Eu estava constantemente alternando o modo de planejamento, escrevendo comandos de barra, configurando hooks — um overhead que não produzia resultados visíveis imediatos. Na segunda semana, esse overhead já havia se tornado automático. Na terceira, eu entregava mais em uma manhã do que costumava entregar em um dia inteiro.

O Que Eu Errei — E O Que Faria Diferente

Vou ser honesto sobre os erros que cometi ao implementar esse fluxo de trabalho, porque eles vão te poupar tempo se você estiver começando do zero.

Erro 1: Implementar tudo de uma vez. Li a metodologia completa da Maddy e tentei adotar todas as nove práticas já no primeiro dia. A sobrecarga cognitiva foi brutal. Fiquei tão focado no processo que mal escrevi código. Abordagem melhor: comece com CLAUDE.md + modo de planejamento + /clear. Adicione hooks de validação na segunda semana. Inclua comandos de barra e sessões paralelas na terceira semana. Deixe subagentes, skills e MCP para a quarta semana.

Erro 2: Complicar demais os comandos de barra. Meu primeiro lote de comandos de barra eram praticamente redações. Trezentas palavras de instrução cada. Funcionavam, mas consumiam um contexto enorme. Desde então, reduzi-os para serem tão concisos quanto meu CLAUDE.md — cada palavra precisa justificar sua presença. Um comando objetivo de 50 palavras supera um prolixo de 300 quase sempre.

Erro 3: Rodar sessões paralelas demais. Fiquei empolgado e tentei rodar cinco sessões simultâneas. O esforço de revisão destruiu todo o ganho de produtividade. Três é meu ponto ideal. Duas, se as tarefas forem complexas. Cinco foi puro caos.

Erro 4: Esquecer de limpar o contexto. Velhos hábitos custam a morrer. Eu entrava no fluxo, completava três tarefas sem limpar, e me perguntava por que as sugestões do Claude ficavam cada vez piores. Acabei colando um post-it físico no monitor: "Você já deu /clear?" Pouco elegante. Eficaz.

Erro 5: Usar subagentes para tarefas que precisavam do contexto da sessão principal. Tentei criar um subagente para refatorar uma função que dependia fortemente da conversa que eu vinha tendo na sessão principal sobre decisões de arquitetura. O subagente não tinha esse contexto e produziu uma refatoração que contradizia tudo o que havíamos discutido. Subagentes funcionam para tarefas independentes. Para trabalhos que exigem muito contexto, mantenha na sessão principal.

Nenhum desses erros foi catastrófico. Mas cada um me custou tempo que eu não precisava perder. O fluxo de trabalho é realmente poderoso — e é mais poderoso quando você respeita suas limitações, em vez de tentar burlar o sistema.

A Mudança na Forma de Pensar Sobre Seu Papel

Existe uma ideia maior por trás de todos os nove passos, que levou um tempo para eu conseguir articular.

Quando você implementa esse fluxo de trabalho por completo, seu papel muda. Você passa menos tempo escrevendo código e mais tempo tomando decisões. Você planeja a arquitetura em vez de implementá-la. Você revisa o resultado em vez de gerá-lo. Você projeta sistemas em vez de digitá-los.

Alguns desenvolvedores acham isso desconfortável. Para muitos de nós, codificar faz parte da identidade. A sensação de construir algo linha por linha — aquele estado de fluxo em que seus dedos e seu cérebro estão perfeitamente sincronizados — é realmente gratificante. Abrir mão disso, mesmo que parcialmente, parece uma perda.

Eu me senti assim nas duas primeiras semanas. Depois percebi que as decisões que eu estava tomando — as escolhas arquiteturais, as definições de prioridade, os julgamentos de qualidade — eram mais difíceis e mais valiosas do que o código que eu costumava escrever. O código era execução. As decisões eram estratégia. E é a estratégia que realmente determina se um software terá sucesso.

O framework da Maddy não substitui a habilidade de engenharia. Ele a redireciona. Seu entendimento de algoritmos, estruturas de dados, padrões de design e arquitetura de sistemas se torna ainda mais importante, não menos — porque é você quem está guiando uma IA capaz de executar em velocidade sobre-humana, mas que não consegue tomar decisões estratégicas sem você.

Os engenheiros que vejo tendo dificuldades com esse fluxo de trabalho são aqueles que não conseguem largar o teclado. Já os que prosperam são os que sempre desejaram ter mais tempo para pensar na arquitetura e menos tempo digitando código repetitivo. Esse fluxo de trabalho oferece exatamente essa troca.

Para Onde Estamos Indo

Não acho que já chegamos ao fim. O abismo entre o que o Claude Code consegue fazer hoje e o que será capaz de fazer em doze meses provavelmente é maior do que a maioria dos desenvolvedores imagina.

O padrão que observo: cada uma dessas nove práticas existe por causa de uma limitação atual. O modo de planejamento existe porque o Claude às vezes escreve código correto no lugar errado. Hooks de validação existem porque o Claude nem sempre consegue verificar seu próprio trabalho internamente. Limpeza de contexto existe porque as janelas de contexto têm capacidade finita. Subagentes existem porque um único contexto não consegue acomodar todas as preocupações ao mesmo tempo.

À medida que as janelas de contexto se expandem, que os modelos ficam melhores em auto-verificação, que o uso de ferramentas se torna mais sofisticado — algumas dessas práticas vão se tornar menos críticas. O modo de planejamento pode se tornar desnecessário quando o raciocínio arquitetural do modelo for confiável o suficiente para dispensar essa etapa explícita. Hooks de validação podem se tornar redundantes quando a verificação interna do modelo igualar a precisão dos testes externos.

Mas a meta-prática — construir estrutura em torno das capacidades da IA — só vai se tornar mais importante. Os modelos vão evoluir. Os engenheiros que souberem arquitetar fluxos de trabalho em torno desses modelos vão extrair o máximo valor. Essa é a verdadeira habilidade que essa metodologia ensina: não como usar o Claude Code especificamente, mas como pensar o desenvolvimento aumentado por IA como uma disciplina.

Os nove passos da Maddy são o melhor ponto de partida que encontrei para construir essa disciplina. Comece com o CLAUDE.md e o modo de planejamento. Adicione uma prática por semana. Em um mês, você terá um fluxo de trabalho que fará sua abordagem atual parecer dirigir com o freio de mão puxado.

A pergunta que vale a pena considerar esta noite não é se esse fluxo de trabalho vale a implementação — as evidências são esmagadoras de que sim. A pergunta é: quais dos seus hábitos atuais são tão confortáveis que estão impedindo você de fazer essa mudança.

Perguntas Frequentes

Como configuro o modo de planejamento no Claude Code?

Ative o modo de planejamento com Shift+Tab no CLI do Claude Code antes de descrever sua tarefa. O Claude analisará sua base de código e produzirá um plano de implementação para revisão antes de escrever qualquer código. Use este modo para qualquer alteração que envolva mais de um arquivo.

Qual a diferença entre comandos de barra e skills no Claude Code?

Comandos de barra são prompts de ação única armazenados como arquivos Markdown em .claude/commands/. Skills são fluxos de trabalho multi-etapas armazenados em .claude/skills/, codificando procedimentos complexos com árvores de decisão e critérios de qualidade. Desde 2026, ambos utilizam a mesma interface de comandos de barra.

Quantas sessões paralelas do Claude Code devo rodar?

Comece com duas sessões paralelas usando worktrees do Git para isolamento. Três sessões é o ponto ideal para a maioria dos desenvolvedores. Rodar mais de três geralmente gera um excesso de revisões que anula os ganhos de produtividade da paralelização.

Hooks de validação do Claude Code atrasam o desenvolvimento?

Hooks adicionam um tempo de execução igual à duração do seu build e testes após cada edição. Para projetos com suítes de testes abaixo de 30 segundos, o overhead é insignificante comparado ao tempo de depuração que eles evitam. Para suítes mais longas, considere rodar apenas um subconjunto relevante de testes como hooks e a suíte completa antes dos commits.

Quais servidores MCP devo instalar para o Claude Code?

A maioria dos desenvolvedores precisa de dois a três servidores MCP: GitHub (para gerenciamento de PRs e issues), uma extensão de sistema de arquivos e um servidor específico do seu domínio. Adicione-os com configuração de escopo — user para disponibilidade global, project para ferramentas compartilhadas pela equipe via .mcp.json no seu repositório.

Vamos Trabalhar Juntos

Quer construir sistemas de IA, automatizar fluxos de trabalho ou escalar sua infraestrutura tecnológica? Eu posso ajudar.

• Fiverr (projetos personalizados & integrações): fiverr.com/s/EgxYmWD
• Portfólio: mejba.me
• Ramlit Limited (soluções empresariais): ramlit.com
• ColorPark (design & branding): colorpark.io
• xCyberSecurity (serviços de segurança): xcybersecurity.io