De onde veio esse projeto
Recentemente me certifiquei em Arquitetura de Informação com IA pelo IBMEC — e o trabalho de conclusão foi a oportunidade que eu precisava para transformar em produto uma ideia que eu carregava há tempos.
Quem trabalha com requisitos sabe bem como isso funciona na prática: a tarefa chega ao desenvolvimento com o objetivo vago, sem critérios de aceite definidos, sem que ninguém tenha pensado no que acontece quando o usuário faz algo inesperado. O time começa a trabalhar, aparecem as dúvidas, e aí vem o retrabalho — que, na maioria das vezes, podia ter sido evitado bem antes.
Eu vivia isso. Não por falta de cuidado das pessoas, mas porque não havia nenhuma camada de verificação entre o momento em que a especificação era escrita e o momento em que ela chegava ao desenvolvimento. Era tudo na base da revisão manual — quando acontecia. Sempre tive vontade de fazer algo a respeito. A certificação me deu o contexto, as ferramentas e o empurrão para construir.
Foi assim que nasceu o SpecGuard.
O que é o SpecGuard
O SpecGuard é um sistema especialista que avalia automaticamente especificações de requisitos e retorna um veredicto antes que elas cheguem ao time de desenvolvimento. Ele analisa a especificação em sete dimensões, calcula um score de 0 a 100, identifica bloqueadores críticos e, se a especificação for aprovada, gera automaticamente um documento SRS e as informações para criação do card no Jira.
Se for reprovada, nenhum artefato é gerado. Essa decisão é intencional — a reprovação não é um aviso, é um bloqueio funcional que força a revisão antes de qualquer avanço.
Como eu construí
Antes de escrever qualquer linha de código, escrevi uma especificação — do SpecGuard. Faz sentido, né? Criei um arquivo SPEC.md descrevendo o que o sistema deveria fazer, como deveria se comportar e quais critérios deveria avaliar. A partir daí, usei o Claude Code como parceiro técnico em todas as etapas: definição da arquitetura, escrita do código Python, construção da base de conhecimento e elaboração do system prompt.
A interface web foi construída com Streamlit, um framework de código aberto que transforma scripts Python em aplicações web interativas sem precisar de desenvolvimento front-end separado. Isso foi essencial: queria que o sistema fosse acessível para Product Owners e analistas — pessoas que precisam usar a ferramenta, não necessariamente saber programar.
A decisão de arquitetura mais importante
O ponto central do sistema não é o modelo de linguagem — é a base de conhecimento. O SpecGuard não envia a especificação diretamente ao LLM e espera uma resposta genérica. Antes da análise, ele carrega quatro arquivos YAML que ficam armazenados no próprio código e são injetados no system prompt:
risk_catalog.yaml — catálogo de riscos por categoria, com severidade e estratégias de mitigação
lgpd_checklist.yaml — mapeamento de dados pessoais, bases legais e controles exigidos pela LGPD
business_rules.yaml — padrões obrigatórios e anti-padrões para regras de negócio
Essa estrutura garante que o modelo analise a especificação com critérios específicos e conhecimento de domínio — não apenas com o que ele sabe em geral. E como toda a inteligência de domínio está nos arquivos YAML, os critérios podem ser atualizados sem mexer no código. Cada organização pode adaptar para sua realidade.
Como a avaliação funciona
A análise percorre sete dimensões ponderadas. O score final é a média ponderada das sete, em uma escala de 0 a 100:
| Dimensão | Peso | O que verifica |
|---|---|---|
| Completude | 20% | Presença de todos os elementos necessários para implementação |
| Clareza | 15% | Linguagem sem ambiguidade nem dupla interpretação |
| Coerência | 15% | Consistência interna e ausência de contradições |
| Completude Técnica | 15% | O time consegue iniciar sem dúvidas adicionais |
| Regras de Negócio | 15% | Regras específicas, testáveis, com condições e exceções |
| Riscos | 10% | Riscos técnicos e de negócio mapeados |
| LGPD | 10% | Conformidade com a Lei n.º 13.709/2018 quando aplicável |
Para ser aprovada, uma especificação precisa de score igual ou superior a 75 e ausência de bloqueadores críticos. Os bloqueadores são problemas que, independentemente do score, inviabilizam o início seguro do desenvolvimento — como ausência de objetivo claro, falta de critérios de aceite para funcionalidades principais ou dados pessoais sem requisitos de conformidade com a LGPD.
Por que incluí o BDD como bloqueador crítico
O formato Given-When-Then, proposto pelo Behavior-Driven Development, elimina ambiguidades ao definir explicitamente o contexto, a ação e o resultado esperado de uma funcionalidade. Na prática, a ausência desse padrão em funcionalidades principais é uma das principais causas de retrabalho que eu observei. Por isso, no SpecGuard, é tratada como bloqueador — não como sugestão.
Por que incluí a LGPD
Na maioria dos times que conheço, a conformidade com a LGPD é tratada como preocupação técnica posterior — algo para resolver na implementação. O problema é que, quando os requisitos de proteção de dados não são pensados na especificação, o custo de corrigi-los depois é muito maior. O SpecGuard verifica automaticamente quando uma especificação menciona dados pessoais e não apresenta os requisitos correspondentes de proteção e base legal.
O que acontece na tela de resultados
Ao concluir a análise, o sistema exibe um banner de APROVADO ou REPROVADO com o score geral, seguido da avaliação por dimensão com status colorido, os bloqueadores críticos com localização precisa na especificação e recomendação de correção, os alertas de nível intermediário e as recomendações gerais de melhoria.
Se aprovada, são exibidos os previews dos artefatos gerados: o documento SRS versionado e as informações para criação do card no Jira — com título, descrição, critérios de aceite e sugestão de story points. Se reprovada, esses artefatos simplesmente não existem. O sistema bloqueia a geração até que os problemas sejam corrigidos e a especificação seja reavaliada.
O que eu aprendi construindo isso
A maior surpresa foi perceber o quanto a qualidade da análise depende da qualidade do prompt e da base de conhecimento — não do modelo. O Claude Opus é muito capaz, mas sem contexto de domínio estruturado, a análise seria genérica demais para ser útil. A combinação de LLM com conhecimento específico é o que transforma uma análise superficial em algo acionável.
Outro aprendizado foi sobre o processo de construção em si. Escrever a especificação do SpecGuard antes de começar a codar foi essencial — e um pouco irônico. Mas funcionou exatamente como deveria: ter clareza sobre o que o sistema deveria fazer tornou cada decisão de arquitetura mais fácil de tomar.
Limitações honestas
O SpecGuard avalia com os critérios da base de conhecimento embarcada, que reflete boas práticas gerais. Times com padrões ou terminologias específicas precisarão adaptar os arquivos YAML para que a avaliação seja relevante para seu contexto.
Na versão atual, não há integração nativa com Jira e Confluence — os artefatos gerados precisam ser copiados manualmente. O sistema também não mantém histórico entre sessões, o que impede o rastreamento da evolução de uma especificação ao longo de ciclos de revisão.
Esses são os próximos passos: integração com ferramentas, configuração da base de conhecimento por organização e histórico de análises.