Lucas

Posted on Jul 6 • Originally published at apidog.com

Por Que Desenvolvemos o Novo Apidog CLI + SKILL

Esta é uma série em 10 partes sobre como a Apidog desenvolveu o Apidog CLI, uma ferramenta de linha de comando para testes de API e gerenciamento do ciclo de vida de APIs. Leia em ordem ou pule para o tópico que estiver implementando agora:

Experimente o Apidog hoje

Parte	Título	Foco
1	Construímos 126 Ferramentas MCP. Mas Não É a Melhor Solução para Agentes	Descoberta do problema
2	Por Que Desenvolvemos o Novo Apidog CLI	Desenvolvimento da arquitetura
3	A Regra de Ouro: CLI Produz Fatos, Modelo Age com Base nos Fatos	Filosofia central
4	`agentHints`: Ensinando CLIs a Falar com Agentes	Saída estruturada
5	SKILL: Entregando Experiência Operacional como Código	Experiência operacional
6	Os Números Não Mentem: 30% Menos Chamadas de Ferramentas, 25% Menos Tokens	Resultados quantitativos
7	Do PRD ao Ciclo de Teste: Um Fluxo de Trabalho Completo de Agente com Apidog CLI	Tutorial prático
8	Por Que a Compatibilidade CI/CD É Inegociável para Ferramentas de Agente	Perspectiva DevOps
9	Ramificação de IA: Mudanças de Projeto Mais Seguras com Agentes de IA	Camada de segurança
10	Spec-First Foi Ontem. Bem-vindo ao Skill-First.	Visão e futuro

Construímos CLI + SKILL para lidar com o que o MCP não otimiza: fluxos de trabalho complexos com validação, execução estruturada e verificação.

O MCP continua útil

Antes de falar sobre CLI + SKILL, vale deixar claro: o Apidog MCP continua disponível e mantido.

Use MCP quando você precisar de conexões de ferramentas padronizadas seguindo o protocolo, especialmente em casos como:

operações simples e bem definidas;
usuários que já trabalham com fluxos baseados em MCP;
integração com clientes compatíveis com MCP.

O CLI + SKILL não substitui o MCP. Ele complementa o MCP.

A diferença prática está no tipo de trabalho. O MCP é forte para conectar ferramentas. Já fluxos de P&D mais complexos — com múltiplas etapas, validação, leitura de estado e verificação — se beneficiam de processos de engenharia executáveis.

Tipo de tarefa	Abordagem recomendada
Chamada simples de ferramenta, como obter um endpoint	MCP ou CLI
Fluxo multi-etapas, como criar teste, validar e executar	CLI + SKILL
Integração CI/CD	CLI
Integração com ecossistema MCP	MCP

O antigo CLI: executar testes no final

O Apidog CLI já era usado como ponto de entrada de linha de comando para executar testes de API:

apidog run --project <projectId> --test-scenario <scenarioId> --environment <environmentId>

Esse uso continua importante. Em automação, equipes precisam conseguir:

executar testes de API pelo terminal;
gerar relatórios em pipelines CI;
manter quality gates em fluxos de entrega.

O ponto é que o antigo CLI era focado principalmente na execução de testes. Ele aparecia no final do ciclo:

Design → Documentar → Mock → Depurar → Testar → [CLI executa testes]

Ou seja: o CLI entrava depois que a maior parte do trabalho já tinha sido feita.

O novo requisito: agentes precisam operar o ciclo inteiro

O desenvolvimento de APIs está mudando. Agentes de IA agora participam de etapas como:

Etapa	Atividade do agente
Design de API	Gerar definições de endpoint a partir do PRD
Geração de testes	Criar casos de teste a partir de especificações de API
Depuração	Analisar falhas e sugerir correções
Migração	Mover APIs entre projetos
Manutenção	Atualizar testes quando APIs mudam

Para esses fluxos, o CLI não pode ser apenas o executor final. Ele precisa permitir que agentes façam operações estáveis e verificáveis, como:

