Esta é uma série de 10 partes que compartilha como a Apidog desenvolveu o Apidog CLI, uma ferramenta de linha de comando para testes de API e gerenciamento do ciclo de vida da API. Leia em ordem ou pule para qualquer post que lhe interesse:
| 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 Atua com Base em Fatos | Filosofia central |
| 4 | agentHints: Ensinando CLIs a Falar com Agentes |
Saída estruturada |
| 5 | SKILL: Empacotando 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 Agentes | 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 |
O desenvolvimento de API está mudando com os Agentes de IA. O Skill-First empacota especificações, testes e cenários em habilidades executáveis e verificáveis — complementando as abordagens existentes para a era dos Agentes.
A Era Spec-First
Por anos, os processos de colaboração de muitas equipes de desenvolvimento foram Spec-First.
O Que Foi
| Princípio | Descrição |
|---|---|
| Projetar APIs primeiro | Definir API antes da implementação |
| Colaborar em torno da documentação | Equipes consultam especificação compartilhada |
| Mockar cedo | Frontend pode desenvolver contra mock |
| Depurar juntos | Problemas visíveis em formato compartilhado |
| Testar contra especificação | Verificar se a implementação corresponde ao design |
| Publicar quando pronto | Lançar APIs documentadas e testadas |
O Valor
| Benefício | Por que é Importante |
|---|---|
| Contratos claros | Frontend/backend sabem o que esperar |
| Desenvolvimento paralelo | Equipes trabalham independentemente |
| Redução de atrito | Má comunicação detectada cedo |
| Teste estável | Testes correspondem ao comportamento documentado |
| Documentação viva | Especificação evolui com o produto |
Spec-First foi a abordagem correta para o desenvolvimento de API impulsionado por humanos.
O Novo Consumidor: Agentes de IA
Após o surgimento da Codificação de IA, os consumidores de ativos de API mudaram.
Agentes também começaram a consumir esses ativos.
O Que os Agentes Precisam
| Atividade do Agente | Ativo Necessário |
|---|---|
| Ler endpoints | Documentação da API |
| Adicionar testes | Definições de endpoint, esquemas |
| Executar automação | Cenários de teste, ambientes |
| Corrigir código com base em relatórios | Detalhes de falha, dados de resposta |
| Julgar se a mudança é utilizável | Resultados de teste, cobertura |
Nesse contexto, a documentação de API, casos de teste e cenários de teste no Apidog não são apenas materiais de colaboração para humanos.
São ativos deterministically chamáveis para Agentes.
Transformação de Ativos
| Ativo | Spec-First (Visão Humana) | Skill-First (Visão do Agente) |
|---|---|---|
| Documentação da API | Material de colaboração | Fonte de dados chamável |
| Casos de teste | Artefato de qualidade | Verificação executável |
| Cenários de teste | Fluxo de trabalho de teste | Alvo de automação |
| Ambientes | Configuração | Contexto de tempo de execução |
| Relatórios | Saída de revisão | Sinal de feedback |
Ativos se transformam de "legíveis" para "chamáveis".
Definição Skill-First
Baseado em Spec-First:
| O Que Permanece | Por quê |
|---|---|
| Especificações de endpoint | Ainda precisamos de contratos claros |
| Casos de teste | Ainda precisamos de artefatos de qualidade |
| Cenários de negócios | Ainda precisamos de cobertura de fluxo de trabalho |
| Documentação | Ainda precisamos de referência humana |
Além disso:
| O Que é Adicionado | Propósito |
|---|---|
| Habilidades executáveis | Agentes podem invocar fluxos de trabalho |
| Etapas verificáveis | Portões de qualidade em cada estágio |
| Cadeias rastreáveis | Trilha de auditoria das ações do Agente |
Skill-First = Spec-First + camada de execução do Agente.
A Arquitetura do Sistema
| Camada | Responsabilidade | Exemplo |
|---|---|---|
| Apidog | Gerencia ativos de API e teste | Endpoints, esquemas, casos de teste, cenários |
| CLI | Fornece execução determinística | Comandos, validação, saída |
| SKILL | Fornece julgamento e caminhos de tarefa | Orientação do fluxo de trabalho, regras de sequência |
| Agentes | Entendem objetivos, executam, ajustam | Claude Code, Cursor, Trae, Codex |
Cada camada tem uma função específica.
Como Eles Trabalham Juntos
Usuário: "Gerar testes para a API de reembolso e executar verificação"
↓
Agente: Entende o tipo de tarefa (SKILL ajuda)
↓
Agente: Chama CLI para ler endpoints (CLI executa)
↓
Agente: Gera casos de teste (Agente cria)
↓
CLI: Valida estrutura (cli-schema valida)
↓
Agente: Escreve casos de teste (CLI executa)
↓
CLI: Retorna agentHints (CLI guia)
↓
Agente: Lê de volta, ajusta (Agente segue dicas)
↓
Agente: Executa testes (CLI executa)
↓
CLI: Retorna relatório (CLI fornece feedback)
↓
Agente: Resume para o usuário (Agente completa)Transformação do Fluxo de Trabalho
Fluxo de Trabalho Spec-First (Impulsionado por Humanos)
Humano projeta a especificação
↓
Humano documenta
↓
Humano cria mock
↓
Humano depura
↓
Humano escreve testes
↓
Humano publicaCaracterísticas:
| Aspecto | Descrição |
|---|---|
| Driver | Humano |
| Foco | Colaboração |
| Feedback | Revisão manual |
| Velocidade | Ritmo humano |
| Erros | Humanos detectam |
Fluxo de Trabalho Skill-First (Assistido por Agentes)
Humano especifica o objetivo
↓
Agente lê ativos existentes
↓
Agente gera mudanças
↓
CLI valida
↓
Agente escreve
↓
CLI guia os próximos passos
↓
Agente verifica
↓
Humano revisa o resultadoCaracterísticas:
| Aspecto | Descrição |
|---|---|
| Driver | Agente (guiado por objetivo humano) |
| Foco | Execução |
| Feedback | Validação automatizada |
| Velocidade | Ritmo do Agente |
| Erros | CLI detecta |
O Que as Equipes Devem Fazer
Passos Imediatos
| Passo | Ação |
|---|---|
| 1. Instalar | npm install -g apidog-cli@latest |
| 2. Instalar SKILL | apidog skill install |
| 3. Tentar tarefa pequena | Dar ao Agente uma tarefa de baixo risco |
| 4. Aprender padrões | Observar o fluxo de trabalho do Agente |
| 5. Expandir o escopo | Aumentar gradualmente a complexidade da tarefa |
Exemplo da Primeira Tarefa do Agente
Use o Apidog CLI para me ajudar a criar meu primeiro endpoint de API no Apidog.
Primeiro, verifique minha configuração do Apidog CLI e liste os projetos que posso acessar.
Pergunte-me qual projeto usar. Depois que eu confirmar, crie um endpoint GET /health simples
chamado Health Check com um exemplo de resposta 200. Valide qualquer
entrada estruturada antes de escrever, então leia o endpoint de volta e resuma
o que foi criado.Isso oferece:
| Benefício | Descrição |
|---|---|
| Verificação de configuração | Agente verifica o ambiente |
| Seleção de projeto | Agente pergunta antes de escrever |
| Pequena criação | Primeira tarefa de baixo risco |
| Validação | cli-schema antes da escrita |
| Leitura de volta | Confirma o que foi criado |
| Resumo | Humano obtém resultado claro |
Comandos para Começar
# Instalar Apidog CLI
npm install -g apidog-cli@latest
# Instalar o SKILL complementar
apidog skill install
# Verificar versão (precisa ser 2.2.5+)
apidog -v
# Autenticar
apidog auth login
# Listar projetos
apidog project listO Futuro
| Tendência | Direção |
|---|---|
| Participação de Agentes | Mais tarefas de desenvolvimento de API sendo gerenciadas por Agentes |
| Padrões CLI + SKILL | Fluxos de trabalho maduros e padronizados |
| Mais Skills | Skills específicas de domínio para diferentes contextos |
| Melhor convergência | Engenharia aprimorada para nós críticos |
| Colaboração Humano-Agente | Transição perfeita entre humano e Agente |
O futuro é o desenvolvimento de API assistido por Agentes.
Resumo Completo da Série
Cobrimos toda a jornada:
| Parte | Tópico | Principal Insight |
|---|---|---|
| 1 | Problema | 126 ferramentas MCP → muro de ferramentas aleatórias |
| 2 | Pivô | A complexidade mudou do contexto para a engenharia |
| 3 | Filosofia | CLI valida, Agente gera |
| 4 | Design | agentHints guia os próximos passos |
| 5 | Experiência | SKILL empacota o conhecimento do fluxo de trabalho |
| 6 | Validação | 30% menos chamadas, 25% menos tokens |
| 7 | Prática | PRD → OpenAPI → Testes → Verificação |
| 8 | Fundação | CI/CD permanece a base |
| 9 | Honestidade | Quatro desafios permanecem |
| 10 | Visão | Spec-First → Skill-First |
O Princípio Final
Spec-First era para colaboração humana. Skill-First é para execução de Agentes.
| Era | Abordagem | Consumidor |
|---|---|---|
| Tradicional | Spec-First | Humanos |
| Era dos Agentes | Skill-First | Humanos + Agentes |
Ativos se tornam chamáveis. Fluxos de trabalho se tornam executáveis. Qualidade se torna verificável.
Bem-vindo ao Skill-First.
Principais Conclusões
- Spec-First estava certo para o desenvolvimento impulsionado por humanos
- Agentes agora são consumidores de ativos de API
- Ativos se transformam de legíveis para chamáveis
- Skill-First = Spec-First + execução do Agente
- Sistema: Apidog (ativos) → CLI (execução) → SKILL (julgamento) → Agentes (ação)
- Humano especifica o objetivo, Agente executa, CLI valida
- Comece pequeno, aprenda padrões, expanda o escopo
Baixe Apidog para projetar, simular, testar e documentar APIs em um único espaço de trabalho. 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.