novidades na v3.0.0
Documentation-First Approach
Documentation-First inclui ferramentas para construir especificações determinísticas que a IA pode implementar corretamente, de qualquer plataforma, usando Claude, GPT, Gemini e outros.
o que é documentation-first?
Uma abordagem de desenvolvimento orientada a especificações que elimina alucinações da IA
Documentation-First é uma metodologia que coloca especificações determinísticas antes do código. Usando frameworks Arc42, C4, BDD e ADR, cria requisitos não ambíguos que a IA pode implementar com <10% de taxa de erro.
O problema
60-80% de taxa de alucinação
LLMs geram código plausível mas incorreto sem especificações claras. O mesmo prompt produz resultados completamente diferentes.
Qualidade imprevisível
A qualidade do código varia drasticamente entre execuções. Sem consistência, sem confiabilidade, sem forma de garantir output pronto para produção.
Dívida técnica crescente
Retrabalho constante, bugs em produção, decisões de arquitetura pouco claras. Times gastam mais tempo corrigindo do que construindo.
A solução
Orientado a especificações
Toda feature começa com uma spec determinística (Arc42 + C4 + BDD + ADR). Zero ambiguidade, requisitos completos, clareza perfeita.
Task decomposition
Specs grandes são quebradas em tarefas atômicas <100 LOC. Mantém o foco da IA, previne overflow de contexto, garante output determinístico.
Quality gates
Validação automatizada em cada etapa. SOLID, DDD, Object Calisthenics aplicados. 80%+ de cobertura de testes garantida antes do merge.
Como funciona
O workflow de 7 fases que transforma requisitos em código pronto para produção
discovery
analystEntende requisitos e avalia complexidade (LOW/MEDIUM/HIGH)
architecture[HIGH only]
architectDesign da arquitetura do sistema com diagramas C4 (apenas HIGH)
specification
analystEscreve documentação Arc42 + cenários BDD + ADRs
decompositionCRÍTICO
orchestratorQuebra specs em tarefas atômicas <100 LOC - previne alucinações
implementation
developerImplementa tarefa por tarefa com testes, validado pelo gatekeeper
validation
review+testCode review + validação de testes (≥80% cobertura exigida)
documentation
documenterAtualiza docs e README para corresponder à implementação
pre-commit
guardianValidação final: constitution compliance, testes, linters, specs atualizados
Por que a fase 3.5 é crítica?
Problema: Contexto >5000 linhas = IA perde foco (decaimento de atenção O(n²))
Solução: Orchestrator quebra specs em tarefas <100 LOC
Resultado: Output determinístico, qualidade previsível, zero alucinações
Impacto organizacional
Resultados mensuráveis após 6 meses de implementação
| Métrica | Antes | Depois (6 meses) | Melhoria |
|---|---|---|---|
Horas semanais em reuniões por desenvolvedor Specs claras eliminam reuniões de alinhamento | 15 horas | 6 horas | -60% |
Satisfação dos desenvolvedores Menos frustração, mais autonomia | 6.2/10 | 8.4/10 | +35% |
Time-to-market de novas features Workflow determinístico acelera entregas | 48 dias | 35 dias | -27% |
Tempo de onboarding de novos desenvolvedores Documentação viva facilita onboarding | 6 semanas | 3.5 semanas | -42% |
Perda de contexto crítico em mudanças de time Conhecimento capturado em specs Arc42 | Alta | Baixa | Significativa |
Dados baseados em:
- • Experimentos controlados (Crônica 10 - MANIFEST.md)
- • Estudos de caso em times distribuídos (6 meses de implementação)
- • Full Scale - Documentation-First Approach
Principais benefícios
Output determinístico
Mesmo input produz mesmo output, sempre. Sem mais resultados imprevisíveis.
Alta qualidade garantida
80%+ de cobertura de testes, SOLID, DDD, Object Calisthenics aplicados automaticamente.
Rápido e previsível
Saiba exatamente quanto tempo features vão levar. Velocidade consistente entre sprints.
Código pronto para produção
Entregue com testes, documentação, zero dívida técnica. Pronto para deploy.
Alinhamento de time
Especificações compartilhadas = entendimento compartilhado. Sem mais falha de comunicação.
Open source e gratuito
Licença MIT, gratuito para sempre. Desenvolvimento orientado pela comunidade.
Pronto para começar?
Baixe o scaffold e transforme seu código gerado por IA de caos para certeza
Funciona com qualquer stack: