Specification no Kavor: pense com cuidado uma vez, implemente melhor

Uma Specification transforma intenção em um contrato durável que humanos e CodingAgents conseguem ler, discutir, implementar e revisar sem depender da memória de uma única conversa.

Ela pode definir uma arquitetura, integração, modelagem de domínio, feature, módulo ou um conjunto delimitado de correções. O tamanho varia; a responsabilidade permanece a mesma: explicar o que precisa ser verdadeiro antes de o trabalho ser tratado como concluído.

Ver imagem em tamanho original

A fonte da verdade é um arquivo

O conteúdo de uma Specification vive em Markdown dentro do seu Workspace. O arquivo é seu: pode ser aberto no Kavor, editado por outras ferramentas, versionado no Git e lido diretamente por CodingAgents.

O Kavor mantém apenas metadados operacionais ao redor dessa fonte, como identidade, status e outputs. O frontmatter preserva a identidade que permite acompanhar uma Specification quando seu arquivo é movido ou renomeado.

Não edite manualmente os campos que o Kavor controla no frontmatter. Escreva o contrato no corpo; deixe identidade e lifecycle serem atualizados pelas operações do produto.

Escreva sozinho ou com um CodingAgent

Você pode começar manualmente ou coescrever com um CodingAgent. Para um assunto difícil, vale usar uma sessão voltada a planejamento e investir mais capacidade de raciocínio antes de implementar.

Um bom ponto de partida é:

Entreviste-me sobre o assunto X para escrevermos a Specification Y. Separe fatos verificados, decisões, premissas, non-goals, cenários de falha e critérios de aceite observáveis. Não trate o documento como Ready enquanto existirem decisões que mudariam a solução.

Pensar melhor aqui pode reduzir retrabalho, contexto desperdiçado e implementação ambígua. Não é garantia de menor custo: uma Specification ruim continua ruim mesmo quando é longa ou foi escrita por um modelo caro.

Um contrato mínimo que consegue orientar trabalho

Uma Specification útil normalmente contém:

• contexto e problema atual;
• objetivo e definição de sucesso;
• non-goals que limitam o escopo;
• decisões e restrições;
• abordagem pretendida quando ela já estiver decidida;
• critérios de aceite observáveis;
• cenários de falha e riscos relevantes;
• perguntas ainda abertas;
• referências para código, ADRs, issues ou outras Specifications.

O documento não precisa seguir um ritual fixo quando o Workspace já possui uma convenção melhor. Precisa, porém, distinguir decisão de hipótese e permitir que outra pessoa avalie o resultado sem reconstruir toda a conversa original.

Lifecycle é orientação, não decoração

O Kavor usa cinco estados:

O status é deliberadamente advisory. O Kavor não transforma checkboxes de Markdown em um sistema proprietário nem prova sozinho que todos os critérios foram satisfeitos. Tratar como Done continua exigindo evidência e julgamento.

Uma prática forte é separar autoria, implementação e revisão. O CodingAgent que ajudou a escrever pode esclarecer o contrato; outro implementa; um Reviewer independente compara resultado e critérios.

Organize mais de uma Specification root

Um Workspace pode manter Specifications em mais de uma pasta. Isso ajuda quando um único projeto já separa decisões por produto, engenharia, operações ou módulos — ou quando uma raiz única se tornou um depósito difícil de navegar.

Abra Workspace Settings e use Specification roots para adicionar, remover ou reordenar as pastas. As roots são:

• relativas ao diretório do Workspace;
• ordenadas;
• únicas e não sobrepostas;
• limitadas a 32 por Workspace.

A primeira root é a Primary e recebe novas Specifications por padrão. Reordenar muda esse destino padrão; não move arquivos existentes. Remover uma root também não apaga seus arquivos. As Specifications fora das roots configuradas deixam de participar da listagem ativa e podem voltar quando a root for adicionada novamente.

Quando mais de uma root existe, o painel de Specifications agrupa primeiro por root e depois pelas pastas reais do filesystem. O Canvas não cria uma taxonomia paralela: a organização continua sendo a estrutura de arquivos que você já possui.

Um desenho simples de roots

docs/         decisões e contratos gerais do produto
specs/        features e integrações em execução
marketing/    campanhas e experiências editoriais
operations/   manutenção e mudanças operacionais

Não crie roots apenas para reduzir a quantidade de itens em uma lista. Use-as quando cada pasta possui uma fronteira durável e compreensível para humanos e agentes.

O que a Specification ganha no grafo

Uma Specification aceita duas Connections diretas:

• Specification + CodingAgent coloca o contrato ao alcance do agente e permite lifecycle e outputs. A Connection pode receber specification_read_only.
• Specification + Terminal exporta o caminho absoluto canônico do Markdown por uma variável de ambiente configurada na Connection.

Outros CodingAgents no mesmo componente também podem alcançar a Specification por caminhos válidos. A Connection direta não precisa ser repetida para cada participante, a menos que melhore a leitura da topologia ou precise de um Guardrail específico para aquele par.

Três usos que justificam uma Specification

Fundação arquitetural

Registre invariantes, dependências permitidas, limites de segurança, estratégia de migração e critérios verificáveis. O documento passa a orientar features posteriores sem exigir que cada agente redescubra a fundação.

Feature com implementação e revisão independentes

Um Spec Writer esgota decisões e move o contrato para Ready. Um Implementer trabalha a partir dele. Um Reviewer verifica comportamento, falhas e evidências. Outputs mantêm commits ou outros resultados ligados ao trabalho.

Série delimitada de correções

Quando vários defeitos compartilham uma causa ou uma superfície, uma Specification pode definir o comportamento esperado, o conjunto exato de correções e os testes de regressão. Se o documento vira uma lista infinita de bugs sem uma fronteira comum, ele perdeu o papel de contrato.

Um grafo prático

Spec Writer — Specification — Implementer — Reviewer
                        │
                     Terminal

O Spec Writer registra decisões. O Implementer executa somente o contrato Ready. O Reviewer compara resultado e critérios. O Terminal fornece evidências. A decisão de tratar o trabalho como Done continua humana.

O que evitar

• Sair de Draft porque o texto parece longo, sem resolver decisões que mudam a solução.
• Colocar análise, Specification, implementação e revisão na mesma sessão por conveniência.
• Escrever critérios como “funciona corretamente” ou “possui boa performance” sem resultado observável.
• Alterar o frontmatter controlado pelo Kavor como se fosse conteúdo comum.
• Tratar status como prova automática de qualidade ou conclusão.
• Criar roots sobrepostas ou usar várias roots sem uma fronteira editorial durável.
• Guardar a única decisão relevante numa conversa ou mensagem que o próximo participante não encontrará.

Antes de mover para Ready

Confirme:

• problema, objetivo e non-goals estão claros?
• fatos, decisões e hipóteses estão separados?
• cenários de falha relevantes foram tratados?
• critérios de aceite podem ser verificados?
• o Implementer saberá onde pode e onde não pode alterar?
• o Reviewer conseguirá avaliar o resultado sem herdar a linha de raciocínio do autor?
• perguntas que mudariam a solução foram respondidas?

Uma Specification boa não tenta prever cada linha de código. Ela remove ambiguidade suficiente para que execução e revisão possam ser independentes, verificáveis e recuperáveis.

Continue em Como fechar seu primeiro loop, escolha os participantes em CodingAgents e papéis ou revise a matriz de Connections.