Esta é uma série de 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 da API. Leia em ordem ou pule para o tema que for mais útil para o seu fluxo de trabalho.
| 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 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 abordagens existentes para a era dos Agentes.
A Era Spec-First
Por anos, muitas equipes organizaram o desenvolvimento de APIs em torno de uma prática simples: definir a especificação antes da implementação.
O Que É Spec-First
| Princípio | Como aplicar |
|---|---|
| Projetar APIs primeiro | Defina endpoints, métodos, parâmetros, payloads e respostas antes de codificar |
| Colaborar em torno da documentação | Use uma especificação compartilhada como contrato entre frontend, backend, QA e produto |
| Mockar cedo | Permita que o frontend desenvolva contra mocks antes do backend estar pronto |
| Depurar em conjunto | Torne problemas visíveis em um formato comum |
| Testar contra a especificação | Verifique se a implementação corresponde ao design |
| Publicar quando pronto | Lance APIs documentadas, testadas e revisadas |
Por Que Isso Funcionou
| Benefício | Impacto prático |
|---|---|
| Contratos claros | Frontend e backend sabem o que esperar |
| Desenvolvimento paralelo | Equipes trabalham sem bloquear umas às outras |
| Menos atrito | Inconsistências aparecem mais cedo |
| Testes mais estáveis | Testes seguem o comportamento documentado |
| Documentação viva | A especificação evolui junto com o produto |
Spec-First foi a abordagem correta para o desenvolvimento de API impulsionado por humanos.
O Novo Consumidor: Agentes de IA
Com a adoção de ferramentas de codificação assistida por IA, os consumidores dos ativos de API mudaram.
Antes, documentação, casos de teste e cenários eram feitos principalmente para humanos. Agora, Agentes também consomem esses ativos.
O Que os Agentes Precisam Ler e Executar
| Atividade do Agente | Ativo necessário |
|---|---|
| Entender endpoints existentes | Documentação da API |
| Adicionar testes | Definições de endpoint e esquemas |
| Executar automação | Cenários de teste e ambientes |
| Corrigir código com base em falhas | Detalhes de erro e dados de resposta |
| Avaliar se uma mudança é utilizável | Resultados de teste e cobertura |
No Apidog, documentação de API, casos de teste e cenários de teste deixam de ser apenas materiais de colaboração humana.
Eles passam a ser ativos chamáveis de forma determinística por Agentes.
A Transformação dos Ativos
A mudança central é esta:
Ativos deixam de ser apenas “legíveis” e passam a ser “chamáveis”.
| 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 QA | Alvo de automação |
| Ambientes | Configuração | Contexto de execução |
| Relatórios | Saída para revisão | Sinal de feedback |
Na prática, isso significa que um Agente não deve apenas “ler” uma especificação. Ele precisa conseguir:
- localizar o endpoint correto;
- entender o contrato;
- gerar ou alterar testes;
- validar a estrutura;
- executar a verificação;
- usar o relatório como feedback.
O Que É Skill-First
Skill-First não substitui Spec-First. Ele adiciona uma camada de execução para Agentes.
O Que Permanece do Spec-First
| O que permanece | Por quê |
|---|---|
| Especificações de endpoint | Contratos claros continuam necessários |
| Casos de teste | Artefatos de qualidade continuam necessários |
| Cenários de negócios | Cobertura de fluxo de trabalho continua necessária |
| Documentação | Referência humana continua necessária |
O Que É Adicionado
| O que é adicionado | Propósito |
|---|---|
| Habilidades executáveis | Agentes podem invocar fluxos de trabalho |
| Etapas verificáveis | Cada estágio pode ter validação |
| Cadeias rastreáveis | Ações do Agente podem ser auditadas |
Skill-First = Spec-First + camada de execução do Agente.
Arquitetura: Como as Camadas se Encaixam
| Camada | Responsabilidade | Exemplo |
|---|---|---|
| Apidog | Gerenciar ativos de API e teste | Endpoints, esquemas, casos de teste, cenários |
| CLI | Fornecer execução determinística | Comandos, validação, saída |
| SKILL | Fornecer julgamento e caminhos de tarefa | Orientação de fluxo, regras de sequência |
| Agentes | Entender objetivos, executar e ajustar | Claude Code, Cursor, Trae, Codex |
Cada camada tem uma responsabilidade separada:
- Apidog armazena os ativos.
- CLI executa ações de forma previsível.
- SKILL orienta o fluxo de trabalho.
- Agente interpreta o objetivo e toma decisões.
Fluxo Prático
Usuário: "Gerar testes para a API de reembolso e executar verificação"
↓
Agente: entende o tipo de tarefa com ajuda do SKILL
↓
Agente: chama CLI para ler endpoints
↓
Agente: gera casos de teste
↓
CLI: valida estrutura com cli-schema
↓
Agente: escreve casos de teste via CLI
↓
CLI: retorna agentHints
↓
Agente: lê de volta e ajusta
↓
Agente: executa testes via CLI
↓
CLI: retorna relatório
↓
Agente: resume o resultado para o usuário
Esse fluxo evita depender apenas de texto livre. O Agente gera, mas a CLI valida e retorna fatos.
Como o Fluxo de Trabalho Muda
Antes: Spec-First Impulsionado por Humanos
Humano projeta a especificação
↓
Humano documenta
↓
Humano cria mock
↓
Humano depura
↓
Humano escreve testes
↓
Humano publica
| Aspecto | Descrição |
|---|---|
| Driver | Humano |
| Foco | Colaboração |
| Feedback | Revisão manual |
| Velocidade | Ritmo humano |
| Detecção de erros | Humanos detectam |
Agora: Skill-First Assistido por Agentes
Humano especifica o objetivo
↓
Agente lê ativos existentes
↓
Agente gera mudanças
↓
CLI valida
↓
Agente escreve
↓
CLI orienta próximos passos
↓
Agente verifica
↓
Humano revisa o resultado
| Aspecto | Descrição |
|---|---|
| Driver | Agente, guiado por objetivo humano |
| Foco | Execução |
| Feedback | Validação automatizada |
| Velocidade | Ritmo do Agente |
| Detecção de erros | CLI detecta |
Como Começar com Apidog CLI e SKILL
Comece pequeno. A primeira tarefa não deve alterar um fluxo crítico de produção. Use um endpoint simples, valide a configuração e observe como o Agente interage com a CLI.
Passos Imediatos
| Passo | Ação |
|---|---|
| 1 | Instale o Apidog CLI |
| 2 | Instale o SKILL |
| 3 | Dê ao Agente uma tarefa de baixo risco |
| 4 | Observe os padrões de execução |
| 5 | Aumente gradualmente o escopo |
Comandos
# 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 disponíveis
apidog project list
Primeira Tarefa Recomendada para um Agente
Use um prompt pequeno, explícito e verificável:
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.
Depois, leia o endpoint de volta e resuma o que foi criado.
Por Que Esse Prompt Funciona
| Elemento | Benefício |
|---|---|
| Verificação de configuração | O Agente confirma que o ambiente está pronto |
| Seleção de projeto | O Agente pergunta antes de escrever |
| Endpoint simples | A primeira mudança tem baixo risco |
| Validação antes da escrita | Reduz erro estrutural |
| Leitura de volta | Confirma o que foi criado |
| Resumo final | O humano recebe um resultado claro |
Esse tipo de tarefa ajuda a validar o fluxo completo sem introduzir complexidade desnecessária.
Checklist para Adotar Skill-First
Antes de entregar tarefas maiores a um Agente, verifique:
- [ ] O Apidog CLI está instalado.
- [ ] A versão é
2.2.5+. - [ ] O login foi concluído com
apidog auth login. - [ ] O Agente consegue listar projetos com
apidog project list. - [ ] O SKILL foi instalado com
apidog skill install. - [ ] A primeira tarefa é pequena e reversível.
- [ ] O Agente lê antes de escrever.
- [ ] O Agente valida antes de salvar.
- [ ] O Agente executa verificação após a mudança.
- [ ] O humano revisa o resultado final.
Padrão de Uso Recomendado
Para tarefas assistidas por Agente, use sempre este padrão:
1. Ler estado atual
2. Confirmar escopo com o usuário
3. Gerar mudança
4. Validar estrutura
5. Escrever mudança
6. Ler de volta
7. Executar teste ou verificação
8. Resumir resultado
Esse padrão mantém o Agente dentro de um fluxo auditável e reduz ações inesperadas.
O Futuro
| Tendência | Direção |
|---|---|
| Participação de Agentes | Mais tarefas de desenvolvimento de API serão gerenciadas por Agentes |
| Padrões CLI + SKILL | Fluxos de trabalho mais 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 mais fluida entre humano e Agente |
O futuro é o desenvolvimento de API assistido por Agentes.
Resumo Completo da Série
| 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 continua útil para desenvolvimento impulsionado por humanos.
- Agentes agora também consomem ativos de API.
- Ativos evoluem de legíveis para chamáveis.
- Skill-First adiciona execução de Agente sobre a base Spec-First.
- O sistema funciona em camadas: Apidog → CLI → SKILL → Agentes.
- O humano define o objetivo, o Agente executa e a CLI valida.
- Comece com tarefas pequenas, observe o padrão e expanda o escopo gradualmente.
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.
Top comments (0)