ler ativos de API, como endpoints, esquemas e ambientes;
criar ou atualizar ativos de teste;
validar mudanças estruturadas antes de gravar;
gravar mudanças no projeto;
verificar o resultado.

Expansão sistemática, não comandos isolados

O novo Apidog CLI não é apenas o antigo CLI com alguns comandos extras.

Ele introduz capacidades centrais do Apidog no terminal para servir como camada de fluxo de trabalho para:

desenvolvedores;
scripts;
pipelines CI/CD;
agentes de IA.

Antes	Agora
“Como executo testes Apidog externamente?”	“Como agentes de IA podem usar o Apidog de forma estável?”

Essa mudança altera a fronteira arquitetural: o CLI deixa de ser apenas executor e passa a participar do ciclo de desenvolvimento.

MCP vs CLI + SKILL: cadeia de execução

Para entender a diferença, compare a cadeia típica de execução em fluxos complexos.

Rota MCP: boa para conectar ferramentas

Inicializar sessão MCP
        ↓
Carregar lista de ferramentas + descrições
        ↓
Agente seleciona ferramenta
        ↓
Buscar mais ferramentas, como listOpenApiEndpoints
        ↓
Obter esquema, como getOpenApiDetails
        ↓
Executar chamada HTTP, como executeOpenApi

Força do MCP: protocolo padronizado para conectar ferramentas a agentes.

Onde a complexidade fica: no contexto do modelo e na seleção da ferramenta. O agente precisa entender:

lista de ferramentas;
descrições;
esquemas de entrada;
sequência de chamadas;
estruturas de retorno.

Isso funciona bem quando a tarefa tem mapeamento direto para uma ferramenta. Fica mais difícil quando o agente precisa orquestrar várias ferramentas, aplicar semântica de produto e lidar com validação.

Rota CLI + SKILL: melhor para fluxos complexos

SKILL identifica o tipo de tarefa
        ↓
CLI executa comandos semânticos de produto
        ↓
cli-schema valida a estrutura
        ↓
agentHints sugere o próximo passo
        ↓
Loop de verificação com feedback ou apidog run

Força do CLI + SKILL: distribuir a complexidade para o sistema de engenharia.

Na prática:

SKILL orienta metodologia e fluxo de trabalho;
CLI executa comandos alinhados ao domínio do produto;
cli-schema valida antes da gravação;
agentHints orienta o próximo passo após a execução.

Esse modelo funciona melhor para fluxos multi-etapas, operações com validação forte e testes conduzidos por agentes.

A diferença central: onde a complexidade reside

Abordagem	Onde a complexidade reside	Melhor para
MCP	Contexto do modelo + seleção de ferramenta	Chamadas simples e ecossistema MCP
CLI + SKILL	Sistema de engenharia: SKILL, CLI, validação e dicas	Fluxos complexos e multi-etapas

No MCP, o modelo precisa carregar e decidir:

qual ferramenta usar;
o que a descrição da ferramenta significa;
quais campos são obrigatórios;
qual sequência seguir;
como interpretar a estrutura de retorno.

No CLI + SKILL, o sistema de engenharia assume mais responsabilidade:

SKILL identifica o tipo de tarefa;
CLI executa o comando correto;
cli-schema valida a estrutura;
agentHints sugere o próximo passo.

Isso reduz a carga de raciocínio do modelo em fluxos que exigem leitura, validação e verificação.

Exemplo prático de fluxo CLI + SKILL

Um fluxo básico pode seguir esta sequência:

# Etapa 1: ler fatos do projeto
apidog endpoint get <endpointId> --project <projectId>

# Etapa 2: validar a estrutura antes de escrever
apidog cli-schema validate test-case-create --file ./test-case-create.json

# Etapa 3: executar verificação
apidog run --project <projectId> --out-dir ./apidog-reports

Esses comandos representam três ações de engenharia:

Comando	Ação
`endpoint get`	Ler fatos do projeto
`cli-schema validate`	Validar estrutura antes de escrever
`apidog run`	Executar verificação

O padrão recomendado é:

Ler fatos → Gerar mudança → Validar → Escrever → Verificar

