A melhor forma de trabalhar com Claude: CLAUDE.md, Skills, Hooks, Harness e Gatilhos

Em uma das primeiras vezes que vi alguém usando Claude em um projeto real, a cena foi bem familiar: a pessoa copiava um trecho de código, colava no chat, explicava rapidamente o problema e esperava uma solução. Às vezes vinha uma resposta boa. Às vezes vinha uma sugestão que parecia correta, mas ignorava o padrão do projeto. Em outros momentos, o Claude resolvia uma parte e criava outro problema do lado.

O diagnóstico inicial era sempre o mesmo: “precisamos melhorar o prompt”.

Mas, olhando com mais atenção, o problema não era exatamente o prompt. O problema era que o Claude estava trabalhando sem contexto operacional.

Ele não sabia como o projeto era organizado. Não sabia quais comandos eram seguros. Não conhecia as decisões arquiteturais anteriores. Não sabia quais arquivos não deveria alterar. Não tinha clareza sobre o padrão de testes, sobre a estrutura de pastas, sobre as regras de revisão ou sobre o que o time considerava uma entrega aceitável.

Era como contratar um desenvolvedor bom, colocá-lo diante de um repositório grande, não explicar nada e esperar que ele descubra sozinho o jeito certo de trabalhar.

Até pode funcionar. Mas vai oscilar.

Foi aí que ficou mais claro para mim que trabalhar bem com Claude não é apenas saber conversar com IA. É preparar o ambiente para que a IA consiga trabalhar dentro de um processo.

Esse é o ponto que muita gente ainda subestima.

O ganho real não vem de pedir:

Claude, resolva isso para mim.

O ganho real vem de criar um ambiente em que o Claude entende onde está, quais regras precisa seguir, quais ferramentas pode usar, quando deve pedir aprovação e como validar o que entregou.

É aqui que entram CLAUDE.md, Skills, Hooks, Subagents, MCP, Harness e gatilhos.

Antes de falar de ferramenta, o ponto principal é contexto

Projetos profissionais acumulam decisões.

Algumas estão documentadas. Muitas estão espalhadas em conversas, pull requests antigas, comentários de código, scripts esquecidos e na cabeça das pessoas mais experientes do time.

Quando uma IA entra nesse ambiente sem orientação, ela tenta inferir o padrão a partir dos arquivos que encontra. Em projetos pequenos, isso pode ser suficiente. Em projetos maiores, legados ou com múltiplos times, essa inferência começa a falhar.

Ela pode sugerir uma arquitetura que o time já abandonou. Pode criar uma migration onde o padrão interno exige outro fluxo. Pode alterar um arquivo sensível sem perceber. Pode rodar um comando perigoso porque ninguém explicou que aquele comando só deve ser usado em ambiente local descartável.

Não é mágica. É falta de trilho.

Por isso, antes de pensar em automação avançada, eu começaria por uma pergunta simples:

Se uma pessoa nova entrasse hoje no projeto, o que ela precisaria saber para não fazer besteira?

A resposta para essa pergunta normalmente vira a base do CLAUDE.md.

CLAUDE.md: o arquivo que evita explicar tudo de novo

O CLAUDE.md é, na prática, o manual de bordo do Claude dentro do projeto.

Ele não precisa ser bonito. Precisa ser útil.

O objetivo não é criar documentação institucional. O objetivo é orientar o comportamento do agente.

Um bom CLAUDE.md responde perguntas como:

1. Qual é o objetivo do projeto?
2. Qual stack está sendo usada?
3. Como o repositório está organizado?
4. Quais comandos rodam o projeto?
5. Quais comandos executam testes?
6. Quais padrões arquiteturais devem ser respeitados?
7. Quais arquivos exigem cuidado?
8. O que o Claude pode alterar sem pedir permissão?
9. O que exige confirmação humana?
10. Como o Claude deve apresentar um plano antes de mexer em algo grande?

Um exemplo simples:

CLAUDE.md

Visão geral

Este projeto é uma API responsável por autenticação, usuários e permissões.

Stack

• Node.js
• TypeScript
• PostgreSQL
• Docker

Estrutura

• src/controllers: entrada das requisições
• src/services: regras de negócio
• src/repositories: acesso a dados
• tests: testes automatizados

Comandos úteis

• npm install
• npm run dev
• npm run test
• npm run lint
• npm run build

Regras para Claude

• Não alterar migrations antigas.
• Não remover testes existentes.
• Não alterar arquivos de produção sem pedir confirmação.
• Não colocar regra de negócio dentro de controllers.
• Antes de grandes refatorações, apresentar um plano.
• Para correções de bug, priorizar a menor alteração segura.
• Ao final, explicar o que foi alterado, quais testes rodar e quais riscos existem.

