10 skills que transformaram meus agentes de código de autocomplete para colaboradores reais

Existe um momento específico em que a relação com agentes de IA muda. Para mim, foi quando parei de digitar prompts e comecei a delegar tarefas completas. Não "escreva uma função que faz X", mas "refatore o pipeline editorial inteiro, mantenha os testes passando, documente o que mudou". A diferença parece sutil. Não é. É a diferença entre usar uma calculadora e ter um engenheiro júnior que trabalha 24 horas por dia, não reclama de code review, e melhora a cada iteração.

Na Sinal, operamos 6 agentes de IA que monitoram 150+ fontes semanais, mapeiam 4.000+ empresas em 17 países da LATAM e publicam uma newsletter semanal com 52 edições no ar. O frontend roda em Next.js, o backend em FastAPI com PostgreSQL, e o pipeline editorial passa por 6 camadas de revisão antes de qualquer conteúdo ir ao ar. Nada disso seria viável como operação de uma pessoa sem agentes que funcionam como colaboradores reais. Mas para chegar aqui, precisei aprender 10 skills que transformaram completamente a forma como construo software com IA. Não são truques. São mudanças estruturais na forma de trabalhar.

1. CLAUDE.md como sistema operacional do projeto

O problema

Todo projeto com agentes de IA começa igual: você abre o terminal, escreve um prompt, recebe um output razoável, ajusta manualmente, repete. Depois de 50 interações, percebe que está corrigindo os mesmos erros. O agente não lembra que você prefere snake_case no backend. Não sabe que o projeto usa Pydantic V2. Não entende que a arquitetura segue um padrão específico de separação de concerns. Cada sessão é um recomeço.

Como uso na prática

O CLAUDE.md da Sinal tem 3 seções que mudaram tudo. A primeira é Engineering Preferences: define que usamos Python 3.12, FastAPI com async, PostgreSQL com SQLAlchemy 2.0, tipagem estrita em todo lugar, e que imports absolutos são obrigatórios. A segunda é Plan Mode: antes de qualquer mudança com mais de 3 arquivos, o agente precisa gerar um plano, listar os arquivos afetados, e esperar aprovação. A terceira é Quick Commands: atalhos como /test-all, /lint-fix, /deploy-staging que encapsulam sequências complexas de comandos.

Mas o mais importante não está nas seções óbvias. Está nas regras editoriais. O CLAUDE.md da Sinal inclui coisas como: "NUNCA use em dash em textos em português. Use vírgula, dois pontos ou ponto." e "Toda API response deve incluir timestamp e request_id". São decisões que tomei uma vez e nunca mais precisei repetir.

O resultado

O tempo de contexto inicial caiu de 10-15 minutos de explicação por sessão para zero. Abro o Claude Code, ele lê o CLAUDE.md, e já sabe como trabalhar. Estimativa conservadora: economizo 2 horas por dia só em contexto que não preciso repetir. Em um mês, são 40+ horas. É uma pessoa a mais no time.

Como instalar e configurar

O CLAUDE.md é nativo do Claude Code. Não precisa instalar nada. Basta criar o arquivo na raiz do seu projeto:

touch CLAUDE.md

A documentação oficial está em: https://docs.anthropic.com/en/docs/claude-code/memory#claudemd

Aqui está um CLAUDE.md mínimo para começar. Copie, adapte ao seu stack, e itere a partir daí:

# CLAUDE.md

## Projeto
- Nome: [Seu Projeto]
- Stack: [ex: Next.js 14, FastAPI, PostgreSQL]
- Linguagem principal: [ex: Python 3.12, TypeScript 5.x]

## Engineering Preferences
- Tipagem estrita em todo lugar. Sem `Any` a menos que justificado.
- Imports absolutos. Nunca relativos.
- Funções puras sempre que possível.
- Testes obrigatórios para qualquer feature nova (TDD).

## Plan Mode
- Para mudanças que afetam mais de 3 arquivos: gere um plano primeiro.
- Liste os arquivos afetados e as mudanças propostas.
- Espere aprovação antes de implementar.

## Regras Editoriais
- NUNCA use em dash em textos em português. Use vírgula, dois pontos ou ponto.
- [Adicione suas regras específicas aqui]