Esse padrão é mais seguro para agentes porque evita que eles gravem mudanças sem antes confirmar o estado atual e validar a estrutura.

Caminho do agente em fluxos complexos

Com MCP

Selecionar ferramentas → Entender esquemas → Orquestrar sequência → Lidar com erros

O agente precisa:

escolher ferramentas apropriadas;
interpretar descrições e esquemas;
montar a sequência correta;
lidar com erros e retentativas.

Isso pode funcionar, mas exige raciocínio do modelo em cada ponto de decisão.

Com CLI + SKILL

Ler fatos → Gerar mudanças → Validar estrutura → Escrever → Executar verificação

O agente segue uma sequência mais operacional:

lê os fatos existentes;
gera mudanças com base nesses fatos;
valida a estrutura localmente com cli-schema;
grava no projeto;
executa verificação com apidog run.

Ambos os caminhos podem concluir a tarefa. O CLI + SKILL reduz a complexidade na fase de contexto do modelo.

O que o CLI agora cobre

Com a atualização, o CLI passa a cobrir mais recursos centrais do Apidog:

Recurso	Capacidade do CLI
Projetos e metadados	Listar e ler
APIs e definições de API	Obter, criar e atualizar
Ambientes e variáveis	Listar e gerenciar
Casos de teste	Criar, atualizar e validar
Cenários de teste	Criar, atualizar, importar etapas e obter detalhes
Conjuntos de testes	Gerenciar
Relatórios	Gerar a partir de `apidog run`
Importação/exportação	Exportar projeto e importar arquivos

Isso muda o papel do Apidog CLI.

Ele não é apenas uma forma de executar testes depois que tudo já foi feito. Agora ele pode entrar mais cedo no ciclo, quando um agente precisa:

entender o projeto;
gerar ou atualizar ativos de teste;
validar alterações;
executar verificação.

Resumo da arquitetura

Dimensão	MCP	CLI + SKILL
Força principal	Conexão de ferramentas	Execução de fluxo de trabalho
Local da complexidade	Contexto do modelo	Sistema de engenharia
Caminho do agente em tarefas complexas	Selecionar, orquestrar, retentar	Ler, validar, escrever, verificar
Cobertura	126 ferramentas geradas + ferramentas nativas	Gerenciamento de recursos + validação
Melhor adequação	Operações simples e ecossistema MCP	Fluxos complexos e CI/CD

Ambos estão disponíveis. Escolha com base na tarefa.

Como escolher na prática

Use MCP quando:

a operação for simples;
a ferramenta tiver entrada e saída claras;
você estiver integrando com um cliente compatível com MCP;
o fluxo não exigir muitas validações intermediárias.

Use CLI + SKILL quando:

o fluxo tiver múltiplas etapas;
for necessário ler estado antes de modificar;
mudanças precisarem ser validadas antes da gravação;
você quiser executar verificação no final;
o fluxo precisar rodar também em CI/CD.

Uma regra simples:

Se a tarefa é uma chamada isolada, MCP pode bastar.
Se a tarefa é um processo, prefira CLI + SKILL.

O que vem a seguir

Agora que estabelecemos como CLI + SKILL complementa o MCP, a próxima pergunta é:

Qual princípio torna o CLI + SKILL eficaz em fluxos complexos?

Na Parte 3, A Regra de Ouro: CLI Produz Fatos, Modelo Age com Base nos Fatos, vamos explorar a filosofia de design por trás do CLI + SKILL — começando com cli-schema validate, a porta de qualidade que captura erros antes que eles se tornem gravações falhas.

Principais conclusões

O MCP continua disponível e útil para operações simples e integração com o ecossistema MCP.
O CLI + SKILL complementa o MCP em fluxos complexos com validação.
A diferença central está em onde a complexidade reside: no contexto do modelo ou no sistema de engenharia.
O CLI + SKILL reduz a carga de raciocínio do modelo com validação, orientação e verificação.
O CLI agora cobre projetos, APIs, ambientes, casos de teste, cenários e outros recursos.
Escolha MCP ou CLI + SKILL com base na complexidade da tarefa.

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

DEV Community