Como fazer a IA programar certo — Projeto "AI Ready"

Ideia central

O erro mais comum é abrir o projeto no Claude Code (ou similar) e já sair mandando prompt. Programar com IA não começa no prompt — começa antes, deixando o projeto "AI Ready".

Por que ir direto ao prompt é um erro

• A LLM é stateless: não tem memória entre conversas. Toda nova janela começa do zero — não sabe o comando que roda o projeto, a estrutura de pastas, nem quais libs de front/back você usa.
• Sem contexto, ela adivinha → gasta muito mais token.
• Não é questão de modelo forte ou fraco: no teste feito nas turmas (com Opus e GPT, os mais caros), ambos criam um arquivo gigante de 400–500 linhas, tudo junto. O modelo é inteligente; o problema é falta de direcionamento.

Os 2 lados de um projeto AI Ready

1. Guias (guides) → direcionam a IA para o caminho certo.
2. Sensores (sensors) → monitoram e evitam que a IA fuja do padrão do projeto (ciclo de feedback).

---

Guias (evolução progressiva)

A IA sabe React, banco de dados etc. do treinamento, mas não sabe COMO você usa isso no seu projeto. Isso precisa estar escrito em algum lugar.

Rules (regras globais)

• Arquivos: AGENTS.md, CLAUDE.md — ou o padrão já defasado .cursor/rules. No fim, a mesma coisa.
• São long-term memory: injetadas via system prompt em toda conversa.
• Problema do modelo antigo (jogar tudo no .cursor/rules): incha o system prompt. Quanto mais regra, mais pesado o contexto já de largada — mesmo em tarefas que não têm nada a ver com aquela regra.
• Boa prática hoje: deixe no AGENTS.md/CLAUDE.md só o que é global e realmente importante:
  • estrutura de pastas
  • comando que roda os testes
  • porta da aplicação
  • alguns comandos de git
  • enforcements do time (regras obrigatórias)
• Enxuto: ideal entre 250 e 300 linhas. Instrução de uma linha resolve — não precisa de exemplo, floreio ou repetição. Esse arquivo tem peso forte no modelo; frontier models (Opus, GPT 5.5) seguem bem.
• Exemplo prático: a IA às vezes fazia git stash/git reset/git checkout no meio do trabalho e causava problemas. Solução: uma regra proibindo esses comandos no AGENTS.md → nunca mais aconteceu.

Skills (a evolução das rules)

Para as regras não-globais (padrão de React, forma de escrever no banco, jeito de escrever teste).

• Padrão surgiu em novembro e já dominou o mercado.
• Carregadas sob demanda — diferente das rules (carregadas inteiras).
• Estrutura: um cabeçalho (frontmatter) com name, description e talvez outras propriedades → só o cabeçalho entra no system prompt. O corpo só é carregado quando o modelo decide, via tool call. → economiza muito contexto.
• Servem também para processos do time: skill de "abrir Pull Request" (com checklist e formato de description), skill de "code review", orquestração, peer review entre agentes etc.
• Skill é uma pasta, não um arquivo (o "pulo do gato"): fica self-contained — dá para zipar e mandar para outra pessoa. Muito intercambiável/fácil de compartilhar. Pode conter vários tipos de arquivo, referências e até scripts.
• ⚠️ Alerta de segurança: cuidado com marketplaces de skills. Como skills podem conter scripts, baixar de qualquer lugar é risco de segurança.
• Ele mantém um repositório próprio de skills (link na descrição do vídeo) com skills feitas e curadas por ele.

---

Sensores

Se o guia diz o que fazer, o sensor deixa a IA saber se fez certo — um ciclo de feedback.

• Sem sensor: a IA escreve o arquivo e não descobre que errou. Quem descobre é você, depois, ao rodar o projeto e ver o erro → copiar stack trace, corrigir, prompt atrás de prompt, gastando mais token.
• Com sensor: ela mesma se corrige antes de você ver.

Tipos de sensores:

• Testes — o mais importante. Force a IA a rodar; ela vê que falhou e se corrige sozinha.
• Linter — ótimo para garantir regras do projeto.
• Formatters
• Type checking
• Playwright — abre o browser → sensor ponta a ponta (e2e).
• Banco de dados — pedir para testar se o banco local está aceitando/gravando corretamente.
• Logs de debug da aplicação.

---

Resumo prático

• Regra global → AGENTS.md enxuto.
• Resto das regras e processos → skills sob demanda.
• Sensores fecham o ciclo permitindo autocorreção.

Verdade que incomoda alguns

• Deixar o projeto AI Ready leva tempo — não é em 30 segundos, e não é para pedir para a própria IA fazer. Pode levar um dia, uma semana, ou exigir decisão com o time.
• Mas é esse tempo que para de queimar token em prompts repetidos.
• Ele mantém projetos base (usa muito TypeScript e Go — Compose e AD8 são em Go) já com estrutura, AGENTS.md, skills e config de lint, e vai copiando conforme precisa.
• Regras precisam ser vivas: não é "fazer uma vez e esquecer". Mantenha e atualize conforme o projeto muda ou conforme você observa a IA errando em algum ponto. Isso é o mais importante para colher bons resultados no AI-driven development.

---

Conclusão: O programador do futuro é um arquiteto de contexto

No desenvolvimento de software moderno, a produtividade não é mais medida por quão rápido você consegue digitar código, mas por quão bem você consegue instruir a máquina a escrevê-lo por você.

Mapear regras no AGENTS.md, modularizar processos em skills e blindar o fluxo de trabalho com sensores não é preciosismo — é a base do AI-driven development. Tratar a IA como um estagiário genial que acabou de chegar, dando a ela o manual da empresa (guias) e um supervisor automático (sensores), é o que separa quem desperdiça milhares de tokens em loops infinitos de erro daqueles que entregam código de produção em minutos.

Preparar o seu projeto para ser AI Ready exige esforço inicial e manutenção contínua, mas o retorno sobre esse investimento é imediato. Ao parar de programar via prompts improvisados e começar a programar via arquitetura de contexto, você finalmente destrava o real potencial da inteligência artificial.

Não lute contra as limitações da IA; construa o ecossistema para que ela jogue no seu time, sob as suas regras.

---

Se chegou até aqui e quer entender mais a fundo como fazer, acesse meu mini treinamento de Desenvolvimento com IA aqui