Esse tipo de arquivo evita uma quantidade enorme de conversa repetida.

Também reduz uma falha comum no uso de IA: cada pessoa do time pedir a mesma coisa de um jeito diferente e receber respostas em padrões diferentes.

O CLAUDE.md transforma parte do conhecimento operacional do time em instrução reaproveitável.

Ele não substitui README, documentação técnica ou arquitetura formal. O papel dele é outro: orientar o agente durante o trabalho.

Eu gosto de pensar nele como uma conversa de onboarding condensada. É aquilo que você diria para uma pessoa nova antes de deixá-la mexer no repositório.

Skills: quando o time para de depender de “quem sabe pedir melhor”

Depois que o projeto tem um bom contexto base, o próximo passo natural é padronizar tarefas recorrentes.

É aqui que entram as Skills.

Uma Skill é uma capacidade reutilizável. Em vez de explicar toda vez como o Claude deve revisar uma PR, analisar um log ou criar testes, você transforma esse padrão em uma instrução reutilizável.

Na prática, uma Skill responde a cinco pontos:

1. Quando ela deve ser usada.
2. Qual é o objetivo da tarefa.
3. Qual processo deve ser seguido.
4. Quais critérios devem ser avaliados.
5. Qual formato de saída é esperado.

Exemplo de Skill para revisão de código:

Skill: Revisão de Código Backend

Quando usar

Use esta Skill quando houver alteração em código backend.

Objetivo

Identificar riscos de arquitetura, segurança, performance, testes e legibilidade.

Processo

1. Entender o objetivo da alteração.
2. Avaliar os arquivos modificados.
3. Verificar se a mudança respeita a arquitetura do projeto.
4. Procurar ausência de testes.
5. Identificar riscos de segurança.
6. Avaliar impacto em performance.
7. Sugerir correções objetivas.

Formato da resposta

• Resumo da alteração
• Riscos críticos
• Pontos de atenção
• Testes ausentes ou frágeis
• Sugestões de melhoria
• Recomendação final para o reviewer humano

A diferença entre prompt e Skill é que a Skill vira um ativo do time.

Não fica dependente de uma pessoa que sabe escrever uma solicitação perfeita. O padrão passa a estar disponível para todo mundo.

Isso muda bastante o uso em equipe.

Sem Skills, um desenvolvedor pede “revise essa PR” e recebe uma análise superficial. Outro pede com mais detalhes e recebe uma análise muito melhor. Com Skills, o time diminui essa variação e começa a criar uma base comum de qualidade.

Eu começaria com poucas Skills. Três já resolvem muita coisa:

1. Revisão de código.
2. Criação de testes.
3. Análise de incidentes.

Depois disso, dá para criar Skills mais específicas, como documentação técnica, refatoração segura, análise de performance, revisão de segurança, escrita de changelog, análise de logs e revisão de banco de dados.

O erro aqui é querer criar uma biblioteca enorme logo no começo. Normalmente isso vira um cemitério de arquivos que ninguém usa.

Skill boa nasce de repetição. Se o time pede a mesma coisa toda semana, provavelmente vale transformar em Skill.

Hooks: quando a IA precisa encontrar limites

Em algum momento, só orientar o Claude não basta.

Você precisa colocar validações no caminho.

Hooks servem para isso: executar ações automáticas em pontos específicos do ciclo de trabalho.

Enquanto o Claude raciocina, analisa e propõe alterações, os Hooks ajudam a impor regras objetivas.

Alguns exemplos:

1. Rodar lint depois de alterar arquivos.
2. Executar testes depois de uma mudança.
3. Bloquear comandos perigosos.
4. Impedir alteração em arquivos sensíveis.
5. Registrar ações.
6. Validar formatação.
7. Chamar scripts internos.
8. Enviar notificações.
9. Interromper fluxos arriscados.

IA não deve operar apenas com base em confiança. Ela precisa de limites.

Um bom fluxo não é:

Claude, faça tudo sozinho.

Um bom fluxo é:

Claude, trabalhe dentro dessas regras, valide o que foi feito e me mostre onde ainda existe risco.

Imagine que o Claude alterou três arquivos TypeScript. Um Hook pode rodar npm run lint automaticamente. Se ele tentou mexer em um arquivo de configuração de produção, outro Hook pode exigir confirmação. Se uma tarefa terminou, um Hook pode registrar um resumo em log ou disparar uma notificação para o time.

Isso tira parte da validação do campo subjetivo.

