Comece pelo seu projeto real.

1. Prepare o ambiente e o contexto

O kit usa Python 3.11+, Bash, Git, grep, awk e ferramentas Unix usuais. Pode ser usado em macOS/Linux; no Windows, use um ambiente compatível, como WSL. O modelo não exige assinatura de IA, plugin ou serviço de nuvem.

Um assistente de código é opcional. Ele precisa conseguir ler os arquivos do projeto e seguir as instruções acordadas. O mesmo fluxo também pode ser seguido por uma equipe sem IA.

2. Baixe e examine o kit

Extraia em uma pasta nova para conhecer a estrutura. Não execute um comando de cópia que sobrescreva seu repositório. Leia README.md, PATHS.toml e as regras de execução antes de adaptar.

unzip -n modelo-projetos-1.0.0.zip
cd modelo-projetos
# Leia README.md e PATHS.toml antes de adaptar.

3. Entenda a estrutura existente

Identifique a raiz, branch e mudanças locais. Inspecione manifests, módulos, contratos, banco, testes e comandos atuais. Em um projeto novo, registre apenas o que já existe e mantenha o restante como planejado.

• Projeto único: uma aplicação ou serviço com um conjunto principal de checks.
• Monorepo de um produto: múltiplos módulos físicos com contratos e governança compartilhados.
• Produtos independentes: não fundir seus escopos apenas porque estão na mesma pasta.

4. Configure o mapa do projeto

Edite PATHS.toml com nome, raiz, documentos oficiais, módulos reais, diretórios de runtime e checks reproduzíveis. O trecho abaixo é apenas parte do arquivo; preserve as outras seções do kit.

[project]
name = "MEU_PROJETO"
root = "/caminho/absoluto/do/projeto"

[modules]
app.root = "src"

[quality]
runtime_dirs = ["src"]

5. Escreva a verdade do produto

Substitua PRD.md e ESCOPO.md pelos problemas, requisitos, usuários e limites do seu produto. Concilie decisões e convenções antigas com o modelo, sem apagar conteúdo válido. Depois de substituir os placeholders, configure prd.template_mode=false.

Adapte também AGENTS.md e QUALITY_ROADMAP.md. Políticas sobre branches, SQL ou nomenclatura são escolhas do projeto; precisam fazer sentido para sua equipe. Se alterar uma convenção, registre a decisão e o impacto.

6. Reconcilie e revise as evidências

O bootstrap ajuda a descobrir itens e sugere classificações. Ele não aprova a implementação. Revise código, contratos, telas, dados e testes antes de aceitar cada estado. Só então gere a matriz e execute os checks.

python3 scripts/prd_inventory.py --bootstrap-classifications
# Revise docs/prd-classifications.json manualmente.
python3 scripts/prd_inventory.py --update
python3 scripts/prd_inventory.py --check
./check.sh

7. Faça uma primeira entrega pequena

Escolha uma mudança com critério de aceite claro. Inspecione, implemente, teste o recorte, atualize as fontes afetadas e revise o diff. A adoção está funcionando quando os documentos ajudam a tomar decisões sobre o código real.

Antes da configuração e revisão, falhas do check são esperadas. Não reduza a validação nem classifique algo como concluído só para obter um resultado verde.