SpecGuard - plugin CLI/Codex que verifica a spec antes da codificação com IA

Olá. Estou criando uma ferramenta open source chamada SpecGuard.

Ao usar ferramentas de codificação com IA como Codex e Claude Code, a velocidade de implementação de fato fica mais rápida. Mas, depois de usar algumas vezes de forma repetida, percebi que o problema com que eu realmente esbarrava com frequência estava menos em “a IA não consegue escrever código” e mais em “a própria spec passada para a IA está incompleta”.

Quando há falhas na spec, a IA implementa tentando adivinhar por conta própria essas lacunas. No começo parece plausível, mas, à medida que o desenvolvimento avança, os problemas a seguir crescem.

• A qualidade e a estrutura do código vão se deteriorando aos poucos.
• A spec e o código vão deixando de bater cada vez mais.
• Mais tarde, fica difícil distinguir se o código está errado, se a spec ficou desatualizada ou se os requisitos iniciais eram ambíguos.

Por isso, achei que só fazer code review depois da implementação não era suficiente. Antes que uma spec com defeitos fosse passada diretamente para o agente de implementação, era preciso uma etapa que primeiro revelasse as próprias lacunas da spec.

SpecGuard é um plugin CLI/Codex criado para reduzir esse problema. Não é uma ferramenta que inspeciona o resultado depois que o código é gerado, e sim uma ferramenta que verifica primeiro a spec antes de delegar a implementação para a IA.

O fluxo básico que imaginei é este.

1. Uma pessoa escreve a spec do produto.
2. Verifica a spec com o SpecGuard.
3. Se der NOT_READY, reforça a spec.
4. Quando estiver READY, passa para um agente de implementação como Codex/Claude Code.

O SpecGuard procura principalmente por este tipo de lacuna.

• Limites de autenticação/permissão pouco claros
• Falta do escopo de ownership de tenant/user
• Ausência de tratamento para idempotency, replay e race condition
• Regras ambíguas de expiração/revogação/transição de estado
• Ausência de políticas para efeitos colaterais externos, webhook e retry de background job
• Requisitos que confiam apenas na validação do cliente

Os resultados se dividem em três grandes categorias.

• READY: pode ser passada ao agente de implementação
• READY_WITH_WARNINGS: pode ser passada, mas há pontos de atenção
• NOT_READY: há problemas Critical/Major, então é preciso reforçar a spec

O caminho padrão é a inspeção heurística com --no-llm. Isso porque, em CI ou PR Review, considero importante que o resultado seja rápido e reproduzível. Também é possível acoplar uma revisão detalhada baseada na OpenAI Platform ou no Codex, mas por enquanto isso fica como um caminho auxiliar opcional para quando se quiser olhar mais a fundo.

O que foi adicionado no v0.4.0

Nesta v0.4.0, adicionei um MVP de plugin para o app Codex.

pip install spec-guard  
specguard --help  
codex plugin marketplace add KoreaNirsa/spec-guard --ref main  

Se você selecionar a fonte SpecGuard Plugins no app Codex e instalar o plugin SpecGuard, poderá solicitar a execução do SpecGuard dentro do Codex. Por exemplo, depois de criar uma spec de exemplo

specguard example copy specs/your-feature-name --force  

No Codex, abra a pasta correspondente e faça um pedido assim.

1. @SpecGuard execute o SpecGuard para specs/your-feature-name.  
2. @SpecGuard execute o SpecGuard para o pacote de spec specs/your-feature-name e resuma o status READY/NOT_READY e os principais findings.  
3. @SpecGuard execute o SpecGuard para specs/your-feature-name. Prossiga com a inspeção heurística padrão e resuma o status do resultado e o que fazer em seguida.  

O plugin não reimplementa o engine do SpecGuard. Ele chama o CLI specguard existente, lê o resultado gerado e resume o estado atual e a próxima ação.

A ideia é que, quando o SpecGuard gerar um estado READY, seja criado um documento de handoff que possa ser passado ao agente de implementação, e então o Codex comece a implementação em seguida.

Também há suporte a PR Review

Também forneço um workflow de PR Review do SpecGuard baseado em GitHub Actions.

O fluxo é executar o SpecGuard Review quando o pacote de spec muda em um PR e deixar o resultado registrado no PR. Essa funcionalidade é executada chamando a OpenAI.

O objetivo não é “review de código feito por IA”, mas sim “review da entrada da spec antes de passá-la para a IA”.

Pode ser útil quando o time quiser estabelecer regras como estas.

• Não passar specs com NOT_READY para implementação
• Expor findings Critical/Major primeiro no PR
• Gerenciar primeiro a qualidade da entrada de requisitos, e não do resultado da implementação

A instalação pode ser feita no CLI com specguard actions install-pr-review ou pedindo ao Codex: @specguard configure o workflow de SpecGuard PR Review.

No entanto, como ainda é um recurso experimental, não há suporte para configuração automatizada, então é preciso definir manualmente no GitHub Secret da seguinte forma.

SPECGUARD_OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxx  
SPECGUARD_PR_REVIEW_MODEL=gpt-5.4-nano  
SPECGUARD_REVIEW_SPEC_PATHS=specs/your-feature-name  

Estado atual e limitações

Ainda está em uma versão inicial, então não é uma ferramenta capaz de avaliar perfeitamente todas as specs.

Ainda assim, se você vem enfrentando o problema de “a implementação se desvia porque a spec é fraca” ao usar codificação com IA, acho que pode servir como uma proteção para filtrar isso uma vez antes da implementação.

Quero receber feedback. Em especial, tenho curiosidade sobre os pontos abaixo.

• Em que tipos de spec isso funciona bem
• Quais findings estão exagerados ou insuficientes
• Se o fluxo do plugin do Codex é realmente útil na prática
• Se forçar isso via PR Review combina com o workflow do time

No momento, ainda está antes da versão beta, em um estágio em que o desenvolvimento mal começou, mas quero transformá-lo em um projeto que possa ser usado de forma sólida no trabalho real no futuro.

Issues/PRs de quem tiver interesse também são bem-vindos. No momento, as issues e PRs do repositório são gerenciadas principalmente em inglês, mas tudo bem escrever em coreano também.

GitHub : https://github.com/KoreaNirsa/spec-guard

[veltrix]

Você pode conferir mais detalhes sobre este projeto em https://nirsa.tistory.com/487.