Você não precisa apenas confiar que o Claude lembrou de rodar os testes. O fluxo pode obrigar isso.

Hooks são especialmente úteis em times que querem usar IA sem abrir mão de governança. Eles colocam trilhos no processo.

E trilho, nesse contexto, não é burocracia. É segurança operacional.

Gatilhos: quando o Claude deve entrar no fluxo

Muita gente usa Claude apenas quando lembra de usar.

Esse é um problema.

Se a IA só entra no processo quando alguém decide manualmente, ela vira uma ferramenta individual. Ajuda, mas não muda o fluxo do time.

Gatilhos resolvem parte disso.

Um gatilho define quando a IA deve ser acionada e o que ela deve fazer.

Pode ser algo manual:

1. Revise essa PR.
2. Crie testes para esse módulo.
3. Analise esse erro de produção.
4. Explique esse código legado.
5. Gere documentação dessa feature.

Ou pode ser algo automático:

1. Quando uma PR for aberta.
2. Quando o pipeline falhar.
3. Quando um alerta crítico for disparado.
4. Quando a cobertura de testes cair.
5. Quando um arquivo sensível for alterado.
6. Quando uma issue ficar parada muitos dias.
7. Quando um erro aparecer repetidamente nos logs.

Um gatilho útil normalmente combina três elementos:

1. Evento.
2. Contexto.
3. Ação esperada.

Exemplo:

Quando uma PR for aberta no backend,
analise os arquivos modificados,
identifique riscos de segurança,
verifique ausência de testes
e gere um resumo para o revisor humano.

Outro exemplo:

Quando o pipeline falhar,
leia o log,
identifique o estágio da falha,
classifique a causa como código, ambiente, dependência ou teste instável
e sugira a correção mínima.

Esse tipo de configuração evita que a IA dependa da memória das pessoas.

Em vez de alguém pensar “será que vale pedir para o Claude olhar isso?”, o próprio fluxo já prevê quando a análise deve acontecer.

O cuidado aqui é não transformar tudo em gatilho.

Se qualquer evento dispara um agente, o time logo começa a ignorar as respostas. O Claude vira mais uma fonte de ruído.

Gatilho bom é aquele que entra em momentos de decisão, risco ou repetição.

Subagents: separar papéis antes que tudo vire uma conversa gigante

Conforme o uso cresce, começa a surgir outro problema: tentar fazer tudo com um único agente.

O mesmo Claude revisa arquitetura, cria testes, analisa segurança, escreve documentação, olha banco de dados e ainda tenta explicar para o gestor o que aconteceu.

Dá para fazer. Mas nem sempre é o melhor caminho.

Subagents ajudam a separar responsabilidades.

Você pode ter agentes especializados para funções específicas:

1. Agente de testes.
2. Agente de arquitetura.
3. Agente de segurança.
4. Agente de documentação.
5. Agente de banco de dados.
6. Agente de troubleshooting.
7. Agente de revisão de PR.

Cada agente pode ter instruções próprias, ferramentas permitidas, escopo limitado e formato de resposta.

Exemplo:

Agente de Segurança:

1. Verificar autenticação e autorização.
2. Procurar exposição de secrets.
3. Avaliar riscos de injection.
4. Revisar permissões.
5. Não alterar código sem aprovação.

Outro exemplo:

Agente de Testes:

1. Identificar cenários não cobertos.
2. Criar testes unitários.
3. Executar a suíte relevante.
4. Reportar falhas e riscos.

A ideia não é criar um organograma de agentes só porque parece sofisticado.

Subagent faz sentido quando existe uma responsabilidade recorrente, especializada e com critérios próprios.

Se o time ainda nem tem CLAUDE.md, criar cinco agentes provavelmente só vai adicionar confusão.

Primeiro organize o contexto. Depois especialize.

MCP: quando Claude precisa conversar com o ecossistema

MCP, ou Model Context Protocol, permite conectar Claude a ferramentas e fontes externas.

Essa é uma das partes mais poderosas do uso profissional.

Sem integrações, Claude depende do que você cola no chat. Com integrações bem configuradas, ele pode consultar sistemas, buscar informações relevantes e trabalhar mais perto do ambiente real.

Exemplos de integrações:

1. GitHub.
2. GitLab.
3. Banco de dados.
4. Slack.
5. Jira.
6. Notion.
7. Documentação interna.
8. Sistemas de observabilidade.
9. APIs corporativas.

Isso abre possibilidades interessantes.

O Claude pode analisar uma issue, consultar a documentação relacionada, olhar o histórico de PRs, avaliar logs e sugerir uma hipótese de causa. Pode ajudar no troubleshooting, na preparação de uma entrega, na revisão de código ou na geração de documentação.

