Este é uma série de 10 partes que compartilha como a Apidog desenvolveu 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:
| 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, o Modelo Atua sobre Fatos | Filosofia central |
| 4 | agentHints: Ensinando CLIs a Falar 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 Loop 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 | Branch 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 & futuro |
Um SKILL não é apenas uma referência de comando. É um guia operacional para Agentes de IA: quando usar um comando, qual vem primeiro, quais campos não devem ser adivinhados, quando validar, quando ler de volta.
CLI Sozinho Não É Suficiente
Comandos CLI dão a um Agente poder de execução.
Mas poder sem discernimento leva a problemas:
| Poder do CLI | Risco Sem Discernimento |
|---|---|
| Criar caso de teste | Cria no projeto errado |
| Atualizar cenário de teste | Atualiza sem ler de volta |
| Importar passos | Importa sem verificar a estrutura existente |
| Executar testes | Executa sem validar mudanças |
Agentes precisam de mais do que comandos. Eles precisam de discernimento operacional.
O Que É SKILL?
Um SKILL é um guia operacional escrito para Agentes de IA.
Não é:
- Uma lista simples de comandos
- Um manual de referência
- Uma página de ajuda
É:
| Conteúdo do SKILL | Propósito |
|---|---|
| Quando usar um comando | Tipo de tarefa → mapeamento de comando |
| Qual comando vem primeiro | Orientação de sequência |
| Quais campos não devem ser adivinhados | Limites de segurança |
| Quando validar | Posicionamento de portão de qualidade |
| Quando ler de volta | Momento da verificação |
| Quando executar testes | Fluxo de trabalho de confirmação |
SKILL dá aos Agentes discernimento operacional.
Instalação
SKILL é um complemento do Apidog CLI:
# Instale o SKILL para seu Agente de IA
apidog skill installIsso instala 8 Skills complementares que ajudam os Agentes a entender:
- Semântica dos comandos CLI
- Estruturas de recursos
- Fluxos de trabalho de tarefas
- Tratamento de erros
- Padrões de verificação
Por Que o SKILL Importa: Fluxos de Trabalho Ocultos
O Agente ainda precisa saber como as tarefas devem ser decompostas em fluxos de execução cross-business.
Essa experiência não pode ser:
- Completamente escrita em descrições de ferramentas (consumiria muito contexto)
- Espalhada no contexto do chat (seria perdida entre as sessões)
- Memorizada pelo modelo (específica do produto, não conhecimento geral)
Fluxos de trabalho ocultos e "armadilhas de negócios" exigem orientação explícita.
Exemplo: Manutenção de Cenário de Teste
Considere manter um cenário de teste complexo.
Abordagem errada (Agente escreve do zero):
Agente: "Vou criar a estrutura do cenário de teste manualmente"
Agente: Escreve array completo de passos com asserções, extratores, processadores
Resultado: Erros de campo, comparadores errados, campos obrigatórios ausentes
CLI: Rejeita a escrita ou cria cenário incompletoAbordagem correta (codificada em SKILL):
| Passo | Por Quê |
|---|---|
| 1. Importar passos existentes de endpoints ou casos de teste | Não escreva estruturas complexas manualmente |
| 2. Ler de volta a estrutura completa | Ver formato importado real |
| 3. Fazer modificações locais | Trabalhar com base precisa |
| 4. Validar antes de atualizar | Capturar erros localmente |
| 5. Executar cenário | Verificar comportamento |
SKILL não diz apenas "existe um comando test-scenario update".
Ele diz:
"Cenários complexos não são adequados para escrever estruturas completas do zero. Um caminho mais estável é primeiro importar endpoints existentes ou passos de caso, depois ler de volta a estrutura completa e, finalmente, fazer modificações locais."
Os Comandos por Trás da Orientação do SKILL
Aqui estão os comandos reais que o SKILL orienta os Agentes a usar:
# Passo 1: Importar passos de endpoints
apidog test-scenario import-steps <scenarioId> --project <projectId> \
--source endpoint --ids <endpointIds> --sync manual
# Passo 2: Ler de volta com detalhes completos
apidog test-scenario get <scenarioId> --project <projectId> \
--with-case-detail
# Passo 3: Atualizar partes específicas (Agente gera JSON de atualização)
# Passo 4: Validar antes de atualizar
apidog cli-schema validate test-scenario-update --file ./scenario-update.json
# Passo 5: Executar atualização
apidog test-scenario update <scenarioId> --project <projectId> \
--file ./scenario-update.json
# Passo 6: Executar verificação
apidog run --project <projectId> --test-scenario <scenarioId>SKILL diz ao Agente quando usar cada comando e por quê.
Insight Chave: get--with-case-detail
SKILL enfatiza:
"Use get--with-case-detail para obter a estrutura real, não para imaginar o caso dentro dos passos."Por que isso importa:
Sem get--with-case-detail |
Com get--with-case-detail |
|---|---|
| Passos mostram apenas IDs | Passos mostram estruturas completas do caso |
| Agente não conhece o formato interno | Agente vê o formato real de asserção/extrator |
| Agente adivinha nomes de campos | Agente trabalha com exemplos reais |
Obter a estrutura real impede atualizações baseadas na imaginação.
Evoluibilidade: SKILL Pode Mudar
Apidog SKILL é uma experiência operacional evoluível e versionável.
Por Que Isso Importa
| Desafio | Solução SKILL |
|---|---|
| Comandos CLI mudam | SKILL pode ser atualizado para corresponder |
| Usuários têm fluxos de trabalho personalizados | SKILL pode ser customizado |
| Novos recursos do produto | SKILL pode ser estendido |
| Melhorias no fluxo de trabalho | SKILL pode ser refinado |
Como Funciona
Os Agentes recebem permissões de escrita para o SKILL.
Se o SKILL ficar desatualizado ou difícil de usar:
- O Agente pode modificá-lo
- O Agente pode sugerir melhorias
- O SKILL evolui através do uso
SKILL não é documentação congelada. É código operacional vivo.
A Camada de Compatibilidade
Aprendemos isso com bugs reais:
Problema descoberto:
Alguns passos de cenário, durante atualizações secundárias, tiveram os passos externos atualizados com sucesso, mas os casos HTTP internos não foram atualizados corretamente.
Causa raiz:
- Marcadores de atualização de caso internos precisavam de tratamento especial
- Agentes não sabiam sobre esses marcadores
- A semântica do produto exigia flags específicas
Solução:
- Lógica de compatibilidade inserida no CLI
- CLI lida com marcadores internos automaticamente
- Usuários e Agentes não precisam saber detalhes internos
O significado da restrição é inserido em camadas no SKILL:
SKILL diz ao Agente para usar os comandos corretos. O CLI lida com a semântica do produto por trás desses comandos. O Agente não precisa entender os marcadores internos.
Carregamento Sob Demanda
SKILL segue o mesmo princípio do cli-schema:
A complexidade deve ser absorvida pela execução e documentação, não totalmente exposta ao modelo.
| Alternativa | Problema |
|---|---|
| Carregar todo o SKILL no contexto | Carga de tokens |
Colocar todas as regras em --help |
Compete por atenção |
| Escrever no prompt | Não pode ser atualizado |
Abordagem do SKILL:
- Agente carrega SKILL sob demanda
- SKILL é carregado quando o tipo de tarefa é identificado
- Somente a orientação de fluxo de trabalho relevante entra no contexto
SKILL vs. Documentação
| Documentação | SKILL |
|---|---|
| Para humanos lerem | Para Agentes executarem |
| Explica o que os comandos fazem | Explica quando usá-los |
| Referência estática | Fluxo de trabalho dinâmico |
| Abrangente | Focado na tarefa |
| Externo ao Agente | Integrado com o Agente |
Os 8 SKILLs Complementares
Apidog fornece 8 SKILLs complementares:
| SKILL | Cobertura |
|---|---|
| Gerenciamento de projeto | Projetos, metadados, recursos |
| Design de API | Endpoints, esquemas, definições |
| Gerenciamento de ambiente | Ambientes, variáveis |
| Criação de caso de teste | Testes de endpoint único, asserções |
| Gerenciamento de cenário de teste | Testes multi-passos, importação, atualização |
| Organização de suíte de testes | Agrupamento, execução |
| Fluxos de trabalho de importação/exportação | Migração de dados, backup |
| Integração CI/CD | Comandos de pipeline, relatórios |
Cada SKILL contém:
- Identificação do tipo de tarefa
- Orientação da sequência de comandos
- Limites de segurança de campos
- Pontos de verificação de validação
- Padrões de verificação
O Que Vem a Seguir
Agora que estabelecemos todos os três componentes centrais:
- cli-schema validate — Portão de qualidade
- agentHints — Navegação para o próximo passo
- SKILL — Discernimento do fluxo de trabalho
A próxima pergunta é:
Isso realmente funciona? Quais são os números?
Na Parte 6, Os Números Não Mentem: 30% Menos Chamadas de Ferramentas, 25% Menos Tokens, compartilharemos os resultados quantitativos de nossas comparações internas — e explicaremos de onde vêm as economias.
Principais Conclusões
- CLI dá poder de execução; SKILL dá discernimento operacional
- SKILL é um guia operacional, não uma referência de comando
- Fluxos de trabalho ocultos exigem orientação explícita
- Importar passos → ler de volta → atualizar localmente é mais seguro do que escrever manualmente
--with-case-detailimpede atualizações baseadas na imaginação- SKILL é evoluível — Agentes podem modificá-lo
- CLI absorve a semântica do produto, SKILL orienta o fluxo de trabalho
- Carregamento sob demanda evita a carga de contexto
Baixe Apidog para projetar, simular, testar e documentar APIs em um único espaço de trabalho. Saiba mais sobre o Apidog CLI para teste de API por linha de comando, automação CI e fluxos de trabalho de Agente de IA.