Template de arquitetura

Eu sei o nome talvez seja ruim, mas preciso compartilhar como tenho usado isso e finalmente mudou a minha forma de programar usando AI Agents.

Mas antes vamos voltar um pouco em redes neurais? Brincadeira.

Nessa altura todos nós já sabemos que o prompt inicial conta muito e até mesmo o uso de RAG contribui para limitar os parâmetros das LLMs.


Vou ter que criar uma pequeno desvio de rota aqui, enquanto eu estava escrevendo esse texto, me deparei com o conceito de AGENTS.md

O básico dele já endereça alguns pontos do template de arquitetura, mas ainda não vai conter os itens necessários que vamos abordar. É parte da combinação e estratégia para ser usada na execução inicial do seu projeto.


Os transformers generativos, devem ter restrições para não gerar coisas além do que gostaríamos, a famosa alucinação e aqui entra algumas técnicas que tenho experimentado e finalmente consegui parar de lutar contra IA ao desenvolver e chamo isso de Template de Arquitetura.

Detalhando um pouco o que é?

O Template de arquitetura, é um documento markdown onde contém as pastas do projeto, o estilo de escrita do código e dos testes, o tipo de abordagem, se é mais uma programação funcional ou programação orientada a objetos, também como a IA deve se comportar ao gerar código, principalmente escrevendo testes primeiro e resolvendo o software depois.

Feito isso o modelo Claude Sonnet com Github Copilot tenho obtido melhores resultados, ao ler esse arquivo anexado no meus prompts e solicitações de ação.

Construindo um Template de Arquitetura

Vamos começar por considerar um projeto front-end em sveltekit (se vc ainda está preso no React, só lamento, mas funciona também), a minha preferência para projetos front-end é seguir uma linha parecida com o Atomic Design, começar organizando os menores componentes para os maiores como uma tela completa.

Em todos os cenários as rotas tem seus controllers com telas e onde fazem chamadas de requisições para serviços, alguns outros components mais complexos acabam se tornando panels e também pode chamar as services.

Então imagina algo assim Rota -> Controller -> Panel -> Components, todos seguindo Data Down Actions Up, evitando o máximo possível efeitos colaterais.

Essas instruções devem ir para o arquivo markdown, a LLM, foi treinada e sabe o peso dessas informações.

Também é necessário mostrar qual caminho ela não deve ir. Criei um repositório contendo um login funcional em que não escrevi uma linha de código, ele só seguiu os guidelines que mandei e as interações e correções de erros.

GitHub - flpms/architecture-template: Architecture Template (RAG via Markdown)
Architecture Template (RAG via Markdown). Contribute to flpms/architecture-template development by creating an account on GitHub.

Se você quer entender a sequência de pensamentos pode ler o prompts.md que gere e mostra as falhas e como foi corrigido.

Ainda pretendo continuar aumentando essa aplicação como exemplo e ampliando os testes, mas com isso já dá para demonstrar meu ponto em que o contexto e um mapa para a LLM se guiar já consegue algum ganho na geração de código, até mesmo em projetos complexos e com libs fora do treino do modelo.

Eu usei VSCode no modo agente com Claude Sonnet 4.0

Ainda tem técnicas melhores de como guiar os agents para serem ainda mais efetivos e que pretendo combinar e expandir a ideia.

Até a próxima!