eduardovillao.me

Pare de pagar a IA para esquecer o que você já sabe

No momento eu estou construindo várias coisas em paralelo: um backend de formulários, uma ferramenta de alerta de reviews no WhatsApp, meus plugins de WordPress e mais algumas. Todas precisam de Stripe. Todas precisam de e-mail transacional. A maioria usa Cloudflare Workers, D1 e R2.

Por um tempo, eu deixei a IA escrever essas integrações do zero toda vez.

Isso era caro. E burro.

O que realmente estava acontecendo

Quando você pede pro Claude Code (ou qualquer IA de código) “integrar o checkout do Stripe”, ele não teleporta pra implementação pronta. Ele explora. Escreve, avalia, ajusta. Trata os erros, depois repensa o tratamento de erro. Descobre onde colocar o handler do webhook, qual metadata anexar, como estruturar a resposta.

Tudo isso custa token. E tempo.

Agora multiplique por cada projeto. Toda vez que eu começava algo novo, a IA estava reconstruindo o mesmo modelo mental pra integrações que eu já tinha resolvido.

O código geralmente saía bom. Mas eu estava pagando em token e em tempo de review por decisões que já estavam tomadas.

A solução: ai-boilerplates

Criei um repo privado chamado ai-boilerplates. A ideia é simples: todo padrão de integração que eu resolvi e validei vai pra lá, pronto pra ser usado como referência.

ai-boilerplates/
  stripe/
    checkout.ts
    webhook.ts
    customer.ts
  resend/
    transactional.ts
  cloudflare/
    d1-client.ts
    r2-upload.ts
  auth/
    jwt.ts
    session.ts

Mas a parte importante não é só o código. É o bloco de contexto no topo de cada arquivo:

/**
 * BOILERPLATE: Stripe Checkout Session
 *
 * Use: single product or dynamic price_id checkout
 * Don't use: subscriptions (see stripe/subscription.ts)
 *
 * Decisions already made:
 * - success_url always redirects to /dashboard with session_id
 * - metadata always includes userId to reconcile in webhook
 * - errors return 500 with generic message, never expose Stripe details
 */

Esse bloco é o valor real. A IA não só copia o código. Ela entende a intenção, as restrições e as decisões anteriores. Ela pula a fase de exploração inteira.

Conectando isso no Claude Code

Adicionei um arquivo de regra dedicado em ~/.claude/rules/ai-boilerplates.md:

## ai-boilerplates

Repo at ~/ai-boilerplates/ contains standard boilerplate implementations.

Before implementing any new integration, check if a boilerplate exists.
If it does, use it as the base, don't rewrite from scratch.

When using a boilerplate:
- Adapt to the project context, don't copy blindly
- Preserve the documented decisions
- If you need to deviate from a decision, comment why in the code

When writing code that could become a boilerplate, suggest adding it to the repo.

Manter isso em rules/ em vez do CLAUDE.md é intencional. O CLAUDE.md é pro contexto geral do projeto: stack, convenções, quem você é. As regras são modulares e focadas, cada uma com uma responsabilidade só.

Agora toda sessão do Claude Code, em qualquer projeto, começa com esse contexto carregado. A IA sabe que precisa checar antes de construir.

O que mudou

A diferença aparece de algumas formas:

Menos tokens em problemas já resolvidos. A IA não fica reexplorando verificação de webhook do Stripe ou tratamento de erro do Resend. Ela lê o boilerplate, adapta e segue.

Código mais consistente entre projetos. As mesmas decisões (estrutura de metadata, formato da resposta de erro, padrão de log) aparecem do mesmo jeito em todo lugar. Isso importa quando você troca de contexto entre quatro codebases.

Menos tempo de review. Eu não fico questionando se a IA tomou a decisão certa em algo que eu já pensei a fundo. A decisão foi tomada uma vez, documentada, e acabou.

A questão de custo é real

Inferência de IA não é de graça, e só vai ficar mais complexa conforme agentes e subagentes viram norma. Rodar agentes em paralelo numa feature grande já custa dinheiro de verdade. Qualquer coisa que reduza trabalho redundante acumula em cada sessão, cada projeto, cada pessoa do time que encosta na mesma stack.

Um repo de boilerplates é uma das otimizações mais baratas que existem. Custa uma hora pra montar e se paga em toda integração dali pra frente.

O que entra em um bom boilerplate

Nem todo pedaço de código merece virar boilerplate. Um bom candidato é algo que você:

  1. Integra em mais de um projeto
  2. Já debugou pelo menos uma vez
  3. Já tomou decisões arquiteturais explícitas a respeito

Se os três forem verdade, documente. Se for código descartável, não perca tempo.

Contexto é o ativo de verdade

A maioria dos devs pensa em produtividade com IA em termos de prompt: como fazer perguntas melhores, como conseguir output melhor. Isso é válido, mas passa longe da alavanca maior.

O ativo de verdade é contexto estruturado. Boilerplates são uma camada. ADRs são outra. Regras que codificam como seu time trabalha, memória compartilhada do porquê das decisões. Quando esse contexto existe e é carregado em toda sessão, a IA não está começando do zero. Ela está construindo em cima do que você já descobriu.

Isso acumula. Todo problema resolvido deixa o próximo mais barato. Toda decisão documentada economiza tokens, tempo de review e o custo mental de explicar suas convenções de novo.

Um repo ai-boilerplates é um ponto de partida pequeno e concreto. Mas o hábito que ele cria é o que importa.