O que aprendi organizando um projeto AI First

Organizar um projeto AI First não é simplesmente usar IA em mais tarefas. O principal aprendizado é que a IA trabalha melhor quando o projeto já tem contexto, documentação, limites, critérios de aceitação e validação técnica.

Contexto

Quando comecei a organizar o brunopaim.tech, a ideia era ter um site pessoal simples: links, projetos, estudos, blog e alguns bastidores sobre desenvolvimento, IA e produtos digitais.

Com o tempo, o projeto virou também um laboratório de processo. Não no sentido de criar uma metodologia fechada ou um manual gigante para qualquer coisa. A ideia foi mais prática: deixar o projeto preparado para ser entendido, modificado e validado com apoio de IA sem depender apenas de memória de chat ou de prompts soltos.

É nesse sentido que tenho usado a expressão AI First por aqui. Para mim, neste projeto, AI First não significa deixar a IA decidir tudo. Também não significa substituir estudo, revisão ou critério técnico.

Significa organizar contexto, documentação e validação de um jeito que facilite trabalhar com IA, Codex ou agentes sem perder rastreabilidade.

O problema dos prompts soltos

O problema dos prompts soltos é que eles funcionam bem até deixarem de funcionar.

Você explica uma tarefa, recebe uma resposta, ajusta alguma coisa e segue. Para uma mudança pequena, isso pode ser suficiente. Mas quando o projeto envolve posicionamento, tom de voz, padrões visuais, estrutura de blog, SEO, arquivos aprovados, specs e validação, a conversa começa a carregar responsabilidade demais.

• qual é o tom certo do projeto?
• quais informações não podem ser alteradas?
• quais arquivos representam conteúdo aprovado?
• quando uma spec é necessária?
• quais comandos validam uma implementação?
• o que está fora de escopo?
• o que já foi decidido antes?

Quando essas respostas não estão no projeto, a IA precisa adivinhar mais. E quando ela adivinha mais, o risco de sair do posicionamento, mexer no que não deveria ou implementar algo antes da hora aumenta.

A pergunta que guiei neste processo foi: como organizar um projeto para que a IA ajude mais, mas o critério continue nas mãos de quem desenvolve?

1. Contexto do projeto em arquivos

O primeiro aprendizado foi tirar contexto importante da memória informal e colocar em arquivos do repositório.

O AGENTS.md, por exemplo, funciona como uma espécie de memória operacional. Ele registra objetivo do site, posicionamento, stack, restrições, padrões de copywriting, regras para blog e validações esperadas.

• o site não deve parecer software house;
• o tom deve ser pessoal, técnico e acessível;
• informações sensíveis não devem ser alteradas sem confirmação;
• posts precisam passar por ideia, pauta, rascunho, aprovação e implementação;
• mudanças relevantes precisam de validação técnica;
• build, generate e git status fazem parte do fechamento.

Esse tipo de contexto não garante que tudo saia perfeito. Mas reduz bastante a chance de uma resposta genérica ignorar o jeito do projeto.

2. Documentação como memória viva

Outra camada foi separar documentos de apoio. O brief explica o que é o site. O design system preserva decisões visuais. A estratégia de conteúdo orienta os temas. As diretrizes do blog ajudam a manter o tom. A documentação de Spec-Driven Development explica quando desacelerar antes de implementar.

Na prática, isso evita que cada mudança vire uma nova decisão do zero. Documentação boa, nesse contexto, não é enfeite. É uma forma de reduzir ruído entre intenção e execução.

3. Specs antes de mudanças relevantes

O terceiro aprendizado foi usar specs leves antes de mudanças que podem afetar estrutura, conteúdo, visual ou posicionamento.

• qual problema essa mudança resolve?
• o que entra no escopo?
• o que fica fora?
• quais arquivos provavelmente serão afetados?
• como saber que ficou pronto?
• quais validações precisam acontecer?

Isso ajuda a IA porque transforma uma intenção vaga em critérios de execução. E ajuda quem revisa porque deixa claro se a implementação respeitou o combinado.

4. Separar maturidade editorial

No blog, a separação entre ideia, pauta, rascunho, aprovado e implementado foi uma das partes que mais organizaram o processo.

