Esta é uma série de 10 partes que compartilha como o Apidog desenvolveu o Apidog CLI, uma ferramenta de linha de comando para testes de API e gerenciamento do ciclo de vida de API. Leia em ordem ou pule para qualquer post que interesse você:
| Título | Foco | |
|---|---|---|
| 1 | Construímos 126 Ferramentas MCP. Mas Não É a Melhor Solução para Agentes | Descoberta de problemas |
| 2 | Por Que Desenvolvemos um Apidog CLI Completamente Novo | Desenvolvimento de arquitetura |
| 3 | A Regra de Ouro: CLI Produz Fatos, o Modelo Age sobre os Fatos | Filosofia central |
| 4 | agentHints: Ensinando CLIs a Conversar com Agentes |
Saída estruturada |
| 5 | SKILL: Enviando 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 Testes: Um Fluxo de Trabalho Completo de Agentes com Apidog CLI | Tutorial prático |
| 8 | Por Que a Compatibilidade CI/CD É Inegociável para Ferramentas de Agentes | Perspectiva DevOps |
| 9 | AI Branch: 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 126 Ferramentas MCP. Depois Descobrimos Que Não É a Melhor Solução para Trabalhar em Desenvolvimento de API com Agentes.
Quando MCP (Model Context Protocol) se tornou o ponto de interesse da indústria no início de 2025, a questão que cada produto de API enfrentava era simples: "Você tem MCP?"
Para o Apidog, respondemos sim. Construímos um MCP Server completo—não apenas uma simples demonstração. O cliente MCP inicializaria uma sessão, o servidor geraria um sessionId, e salvaria o estado da sessão através do Redis. Era um sistema de sessão em nível de protocolo. Dividimos as ferramentas em categorias: ferramentas nativas do projeto, ferramentas de domínio integradas, e 126 ferramentas geradas automaticamente convertidas de definições de endpoints OpenAPI.
O Apidog MCP continua funcionando e servindo usuários que precisam de integração MCP. Ele fornece conexões de ferramentas padronizadas seguindo o protocolo MCP, que é valioso para o ecossistema.
Mas quando entramos em tarefas reais envolvendo fluxos de trabalho de P&D complexos, descobrimos limitações. Quando um usuário diz "ajude-me a adicionar um teste para este endpoint e executar verificação", o Agente enfrenta um muro de ferramentas aleatórias—decidindo qual usar, em que sequência, com que validação.
Nós percebemos: O MCP se destaca em conectar ferramentas, mas tarefas complexas de P&D precisam de mais do que conexão de ferramentas—elas precisam de processos de engenharia executáveis.
Essa percepção nos levou a desenvolver o Apidog CLI como uma abordagem melhor—uma que lida melhor com fluxos de trabalho de desenvolvimento.
O que é o Apidog CLI?
O Apidog CLI é uma ferramenta de linha de comando para testes de API que permite executar cenários de teste, gerenciar documentação de API, e automatizar fluxos de trabalho de testes diretamente do seu terminal ou pipelines CI/CD. Construído especificamente para que agentes de IA gerenciem recursos de API, vai além do CLI tradicional para testes de API—fornecendo saída estruturada, validação de schemas, e orientação de próximos passos que os agentes precisam para executar fluxos de trabalho complexos com segurança. Seja você executando testes de API automatizados no GitHub Actions, gerando casos de teste de código com Claude Code, ou mantendo cenários de teste entre projetos, o Apidog CLI serve como a ponte entre agentes de IA e sua infraestrutura de testes de API.
Início Rápido: Experimente o Apidog CLI + SKILL
Se você quiser experimentar a abordagem descrita nesta série, aqui está como começar:
# Install Apidog CLI
npm install -g apidog-cli@latest
# Install companion SKILL for AI Agents
apidog skill install
# Check version (need 2.2.5+ for new capabilities)
apidog -v
# Authenticate
Ou peça ao seu Agente de IA para instalá-lo:
Read the instructions and help me install Apidog CLI:
Sua Primeira Tarefa com o Agente
Após a instalação, dê ao seu Agente uma tarefa pequena e de baixo risco:
Use Apidog CLI to help me create my first API endpoint in Apidog.
First, check my Apidog CLI setup and list the projects I can access.
Ask me which project to use. After I confirm, create a simple GET /health
endpoint named Health Check with a 200 response example. Validate any
structured input before writing, then read the endpoint back and summarize
Isso lhe dá um ponto de partida concreto: o Agente verifica a configuração, pergunta antes de escrever, cria uma pequena definição de API, valida antes de escrever, e confirma o resultado salvo.
A Arquitetura Central
| Camada | Responsabilidade |
|---|---|
| Apidog | Gerencia recursos de API e testes (docs, schemas, mocks, testes, relatórios) |
| CLI | Fornece execução determinística (read, validate, write, run) |
| SKILL | Fornece julgamento de tarefas e caminhos de operação (8 Skills complementares) |
| AI Branch | Isola mudanças para revisão humana antes do merge |
| Agents | Entendem objetivos, chamam comandos, ajustam baseado em feedback |
O Ciclo Mais Seguro para Testes Orientados por Agentes
Com o AI Branch como a camada de segurança externa, o fluxo de trabalho completo fica assim:
┌─────────────────────────────────────────────────────────────────────┐
│ AI BRANCH (Camada de Segurança) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Read Assets │────▶│ Generate │────▶│ Validate │ │
│ │ (CLI get) │ │ (Agent) │ │ (cli-schema)│ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Run Tests │◀────│ Read Back │◀────│ Write │ │
│ │ (apidog run)│ │ (CLI get) │ │ (to AI Br.) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────┐ │
│ │ Human Review & Merge │ │
│ │ (User confirms before main branch) │ │
│ └──────────────────────────────────────┘ │
Este ciclo é importante porque muitos recursos do Apidog são estruturados. Casos de teste e cenários de teste incluem dados de request, assertions, extração de variáveis, pre/post processadores, ordem de passos, e referências de ambiente. Se um Agente "chuta" a estrutura, pequenos erros causam escritas falhas, visualização incompleta, ou testes que não funcionam como esperado.
Deixe o Agente gerar, deixe o CLI validar, e deixe o AI Branch isolar mudanças até a revisão humana.
Visão Geral do Journey do Apidog CLI
Esta série documenta como desenvolvemos o Apidog CLI como uma estratégia melhor para fluxos de trabalho de P&D de API.
O Apidog MCP continua fornecendo conexões de ferramentas padronizadas—isso é valioso e mantemos. Mas para tarefas envolvendo fluxos de trabalho de múltiplos passos, gates de validação, e execução estruturada, descobrimos que CLI + SKILL oferece uma experiência melhor.
Não apenas adicionamos comandos ao CLI antigo, onde usuários executavam testes de API automáticos integrando com seu CI/CD. Introduzimos sistematicamente as capacidades core do Apidog no CLI, fazendo dele uma camada de fluxo de trabalho para desenvolvedores, scripts, e Agentes de IA.
A diferença chave é onde a complexidade vive:
- Rota MCP: Complexidade no contexto do modelo e estágio de seleção de ferramentas—ótimo para chamadas de ferramentas simples
- Rota CLI + SKILL: Complexidade distribuída no sistema de engenharia—melhor para fluxos de trabalho mais avançados
O resultado: fluxos de trabalho de Agentes mais seguros para tarefas complexas, menos chamadas de ferramentas, menos desperdício de tokens, e melhor recuperação de erros—enquanto MCP continua disponível para usuários que preferem essa abordagem.
O Mapa do Journey do Apidog CLI
┌─────────────────────────────────────────────────────────────────┐
│ THE APIDOG CLI + SKILL JOURNEY │
├─────────────────────────────────────────────────────────────────┤
│ │
│ [Problem Discovery] │
│ │ │
│ ┌───┐ │
│ │ 1 │ We Built 126 MCP Tools. Then We Found │
│ └───┘ a Better Approach for Workflows. │
│ │ │
│ ▼ │
│ [Architecture Development] │
│ ┌───┐ │
│ │ 2 │ Why We Developed a Brand-new Apidog CLI │
│ └───┘ │
│ │ │
│ ├──────────────────┬──────────────────┐ │
│ ▼ ▼ ▼ │
│ [Core Philosophy] [Technical Design] │
│ ┌───┐ ┌───┐ ┌───┐ │
│ │ 3 │ CLI Produces │ 4 │ agentHints: │ 5 │ SKILL: Shipping │
│ └───┘ Facts └───┘ Teaching └───┘ Operational │
│ │ │ CLIs │ Experience │
│ │ │ │ │
│ └──────────────┴──────────────────┘ │
│ │ │
│ ▼ │
│ [Validation & Practice] │
│ ┌───┐ ┌───┐ │
│ │ 6 │───────│ 7 │ │
│ └───┘ Numbers│ PRD to Testing │
│ │ │ Loop │
│ ▼ ▼ │
│ [Foundation] [Security Layer] │
│ ┌───┐ ┌───┐ │
│ │ 8 │───────│ 9 │ │
│ └───┘ CI/CD │ AI Branch │
│ │ │ │
│ └────────┘ │
│ │ │
│ ▼ │
│ [Vision] │
│ ┌────┐ │
│ │ 10 │ Spec-First → Skill-First │
│ └────┘ │
│ │
Navegação Rápida do Journey
Parte 1: Descoberta do Problema
O MCP fornece conexões de ferramentas padronizadas—mas para fluxos de trabalho de P&D complexos, descobrimos limitações. Agentes enfrentavam um muro de ferramentas aleatórias quando tarefas envolviam processos de múltiplos passos. Este post explora quatro desafios estruturais e por que CLI + SKILL são melhores para tarefas com fluxos de trabalho pesados.
Parte 2: Desenvolvimento de Arquitetura
2. Por Que Desenvolvemos um Apidog CLI Completamente Novo
Não abandonamos o MCP—construímos CLI + SKILL para lidar com o que o MCP não otimiza: fluxos de trabalho complexos com gates de validação e execução estruturada. Este post compara chains de execução e explica como CLI + SKILL distribui complexidade no sistema de engenharia enquanto MCP continua servindo seu propósito.
Parte 3: Filosofia Central
3. A Regra de Ouro: CLI Produz Fatos, o Modelo Age sobre os Fatos
O princípio core: não faça o modelo memorizar todas as regras—deixe as regras serem executadas nos lugares certos. Este post introduz `cli-schema validate`, o gate de qualidade que captura erros de campos, enums errados, e problemas estruturais antes que se tornem escritas falhas.
Partes 4-5: Design Técnico
4. agentHints: Ensinando CLIs a Conversar com Agentes
A saída tradicional de CLI é para humanos. Agentes precisam de resultados estruturados, razões de falha, e sugestões de próximos passos. `agentHints` transforma experiência de produto em guidance machine-readable—aparecendo exatamente onde Agentes precisam fazer decisões.
5. SKILL: Enviando Experiência Operacional como Código
Um SKILL não é apenas uma referência de comandos. É um guia operacional para Agentes de IA: quando usar um comando, qual vem primeiro, quais campos não devem ser "chutados", quando validar, quando ler de volta. SKILL empaqueta conhecimento de fluxos de trabalho em guias versionáveis, evolucionáveis.
Partes 6-7: Validação e Prática
6. Os Números Não Mentem: 30% Menos Chamadas de Ferramentas, 25% Menos Tokens
Comparamos MCP vs. CLI + SKILL em tarefas típicas. Passos de chamadas de ferramentas diminuíram ~30%. Consumo de tokens de descrições inválidas e retries diminuíram ~25%. Retries de erros estruturais diminuíram ~40%. Este post detalha onde os savings vêm.
7. Do PRD ao Ciclo de Testes: Um Fluxo de Trabalho Completo de Agentes com Apidog CLI
Percorra um exemplo real: uma equipe tem um PRD de Order Refund e codebase. Veja como um Agente usa CLI + SKILL para gerar OpenAPI, criar casos de teste, validar estruturas, construir cenários de teste, e executar verificação—end to end.
Partes 8-9: Fundação e Segurança
8. Por Que a Compatibilidade CI/CD É Inegociável para Ferramentas de Agentes
Amigabilidade para Agentes deve ser construída sobre amigabilidade para CI/CD. `apidog run` serve ambos: CI se importa com exit codes, arquivos de relatório, parâmetros estáveis; Agents se importam com resultados estruturados, razões de falha, sugestões de próximos passos. Um comando, múltiplos consumidores.
9. AI Branch: Mudanças de Projeto Mais Seguras com Agentes de IA
Quando Agentes modificam recursos do projeto, segurança importa. AI Branch fornece edição isolada—mudanças ficam em uma branch separada até revisão humana. Isso previne mudanças automáticas de afetar diretamente a branch principal. Crie, revise, então merge com confiança.
Parte 10: Visão e Futuro
10. Spec-First Foi Ontem. Bem-vindo ao Skill-First.
O desenvolvimento de API está mudando com Agentes de IA entrando no fluxo de trabalho. Spec-First foi para colaboração humana. Skill-First empaqueta specs, testes, e cenários em skills executáveis, verificáveis—complementando abordagens existentes para a era de Agentes. Este post delineia o futuro e fornece passos concretos para começar.
Conclusões Chave (TL;DR)
| Insight | O Que Significa |
|---|---|
| MCP e CLI + SKILL servem necessidades diferentes | MCP conecta ferramentas; CLI + SKILL executa fluxos de trabalho—use o que se adapta à sua tarefa |
| Complexidade pertence à engenharia, não ao contexto | 126 ferramentas × 500 tokens = 50,000 tokens de burden para fluxos de trabalho complexos |
| `cli-schema validate` é o gate de qualidade | Capte erros localmente, não através de escritas falhas |
| `agentHints` guia próximos passos | Previne Agentes de escrever baseado em "imaginação" |
| SKILL empaqueta experiência operacional | Não apenas comandos—sabedoria de fluxos de trabalho para Agentes |
| CI/CD continua sendo a fundação | Features de Agentes adicionadas acima, não substituindo CI |
| AI Branch fornece camada de segurança | Edição isolada + revisão humana antes do merge |
Comece a Ler
Pronto para começar? Comece com Post 1: Construímos 126 Ferramentas MCP. Depois Descobrimos Uma Solução Melhor para Fluxos de Trabalho.
Baixe o Apidog para desenhar, mock, testar, e documentar APIs em um workspace. Saiba mais sobre Apidog CLI para testes de API em linha de comando, automação CI e fluxos de trabalho de Agentes de IA.