Escreva um Arquivo de Contexto (AGENTS.md)

A coisa de maior alavancagem que você pode fazer é escrever um arquivo de contexto que a IA lê automaticamente. Ferramentas diferentes procuram nomes diferentes — AGENTS.md, CLAUDE.md, .cursorrules, ou um .github/copilot-instructions.md — mas a ideia é idêntica: um documento vivo que conta à IA como o seu projeto funciona e como você quer que ela se comporte.

Sem ele, a IA chuta. Com ele, a IA para de reformatar seu código, para de inventar bibliotecas que você não usa e para de reexplicar decisões que você já tomou. Pense nisso como documentação de integração para um novo colega de equipe brilhante, mas com amnésia total entre sessões — tudo que ele precisa para ser produtivo tem que estar em algum lugar que ele vai ler toda vez.

Um arquivo inicial prático:

# Project: Invoice Manager

## What this is
A small web app for freelancers to create and track invoices.

## Tech stack
- TypeScript + React (Vite)
- Tailwind for styling
- SQLite via Prisma
- Vitest for tests

## Commands
- Install: `npm install`
- Run dev server: `npm run dev`
- Run tests: `npm test`
- Lint: `npm run lint`

## Conventions
- Use functional components and hooks; no class components.
- Keep components small; one component per file.
- Write a test for every new function in `src/lib`.
- Never edit files in `src/generated/` — they are auto-generated.

## Don'ts
- Don't add new dependencies without flagging it first.
- Don't commit secrets; use environment variables.

Mantenha-o curto e atualizado. Um arquivo de contexto que cresce até mil linhas deixa de ser lido com atenção — por você ou pelo modelo — então pode-o com a mesma agressividade com que você adiciona coisas a ele. Quando a IA repetidamente fizer a mesma suposição errada, esse é o seu sinal para adicionar uma linha; quando uma regra não corresponder mais à realidade, apague-a antes que comece a enganar ativamente o agente.

Alguns padrões separam um arquivo de contexto que funciona de um que é ignorado:

• Seja específico e concreto. "Use nossas convenções" não serve para nada. "Use zod para validação; não usamos yup" é uma regra que a IA de fato consegue seguir.
• Diga os "não faça" com tanta força quanto os "faça". Modelos são ansiosos para ajudar, o que significa que vão adicionar uma dependência ou reescrever uma configuração de bom grado, a menos que você diga para não fazerem isso.
• Aponte para exemplos. "Siga o estilo de src/features/invoices" dá à IA um modelo concreto para copiar, em vez de uma instrução vaga para interpretar.

Trate o arquivo de contexto como um registro de toda lição que, sem ele, você teria que repetir. É o investimento mais barato e mais duradouro deste capítulo inteiro.