specd: Instructions file for Claude Code

specd — instruções para agentes

CLI de spec-driven development cujo diferencial é detecção de drift por âncoras: cada requisito declara onde é realizado no código, e o gate reprova quando a âncora deixa de resolver.

Pacote npm @jnerytech/specd, binário specd, TypeScript. Repositório público em github.com/jnerytech/specd. Para rodar do clone: npm install && npm run build, depois node dist/cli.js <comando> — ou npm link uma vez, e aí specd funciona como nos exemplos.

Princípios invioláveis

Estes não são preferências. Violá-los destrói a proposta de valor do produto. O porquê de cada um — assimetrias, instâncias reais, modos de falha — está em docs/principios.md; leia antes de propor mudança em qualquer princípio.

• no-llm-in-decision-path — A CLI nunca chama LLM no caminho de decisão. Nenhum módulo alcançável a partir de verify() importa cliente de LLM; há teste de arquitetura. Determinismo protege o exit code, e a mesma disciplina se estende à escrita destrutiva em sistema de terceiro, que é irreversível.
• single-gate — Um único gate. Só specd verify retorna 1 por reprovação de qualidade. Outros comandos retornam não-zero apenas por falha operacional.
• gate-no-network — O gate nunca acessa a rede. explore e sync acessam; verify não. Há teste de arquitetura.
• no-guessing-on-conflict — Nunca adivinhar em conflito. Âncora ambígua, conflito de merge e estado inconsistente saem com erro e diagnóstico. Jamais auto-resolução.
• config-only-on-divergence — Botão de configuração só existe se dois clientes reais divergirem.
• memory-is-ephemeral — Memória é efêmera; verdade durável vai para spec ou ADR.
• anchor-necessary-not-sufficient — Âncora é necessária, nunca suficiente. Ela responde onde, não se nem quando. Nunca aponta para implementação parcial: âncora honestamente pendurada é preferível a resolvê-la para um stub.
• absence-is-not-compliance — Ausência de dado não é conformidade. Verificou-e-certo, verificou-e-errado e não-consegui-verificar são três resultados; o terceiro nunca é verde. Vale nas duas direções: resposta de sucesso de sistema externo não é prova de que a escrita aconteceu — quem confirma é a releitura.
• costly-ops-are-not-silent — Operação que custa alguma coisa não acontece em silêncio. Escrita destrutiva ou fora do repositório ou para e nomeia a escolha, ou deixa o resultado onde a revisão passa antes de virar história. O custo de uma operação é visível no momento em que é pago.