new in v3.0.0

Documentation-First Approach

Documentation-First includes tools to build deterministic specifications that AI can implement correctly, from any platform, using Claude, GPT, Gemini and others.

install and useread docs
~/project
85%
less hallucinations
78%
less rework
80%+
test coverage
<10%
error rate

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

1

discovery

analyst

Entende requisitos e avalia complexidade (LOW/MEDIUM/HIGH)

2

architecture[HIGH only]

architect

Design da arquitetura do sistema com diagramas C4 (apenas HIGH)

3

specification

analyst

Escreve documentação Arc42 + cenários BDD + ADRs

3.5

decompositionCRÍTICO

orchestrator

Quebra specs em tarefas atômicas <100 LOC - previne alucinações

4

implementation

developer

Implementa tarefa por tarefa com testes, validado pelo gatekeeper

5

validation

review+test

Code review + validação de testes (≥80% cobertura exigida)

6

documentation

documenter

Atualiza docs e README para corresponder à implementação

7

pre-commit

guardian

Validaçã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étricaAntesDepois (6 meses)Melhoria
Horas semanais em reuniões por desenvolvedor
Specs claras eliminam reuniões de alinhamento
15 horas6 horas-60%
Satisfação dos desenvolvedores
Menos frustração, mais autonomia
6.2/108.4/10+35%
Time-to-market de novas features
Workflow determinístico acelera entregas
48 dias35 dias-27%
Tempo de onboarding de novos desenvolvedores
Documentação viva facilita onboarding
6 semanas3.5 semanas-42%
Perda de contexto crítico em mudanças de time
Conhecimento capturado em specs Arc42
AltaBaixaSignificativa

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:

TypeScript
•
Python
•
Go
•
Rust
•
Java
•qualquer outra