Prefácio — Como navegar esta documentação

Para quem é

Para você que usa LLMs para escrever código e já sentiu a frustração de pedir "implemente o cadastro de produtos" e receber 200 linhas que quase funcionam: nomes que conflitam com o resto do projeto, uma biblioteca que o time abandonou, validações esquecidas, 80% entregue e declarado como 100%.

Você sabe programar. Conhece Git, testes e revisão de código. O que você não precisa saber de antemão é o agent-spec — vamos construí-lo do zero, peça por peça, com o porquê de cada escolha.

O que você vai saber fazer ao final

Explicar a dor

Por que ambiguidade destrói o output de uma LLM — e como spec antes de código ataca isso.

Escolher o caminho certo

Conversa, TaskCard, miniSpec ou SDD para qualquer demanda, com sinais objetivos.

Gerar artefatos

Os artefatos de especificação corretos para o caminho escolhido.

Rodar a pipeline

Interpretar os vereditos dos dois gates de qualidade.

Aplicar débito-controlado

Fechar o ciclo da dívida técnica sem acumular.

Decidir o que vira ADR

Manter conformidade arquitetural.

Diagnosticar a pipeline

Saber o que fazer quando ela trava.

As três trilhas de leitura

💡 Dica

Escolha sua trilha:

Trilha rápida (~1h) — Prefácio → Capítulo 0 → Parte II (passo a passo) → Apêndice D. Você sai sabendo operar o básico.

Trilha completa (onboarding — capacitação inicial) — leia linear, do Prefácio aos Apêndices. É o caminho desenhado para aprender de verdade.

Trilha de referência — use a busca ou a área 🔧 Referência da sidebar; depois do Capítulo 0, cada capítulo é autocontido.

Convenções e callouts

Ao longo da documentação, blocos destacados sinalizam o tipo de informação:

📝 Nota

Contexto que ajuda, mas não trava o fluxo principal.

💡 Dica

Atalho prático ou recomendação operacional.

⚠️ Armadilha comum

Um erro frequente que custa caro. Preste atenção nestes — quase todos vêm de casos reais.

🔎 Aprofundamento

Detalhe para quem quer o fundo do assunto. Pode pular na primeira leitura sem prejuízo.

🚫 Regra

Regra inegociável — quebrar tem consequência operacional.

Outras convenções

• Comandos de skill aparecem como /nome-da-skill (ex.: /agent-spec-sdd-generate-prd).
• Caminhos de arquivo em monospace (ex.: docs/specs/features/...).
• Siglas recorrentes: US = User Story, CA = Critério de Aceitação, CT = Caso de Teste, ADR = Architecture Decision Record, PRD = Product Requirements Document. Todas reaparecem no Glossário (Apêndice E).
• Cada parte termina com exercícios de fixação; o gabarito está no Apêndice F.

Sumário

• Capítulo 0 — O framework em 5 minutos
• Parte I — Por que especificar antes de codar
• Parte II — Seu primeiro fluxo, do início ao fim
• Parte III — Escolhendo o caminho certo (em migração — consulte /agent-spec-completo)
• Parte IV — A pipeline e os dois gates (em migração)
• Parte V — A política débito-controlado (em migração)
• Parte VI — Qualidade de testes (em migração)
• Parte VII — ADRs: a memória das decisões (em migração)
• Parte VIII — Observabilidade, memória e estado (em migração)
• Apêndices — referência, glossário e gabarito (em migração)

📝 Nota sobre a migração

A documentação está sendo reorganizada em dois caminhos coexistentes: a espinha narrativa (Prefácio → Capítulos → Apêndices) e a 🔧 Referência técnica (consulta). Partes ainda em migração permanecem disponíveis na versão consolidada em uma página.

📚 Aprofundamento na Referência

• Skills — visão geral — catálogo completo de todas as skills do framework.
• Pipeline — visão geral — anatomia da execução: orquestradores, executores e os dois gates.
• Agents — visão geral — os subagentes de QA, Tech Review e geração de testes.
• Conceitos — visão geral — fundamentos do desenvolvimento spec-driven.