Todo projeto tem decisões que não aparecem no README. A equipe usa actions em vez de services, valida entrada num ponto específico e evita um recurso do framework por uma razão aprendida em produção. Um agente de código vê os arquivos, mas nem sempre enxerga que aquele padrão é deliberado.
O Laravel Boost mudou a forma de capturar esse contexto. O comando anterior, boost:infer-conventions, aplicava detectores escritos à mão. Agora uma skill de agente audita o projeto em dezenas de dimensões e propõe regras em Markdown para revisão humana.
Detectar frequência não é descobrir intenção
A primeira versão era determinística, rápida e não consumia tokens. O limite era estrutural: cada convenção nova precisava virar código no Boost. Além disso, contar padrões produz falsos sinais. Uma construção pode aparecer cem vezes por herança histórica, enquanto uma decisão arquitetural essencial aparece em três arquivos.
A abordagem nova pede que o agente examine cerca de 49 aspectos agrupados em dez áreas, procure evidência consistente e apresente as descobertas. A proposta não é escrever uma biografia do repositório. É preservar decisões específicas que outro agente provavelmente perderia.
O que merece virar regra
- Uma escolha arquitetural repetida, com ao menos três exemplos coerentes e sem alternativa relevante competindo no projeto.
- Uma ausência deliberada: “não usamos observers neste domínio porque a ordem precisa ser explícita”.
- Um limite entre camadas que o framework, sozinho, não consegue inferir.
- Uma convenção de testes ou dados que previne um erro real e recorrente.
Regras mecânicas ficam melhor em ferramentas mecânicas. Formatação pertence ao formatter. Tipos e contratos verificáveis pertencem ao analisador estático. Colocar “use quatro espaços” no contexto do agente consome atenção para repetir algo que o CI já sabe cobrar.
Evidência antes de autoridade
O ponto mais saudável do fluxo é a revisão. A skill não deveria decretar arquitetura com base numa amostra acidental. Ela apresenta achado e evidências; uma pessoa decide se aquilo é regra, dívida técnica ou coincidência. Só então o texto entra em .ai/rules, pode receber escopo por glob e segue versionado junto do projeto.
O Boost também oferece uma ferramenta MCP chamada record-rule. Ela registra título, nota e escopo e atualiza o índice. Isso permite capturar uma decisão no momento em que ela acontece, sem esperar uma auditoria futura. “Esta integração exige idempotency key porque o provedor repete webhooks” é muito mais útil quando registrada durante o trabalho.
Markdown simples ganhou da memória sofisticada
Num relato posterior, a equipe contou que experimentou busca semântica com vetores e a removeu após cinco dias. O substituto foi um conjunto de arquivos Markdown, um índice gerado e busca textual. O motivo é interessante: regras de projeto costumam usar termos concretos, precisam ser legíveis e devem funcionar em várias integrações de agentes.
Não é prova universal de que busca semântica não serve. É evidência de que, para um conjunto pequeno de instruções específicas e versionadas, grep e escopo por caminho podem entregar mais previsibilidade com menos infraestrutura.
A manutenção ainda é a parte difícil
Regra correta hoje pode ficar obsoleta depois de uma refatoração. O fluxo anunciado ainda não faz auditoria automática de regras antigas. Portanto, trate esses arquivos como código: revise no pull request, aponte dono quando necessário e remova instruções que já não descrevem o repositório.
O melhor critério é simples: se um agente competente pudesse ler o código e mesmo assim tomar uma decisão errada por não conhecer a intenção da equipe, talvez exista uma regra útil ali. Se a máquina consegue verificar sozinha, escreva uma verificação.