A Regra de Ouro: CLI Produz Fatos, Modelo Age nos Fatos

Esta é uma série de 10 partes que compartilha como o Apidog desenvolveu o Apidog CLI, uma ferramenta de linha de comando para teste e gerenciamento do ciclo de vida de APIs. Leia em ordem ou pule para qualquer post que lhe interesse:

Não faça o modelo memorizar todas as regras — deixe as regras serem executadas nos lugares certos. cli-schema validate transforma o Schema de conhecimento em um portão de qualidade.

O Princípio Fundamental: Deixe as Regras Serem Executadas nos Lugares Certos.

Destilamos um princípio fundamental de nossa experiência:

Não faça o modelo memorizar todas as regras. Deixe as regras serem executadas nos lugares certos.

Isso é semelhante a uma lição da avaliação de Agentes:

No Apidog CLI + SKILL:

Deixe o CLI validar a estrutura. Deixe os Agentes gerarem o conteúdo.

O Problema com a Memória do Modelo

Quando um Agente de IA ajuda a criar ou atualizar recursos do Apidog, a parte arriscada não é apenas gerar conteúdo.

A parte arriscada é escrever conteúdo gerado em um projeto real sem estrutura ou verificação suficientes.

Os recursos do Apidog são estruturados. Considere o que um caso de teste ou cenário de teste inclui:

Se um Agente adivinhar a estrutura:

• Nome de campo errado → Falha na escrita
• Valor enum inválido → Rejeição do servidor
• Campo obrigatório ausente → Recurso incompleto
• Tipo errado → Problemas de exibição na UI
• Aninhamento incorreto → Testes não se comportam como esperado

cli-schema validate: O Portão de Qualidade

A incorporação mais direta do nosso princípio é cli-schema validate.

apidog cli-schema validate test-scenario-update --file ./scenario-update.json

Quando um Agente deseja escrever ou atualizar um cenário de teste, ter a IA gerando estruturas de etapas complexas é muito propenso a erros.

O comando validate:

• Confirma nomes de campos
• Verifica a validade estrutural
• Verifica a eficácia dos valores enum
• Valida restrições de tipo

Tudo antes de iniciar a requisição de escrita.

Erros Comuns que o cli-schema Captura

Aqui estão exemplos reais de erros que os Agentes comumente cometem – e que o cli-schema validate captura:

Isso não é teórico. Nós os descobrimos através de interações reais com Agentes.

Cada erro causaria:

• Uma requisição de escrita falha
• Uma resposta de erro da API
• Confusão do Agente sobre o que deu errado
• Múltiplas tentativas de repetição
• Desperdício de tokens em chamadas repetidas

Com cli-schema validate, esses erros são capturados localmente, antes da chamada de rede.

A Filosofia de Design

Vamos considerar as alternativas:

Alternativa 1: Escrever Regras no Prompt

Se escrevêssemos todas as regras de campo no prompt do Agente:

• Cada nome de campo documentado
• Cada valor enum listado
• Cada restrição de tipo explicada
• Cada estrutura aninhada descrita

Resultado: Enorme carga de contexto.

Um esquema de cenário de teste abrangente poderia facilmente exigir mais de 5.000 tokens de descrição. Esse é um contexto que o modelo deve carregar para cada tarefa, mesmo quando a maioria das regras não é relevante.

Alternativa 2: Confiar na Memória do Modelo

Se confiarmos no modelo para "saber" a estrutura correta:

• Modelo treinado em alguns padrões de API
• Mas não especificamente nos schemas do Apidog
• Nomes de campos variam entre produtos
• Valores enum são específicos do produto

Resultado: Altas taxas de erro.

O modelo não tem memória perfeita das convenções específicas do Apidog. Ele vai adivinhar — e os palpites estarão errados.

Abordagem Melhor: Validar Localmente

Deixe o Agente gerar rascunhos. Deixe o CLI executar a validação antes de escrever.

# O Agente gera JSON
# (O Agente não precisa memorizar todas as regras)

# O CLI valida
apidog cli-schema validate test-case-create --file ./test-case-create.json

# O CLI exibe erros específicos, se houver
# O Agente ajusta com base nos erros

# Apenas escritas válidas prosseguem
apidog test-case create --project <projectId> --file ./test-case-create.json

Transformação de Schema

cli-schema validate transforma o que Schema significa:

Os problemas não são consumidos em requisições de rede de idas e vindas sem sentido.

As verificações de qualidade são concluídas por meio de comandos locais.

Exemplo Prático

Vamos analisar um fluxo de trabalho real:

# O Agente lê o endpoint
apidog endpoint get <endpointId> --project <projectId>

# O Agente gera o JSON do caso de teste
# (Cria ./test-case-create.json)

# Valida antes de escrever
apidog cli-schema validate test-case-create --file ./test-case-create.json

Se a validação passar:

apidog test-case create --project <projectId> --file ./test-case-create.json

Se a validação falhar:

Error: Field "assertions[0].comparator" has invalid value "contains"
Valid values: equal, not_equal, greater, less, include, not_include, exists, not_exists

Error: Field "extractors[0].type" has invalid value "global"
Valid values: globals, environment, collection, local

Suggestion: Fix these fields and re-validate before writing.

O Agente:

1. Lê os erros específicos
2. Compreende exatamente o que está errado
3. Ajusta o arquivo JSON
4. Reexecuta a validação
5. Prossegue apenas quando válido

Sem escritas falhas. Sem tentativas confusas. Sem tokens desperdiçados.

A Lição Mais Ampla

Este princípio se estende além da validação.

Regras determinísticas → Sistema de engenharia

Julgamento semântico → Agente

O Que Vem a Seguir

Agora que estabelecemos o princípio de validação, a próxima pergunta é:

Após a validação, como o CLI guia o Agente para o próximo passo?

Na Parte 4, agentHints: Ensinando CLIs a Falar com Agentes, exploraremos como a saída estruturada com sugestões de próximos passos transforma o CLI de um executor de comandos em um navegador de fluxo de trabalho.

Principais Conclusões

• Princípio fundamental: as regras pertencem à execução, não ao contexto
• cli-schema validate é o portão de qualidade antes da escrita
• Erros comuns: nomes de campos errados, enums inválidos, tipos errados
• A validação captura erros localmente, economizando rodadas de rede
• O Schema se transforma de "conhecimento a ser memorizado" em "portão a ser passado"
• Regras determinísticas → engenharia; julgamento semântico → Agente

Baixe o Apidog para projetar, simular, testar e documentar APIs em um único workspace. Saiba mais sobre o Apidog CLI para teste de API por linha de comando, automação CI e fluxos de trabalho de Agentes de IA.