## Quick Commands
- `/test-all`: roda pytest com coverage
- `/lint-fix`: roda ruff check --fix && ruff format
- `/deploy-staging`: builda e faz deploy para staging

Dica: o Claude Code também lê arquivos CLAUDE.md em subdiretórios. Use isso para regras específicas por módulo (ex: apps/api/CLAUDE.md com regras de backend, apps/web/CLAUDE.md com regras de frontend).

2. Frontend Design que não parece template

O problema

Existe um fenômeno que chamo de "convergência distributiva": quando todo mundo usa o mesmo modelo de IA para gerar frontend, tudo converge para o mesmo visual. Shadcn/ui com tema padrão, cards com border-radius de 8px, gradientes azul-roxo. Você abre 10 startups de IA e todas parecem o mesmo produto com logos diferentes. Para a Sinal, que precisa transmitir credibilidade como plataforma de inteligência para LATAM, parecer um template era inaceitável.

Como uso na prática

A skill de frontend design do Claude Code, combinada com direção de arte explícita no CLAUDE.md, mudou o jogo. Definimos um sistema de design com regras específicas: dark theme como padrão (fundo #0A0A0B), tipografia com DM Serif Display para headlines e Inter para corpo, e um sistema de cores por agente. O SINTESE usa azul-ciano, o RADAR usa verde-esmeralda, o CÓDIGO usa âmbar, o FUNDING usa roxo. Cada agente tem identidade visual própria.

Na prática, quando peço "crie a página de detalhes do agente RADAR", o Claude já sabe que o accent color é verde, que os cards usam glassmorphism sutil com backdrop-blur, e que a hierarquia tipográfica segue o padrão DM Serif Display para o título, Inter semibold para subtítulos, Inter regular para corpo. Não preciso especificar nada disso. Está no CLAUDE.md e na memória persistente.

O mais útil foi quando fizemos o overhaul completo da landing page. Em vez de pedir "faça uma landing page bonita" (que geraria exatamente o template genérico que quero evitar), pedi: "Analise os sites da Bloomberg Terminal, Stratechery e The Information. Extraia os padrões de design que transmitem autoridade editorial. Aplique ao sistema de design da Sinal." O resultado foi uma página que não parece nenhum dos três, mas carrega a mesma sensação de densidade informacional com elegância.

O resultado

Taxa de rejeição da landing page caiu. Mais importante: quando mostro a Sinal para fundadores e CTOs, a primeira reação é "isso não parece feito por uma pessoa só". Que é exatamente o ponto. Não é feito por uma pessoa só. É feito por uma pessoa com agentes que entendem design.

Como instalar e configurar

A skill de frontend design faz parte do repositório oficial de skills do Claude Code, com 277K+ instalações. Para instalar:

npx skills add anthropics/claude-code --skill frontend-design

Repositório oficial: https://github.com/anthropics/claude-code

Depois de instalar, adicione as regras de design system ao seu CLAUDE.md para que a skill trabalhe com a identidade visual do seu projeto:

## Design System
- Theme: dark (fundo #0A0A0B, superfícies #111113, borders #1A1A1F)
- Tipografia: DM Serif Display para headlines, Inter para corpo
- Border radius: 12px para cards, 8px para inputs, 6px para badges
- Glassmorphism: backdrop-blur-xl com bg-white/5 para cards elevados
- Cores por módulo:
  - Módulo A: cyan (#06B6D4)
  - Módulo B: emerald (#10B981)
  - Módulo C: amber (#F59E0B)
- Sem gradientes genéricos. Cor sólida com opacidade quando necessário.
- Referências visuais: Bloomberg Terminal, Stripe Dashboard, Linear

A skill funciona melhor quando combinada com exemplos concretos. Inclua screenshots ou links de referência no prompt quando pedir componentes novos.

3. Code Review automatizado com /simplify

O problema

Agentes de IA têm um vício: over-engineering. Peça para implementar um endpoint simples e você recebe uma classe abstrata, um factory pattern, três níveis de herança e um decorator customizado. O código funciona, mas ninguém consegue dar manutenção nele em 3 meses, incluindo o próprio agente. A complexidade acidental é o maior custo oculto de desenvolvimento com IA.

Como uso na prática

Criamos um comando /simplify que roda antes de todo commit significativo. O que ele faz: analisa o diff, identifica complexidade desnecessária, e propõe simplificações. Mas não de forma genérica. O CLAUDE.md define o que "simples" significa para a Sinal:

• Funções com mais de 30 linhas precisam ser justificadas
• Nenhuma classe abstrata sem pelo menos 2 implementações concretas existentes (não "futuras")
• Type hints em tudo, mas sem TypeVar desnecessário
• Se um if/elif/elif tem mais de 3 branches, considerar dict dispatch

Na prática, o hook funciona assim: depois que o agente implementa uma feature, eu rodo /simplify no diff. Ele analisa, propõe mudanças, e eu aprovo ou rejeito cada uma. Em um caso recente, o agente tinha implementado o parser de RSS com uma hierarquia de classes (BaseFeedParser, RSSFeedParser, AtomFeedParser, JSONFeedParser). O /simplify reduziu para uma única função com um dict de estratégias. De 4 arquivos e 180 linhas para 1 arquivo e 45 linhas. Mesma funcionalidade, mesma cobertura de testes.

O resultado

O codebase da Sinal tem uma média de complexidade ciclomática de 3.2 por função. Para referência, a média da indústria em projetos Python é 7-10. Código simples significa menos bugs, deploys mais rápidos e onboarding trivial quando (eventualmente) contratar engenheiros humanos.

Como instalar e configurar

Existem duas skills complementares para code review. A primeira é a skill oficial simplify:

npx skills add anthropics/claude-code --skill simplify

A segunda é o template de code reviewer, mais completo para reviews estruturados:

npx claude-code-templates@latest --skill development/code-reviewer

Repositório oficial: https://github.com/anthropics/claude-code

Para que o /simplify funcione com as regras do seu projeto, adicione a seção de review ao CLAUDE.md:

## Code Review Rules

### Complexidade
- Máximo 30 linhas por função. Acima disso, justifique ou quebre.
- Complexidade ciclomática máxima: 5 por função.
- Nenhuma classe abstrata sem 2+ implementações concretas EXISTENTES.
- Prefira composição sobre herança. Sempre.

### Simplificação
- if/elif com 3+ branches: considerar dict dispatch ou match/case.
- Loops com lógica complexa: extrair para função nomeada.
- Try/except genérico (Exception): proibido. Capture exceções específicas.
- TypeVar só quando genuinamente necessário para generics. Sem over-abstraction.

### Ao rodar /simplify
1. Analise o diff completo
2. Identifique complexidade acidental (código que existe "por precaução")
3. Proponha simplificações com antes/depois
4. Nunca simplifique testes. Testes podem ser verbosos.
5. Mantenha a mesma cobertura de testes após simplificação

4. Subagentes em paralelo para mudanças em escala

O problema

Refatorações grandes são o pesadelo de qualquer codebase. Você precisa mudar 20 arquivos, manter consistência entre eles, e garantir que nada quebra. Fazendo sequencialmente, um agente leva horas e perde contexto no meio do caminho. Fazendo manualmente, leva dias.

Como uso na prática

O Claude Code permite spawnar subagentes que trabalham em paralelo. Na prática, usei isso pela primeira vez no UI/UX overhaul da Sinal, quando precisei atualizar 12 componentes de interface simultaneamente: navigation, hero section, agent cards, newsletter archive, pricing, footer, e mais 6 páginas internas.

A estratégia: criei 3 agentes com escopos isolados. O primeiro cuidou de componentes de layout (navigation, footer, sidebar). O segundo cuidou de componentes de conteúdo (cards, listas, tabelas). O terceiro cuidou de páginas compostas (landing, dashboard, detalhes). Cada um tinha acesso ao mesmo sistema de design no CLAUDE.md, mas trabalhava em branches separadas.

O ponto crítico é definir interfaces claras entre os escopos. Antes de spawnar os agentes, defini os contratos: quais props cada componente compartilhado aceita, quais tokens de design são globais, quais são locais. Isso evitou conflitos de merge e garantiu consistência visual.