• ideia captura o tema;
• pauta define tese, público, SEO, escopo e reaproveitamento;
• rascunho desenvolve o texto;
• aprovado confirma tom, sensibilidade e versão em inglês;
• implementação transforma o conteúdo em dados do site;
• revisão final valida rota, imagem, SEO e build.

Essa separação deixa a IA mais útil porque ela sabe em qual maturidade o conteúdo está. Também deixa mais fácil dizer: ainda não é hora de publicar.

5. Validação técnica depois da execução

O último ponto é talvez o mais importante: AI First não elimina validação.

• revisar o diff;
• conferir git status;
• rodar npm run build;
• rodar npm run generate quando há publicação estática;
• validar a rota no navegador quando existe mudança visual ou novo post;
• checar canonical, Open Graph e dados estruturados nos posts relevantes;
• preservar alterações fora de escopo.

Essa parte é menos charmosa do que gerar uma tela ou escrever um artigo. Mas é onde o trabalho deixa de ser apenas uma resposta plausível e passa a ser uma mudança verificável.

Exemplo prático

Um exemplo simples é o próprio fluxo de publicação de posts. Se eu pedisse apenas “crie um artigo sobre AI First”, provavelmente sairia um texto aceitável. Talvez até bem escrito. Mas ele poderia ficar genérico, parecer manifesto, repetir demais outros posts ou prometer mais do que deveria.

1. a ideia aparece no backlog;
2. uma spec editorial define objetivo, escopo e fora de escopo;
3. a pauta estrutura tese, público, SEO, exemplos seguros e reaproveitamento;
4. o rascunho desenvolve o texto sem ainda publicar;
5. a aprovação manual confirma tom, sensibilidade e versão em inglês;
6. só depois o post entra no site;
7. a implementação passa por build, generate, rota, sitemap e dados estruturados.

A IA participa de várias partes, mas ela não decide sozinha que algo está pronto. Esse é o ponto que mais me interessa: usar IA para acelerar o trabalho sem dissolver as etapas que dão confiança ao resultado.

Aprendizados

• AI First, para este projeto, é mais sobre organização de contexto do que sobre usar IA em tudo.
• AGENTS.md ajuda a preservar restrições, tom, stack e validações entre sessões.
• Documentação reduz decisões repetidas e dá mais consistência para respostas da IA.
• Specs leves diminuem ambiguidade antes de editar arquivos.
• Separar ideia, pauta, rascunho, aprovação e implementação evita publicar no impulso.
• Validação técnica continua sendo indispensável, mesmo quando a implementação parece correta.
• Quanto mais o contexto fica no repositório, menos o projeto depende da memória de uma conversa específica.

Limites e ressalvas

Essa abordagem ainda está em evolução. Não acho que todo projeto precise da mesma estrutura. Um experimento pequeno pode funcionar bem com menos documentação. Um estudo rápido talvez não precise de spec. Uma alteração simples pode ser resolvida com uma revisão direta.

Também não quero transformar AI First em um rótulo grandioso. No contexto deste site, a ideia é bem pragmática: preparar o projeto para que IA ajude com mais contexto e para que as mudanças continuem revisáveis.

Documentação não resolve tudo. Ela pode estar desatualizada, incompleta ou burocrática demais. Por isso, precisa ser tratada como parte viva do projeto, não como um arquivo que ninguém lê.

E, claro, IA ainda erra. O processo ajuda a reduzir esse risco, não a eliminar.

Conclusão

O principal aprendizado organizando um projeto AI First é que a qualidade do trabalho com IA não depende só do modelo ou do prompt. Depende do ambiente em que a IA entra.

Quando o projeto tem contexto explícito, documentação útil, specs leves, fluxo editorial claro e validação técnica, a IA deixa de trabalhar no escuro. Ela passa a operar dentro de limites mais claros.

Ainda assim, o critério continua humano. É a pessoa que define objetivo, escolhe o escopo, aprova o conteúdo, revisa o diff, roda validações e decide se aquilo realmente faz sentido para o projeto.

O equilíbrio mais interessante é usar IA para ganhar apoio na execução e na organização, mas manter o processo legível o suficiente para continuar nas nossas mãos.