Como a IA erra (e como isso vira bug no seu commit)

Laboratório: o arquivo de contexto do seu projeto

Mão na massa 7 min de leitura 25 min de prática Você leva: CONTEXT.md do seu projeto

Montar o CONTEXT.md que você vai colar no começo de toda conversa técnica — e que elimina a maior parte dos erros da aula 1.

Quase todo erro das duas aulas anteriores tem a mesma origem: informação que estava na sua cabeça e não na conversa. Esta aula resolve isso uma vez só.

A ideia é simples: um arquivo curto, versionado junto com o código, que responde de antemão as perguntas que o assistente não sabe fazer. Você cola no início da conversa, ou aponta a ferramenta para ele, e para de repetir contexto a cada pedido.

Curto é requisito, não estilo. Contexto grande demais dilui o que importa e come a janela disponível para o problema em si. Mire em uma tela.

Sem contexto

Cria um endpoint para listar pedidos com filtro por status.

Vem um exemplo genérico, com framework que você não usa, sem paginação, sem autorização e com o padrão de resposta errado.

Com o CONTEXT.md colado antes

[CONTEXT.md]

Cria um endpoint para listar pedidos com filtro por status.

Vem no seu framework e versão, com o seu padrão de resposta, respeitando a autorização e a paginação que já existem.

A diferença: O pedido é idêntico. O que muda o resultado é o que o assistente sabia antes de ler o pedido.

Você leva daquiCONTEXT.md do seu projeto

Preencha uma vez, mantenha no repositório e reutilize em toda conversa. Substitua os exemplos entre colchetes pelos dados reais do seu projeto.

# Contexto do projeto

## Stack e versões
- Linguagem: [PHP 8.1 / Python 3.8 / Node 18]
- Framework: [Laravel 10 / Django 4.2 / Express 4]
- Banco: [MySQL 8.0, InnoDB, utf8mb4]
- Infra: [container Docker, deploy por CI, 2 réplicas]

## Convenções que o código segue
- Camadas: [entrada fina → controller → repositório; nenhum SQL fora do repositório]
- Nomes: [métodos em camelCase, tabelas no plural em snake_case]
- Erros: [exceção de domínio própria; nunca catch vazio]
- Testes: [PHPUnit; nome do teste descreve a regra, não a função]

## Escala real
- [pedidos: ~8 mil/mês, cada um com 3 a 40 itens]
- [usuários simultâneos no pico: ~120]
- [maior tabela: eventos, 14 milhões de linhas]

## Restrições inegociáveis
- Não adicionar dependência sem justificativa explícita.
- Não alterar [contrato da API pública / schema sem migração].
- Toda query com valor do usuário usa bind.
- [regra específica do seu domínio]

## O que NÃO posso colar aqui
- Credenciais, tokens, .env, dados de clientes reais.

## Como quero as respostas
- Perguntas antes da solução quando faltar informação.
- Alteração mínima, com o diff explicado.
- Toda premissa marcada como PREMISSA.

Onde guardar: Na raiz do repositório, versionado. Se a sua ferramenta lê arquivos do projeto (Cursor, Claude Code, Copilot Workspace), ela vai encontrar sozinha.

Mão na massa25 min

Produzir o CONTEXT.md do projeto em que você trabalha hoje e provar que ele muda a resposta.

Use um projeto real. O exercício não funciona com projeto imaginário, porque a parte difícil é justamente descobrir o que você sabe e nunca escreveu.

Copie o modelo acima para a raiz do seu repositório.
Preencha stack e versões consultando o arquivo de dependências — não de memória.
Preencha a escala real consultando o banco ou o monitoramento. Se não souber, escreva "não medido": isso também é informação útil.
Escolha uma tarefa pequena e real do seu backlog. Peça a solução sem colar o contexto e guarde a resposta.
Abra uma conversa nova, cole o CONTEXT.md, peça exatamente a mesma coisa e guarde a segunda resposta.
Compare as duas lado a lado e anote quais diferenças vieram só do contexto.

Deu certo quando

O arquivo cabe em uma tela.
Toda versão foi conferida no arquivo de dependências, não lembrada.
A segunda resposta usa o seu framework, o seu padrão e a sua escala.
Você consegue apontar pelo menos três diferenças concretas entre as duas respostas.

Se travar: Se as duas respostas ficaram parecidas, o contexto provavelmente está genérico demais. Adicione a seção de escala real e uma restrição específica do seu domínio — são as duas que mais mudam a saída.

Mantenha vivo

Um CONTEXT.md desatualizado é pior que nenhum: ele injeta com confiança uma versão que não é mais a sua. Revise quando subir versão maior de framework ou quando mudar uma convenção.

Em uma frase

Contexto escrito uma vez vale mais que prompt caprichado toda vez.

← Aula anterior Próxima aula →

Comentários e dúvidas

Inscreva-se grátis para comentar, tirar dúvidas, marcar seu progresso e emitir o certificado ao fim do curso.

Inscrever-se grátis com Google

Ainda não há comentários nesta aula.