Estruture Seu Projeto Para Que a IA Consiga Navegar Nele
Modelos de IA raciocinam sobre seu código lendo-o. Um projeto bagunçado, disperso e inconsistente é tão difícil para eles quanto é para você. Você não precisa de uma arquitetura perfeita, mas alguns hábitos compensam imediatamente:
- Mantenha um layout previsível. Código-fonte em um só lugar, testes ao lado ou espelhando o código-fonte, configuração na raiz.
- Use nomes claros e descritivos.
calculateMonthlyInvoiceTotalé melhor quecalc2. A IA usa nomes como pistas. - Prefira arquivos menores. Um arquivo de 200 linhas é mais fácil de alterar corretamente do que um de 2.000, tanto para você quanto para ela.
- Coloque coisas relacionadas juntas. Quando o código, os estilos e os testes de uma funcionalidade ficam juntos, a IA reúne contexto em uma única leitura.
- Mantenha um ponto de entrada claro. Um único lugar óbvio onde o aplicativo começa dá à IA um fio para puxar quando estiver mapeando o projeto.
Um layout típico e amigável para IA pode se parecer com isto:
my-app/
├── AGENTS.md # project rules & context for the AI
├── README.md # what the project is, how to run it
├── .env.example # documents needed secrets (no real values)
├── .gitignore # excludes .env, build output, node_modules
├── package.json # scripts: dev, test, lint, build
├── src/
│ ├── features/
│ │ └── invoices/ # code + tests for one feature, together
│ ├── lib/ # shared helpers
│ └── index.ts # entry point
└── tests/ # cross-cutting / integration tests
O ganho é cumulativo: quanto mais fácil for para a IA navegar pelo seu projeto, menores e mais cirúrgicas se tornam suas mudanças. Um repositório bem organizado permite que a IA mexa em três arquivos relevantes em vez de tentar adivinhar entre trinta — o que significa diffs menores, menos acidentes e revisões que você realmente consegue ler. Se você perceber a IA fazendo edições amplas e sem foco, muitas vezes o verdadeiro culpado é a estrutura, não o .