Mas MCP não deve ser tratado como “só mais uma extensão”.

Ele deve ser tratado como integração de produção.

A pergunta não é apenas:

Consigo conectar?

A pergunta correta é:

Devo conectar? Com qual permissão? Em qual escopo? Com qual auditoria? Com quais limites?

Claude com acesso irrestrito é como dar a chave do carro para alguém que sabe dirigir, mas ainda não conhece a estrada, o trânsito, os pedágios, as regras locais e os pontos perigosos.

A capacidade existe. O risco também.

Por isso, MCP precisa de permissão mínima, escopo claro e revisão cuidadosa das ferramentas conectadas.

Harness: a camada que organiza tudo

Quando falo em Harness, não estou falando necessariamente de uma ferramenta única.

Estou falando da camada de orquestração e governança que organiza o uso do Claude dentro de um fluxo real.

É o conjunto de práticas, configurações e integrações que define:

1. Onde o Claude roda.
2. Quais repositórios pode acessar.
3. Quais comandos pode executar.
4. Quais Skills estão disponíveis.
5. Quais Hooks serão aplicados.
6. Quais gatilhos acionam a IA.
7. Quais aprovações humanas são necessárias.
8. Onde os resultados serão registrados.
9. Como auditar o que foi feito.

Sem essa camada, cada pessoa usa IA de um jeito.

Com essa camada, o time começa a ter um fluxo reproduzível.

Um fluxo maduro poderia ser assim:

1. O desenvolvedor abre uma issue.
2. Claude lê o contexto do projeto via CLAUDE.md.
3. Uma Skill de análise técnica é acionada.
4. Claude propõe um plano.
5. Um humano aprova.
6. Claude altera os arquivos.
7. Hooks executam lint e testes.
8. Um subagent de testes revisa a cobertura.
9. Claude gera resumo técnico.
10. A PR é criada ou atualizada.
11. O reviewer humano toma a decisão final.

Esse fluxo ainda tem humano no centro.

A diferença é que o humano deixa de fazer todo o trabalho operacional repetitivo e passa a atuar mais em decisão, validação e direcionamento.

Esse é o ponto em que Claude deixa de ser apenas um assistente e começa a virar parte da infraestrutura de engenharia.

O que eu evitaria no começo

Já vi times querendo começar pelo final.

Configuram MCP, criam vários Subagents, adicionam Hooks, inventam gatilhos para tudo e, em poucos dias, ninguém sabe exatamente o que está acontecendo.

O resultado costuma ser previsível: agentes conflitando, automações bloqueando tarefas simples, respostas demais, pouca confiança e um sentimento geral de que “IA dá trabalho”.

Na maior parte das vezes, o problema não é a IA.

É a falta de sequência.

Eu evitaria começar por:

1. MCP antes de ter clareza de permissões.
2. Subagents antes de ter tarefas recorrentes bem definidas.
3. Hooks demais logo no início.
4. Gatilhos para eventos pouco relevantes.
5. Skills genéricas que ninguém usa.
6. CLAUDE.md enorme, bonito e inútil.

O melhor começo é mais simples.

1. Crie um CLAUDE.md útil.
2. Crie uma Skill de revisão de código.
3. Crie uma Skill de testes.
4. Crie uma Skill de análise de incidentes.
5. Adicione Hooks básicos de lint e testes.
6. Defina dois ou três gatilhos realmente úteis.
7. Só então pense em MCP, Subagents e uma camada de Harness mais robusta.

O modelo mental que eu usaria

Se eu tivesse que resumir a estrutura, seria assim:

1. CLAUDE.md é o contexto fixo do projeto.
2. Skills são capacidades reutilizáveis.
3. Hooks são validações automáticas.
4. Gatilhos definem quando acionar a IA.
5. Subagents separam responsabilidades.
6. MCP conecta Claude ao ecossistema.
7. Harness organiza tudo com governança.

Cada camada resolve um problema diferente.

1. O CLAUDE.md reduz repetição.
2. As Skills reduzem variação.
3. Os Hooks reduzem risco.
4. Os gatilhos reduzem esquecimento.
5. Os Subagents reduzem sobrecarga de contexto.
6. O MCP reduz isolamento.
7. O Harness reduz bagunça.

No fim, trabalhar bem com Claude não é apenas escrever prompts melhores.

É desenhar um ambiente em que o Claude consiga operar com contexto, limites, validação e propósito.

Essa é a diferença entre usar IA como ferramenta improvisada e usar IA como parte real do processo de engenharia.

O primeiro caminho gera respostas boas de vez em quando.

O segundo cria consistência.