Inteligência Artificial: Mudanças de Projeto Mais Seguras com Agentes de IA

Esta é uma série de 10 partes que compartilha como a Apidog desenvolveu o Apidog CLI, uma ferramenta de linha de comando para testes e gerenciamento do ciclo de vida de APIs. Leia em ordem ou pule para qualquer post que lhe interesse:

Quando um Agente modifica recursos do projeto, segurança e revisibilidade importam. O AI Branch oferece um ambiente de edição isolado – as alterações entram no branch de destino apenas após confirmação humana.

O Desafio de Segurança

Quando Agentes de IA participam do desenvolvimento e teste de APIs, eles podem criar, atualizar e excluir recursos do projeto por meio de comandos CLI.

Este poder vem com risco.

Como permitir que Agentes trabalhem em projetos reais sem arriscar o branch principal?

AI Branch: A Camada de Segurança

O AI Branch é um tipo especial de Branch de Sprint projetado especificamente para operações externas de IA e CLI.

Conceito chave:

Todas as operações de edição iniciadas do Apidog CLI são tratadas como iniciadas por IA / Agentes de IA por padrão.

O AI Branch oferece aos Agentes de IA um branch de edição isolado. As alterações permanecem no AI Branch até que um humano as revise e mescle.

Agente faz alterações via CLI
        ↓
Alterações armazenadas no AI Branch (isolado)
        ↓
Usuário revisa diferenças
        ↓
Usuário confirma escopo do recurso
        ↓
Mesclar para o branch de destino (direto ou solicitação de mesclagem)

O branch principal permanece intocado até sua aprovação.

Por Que o AI Branch É Necessário

Edições iniciadas por IA podem ser imprevisíveis. O Apidog CLI oferece uma ampla gama de recursos de edição — endpoints, esquemas, cenários de teste, suítes de teste e muito mais.

O AI Branch foi projetado para essas operações de edição de alto risco iniciadas por IA.

Ele permite que os Agentes de IA editem recursos do projeto dentro de um escopo controlado:

O Que É AI Branch?

AI Branch é um branch de sprint especial com características específicas:

Características Principais

Como Funciona

A edição normal no cliente por usuários ainda segue as permissões de membros do projeto e as regras de proteção de branch.

Casos de Uso

O AI Branch é adequado quando a IA precisa participar da manutenção do projeto, preservando o isolamento do branch e a confirmação humana.

Workflow Básico

Um workflow típico do AI Branch:

┌─────────────────────────────────────────────────────────────────┐
│                     WORKFLOW DO AI BRANCH                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Passo 1: Criar AI Branch                                        │
│  ┌───────────────────────────────────────────┐                  │
│  │ apidog branch create --type ai             │                  │
│  │ --name "ai/20260312-from-main-feature"     │                  │
│  │ --from main                                │                  │
│  └───────────────────────────────────────────┘                  │
│                    ↓                                             │
│  Passo 2: Importar ou Criar Recursos                              │
│  ┌───────────────────────────────────────────┐                  │
│  │ apidog branch pick-to (importar existente) │                  │
│  │ OU                                         │                  │
│  │ apidog endpoint create (criar novo)        │                  │
│  └───────────────────────────────────────────┘                  │
│                    ↓                                             │
│  Passo 3: IA Modifica Recursos                                   │
│  ┌───────────────────────────────────────────┐                  │
│  │ Agente usa CLI para atualizar endpoints,  │                  │
│  │ esquemas, cenários de teste, etc.          │                  │
│  │ (--branch parameter especifica AI Branch) │                  │
│  └───────────────────────────────────────────┘                  │
│                    ↓                                             │
│  Passo 4: Usuário Revisa Diferenças                               │
│  ┌───────────────────────────────────────────┐                  │
│  │ apidog merge-request preview              │                  │
│  │ OU                                         │                  │
│  │ Visualizar no cliente Apidog              │                  │
│  └───────────────────────────────────────────┘                  │
│                    ↓                                             │
│  Passo 5: Mesclar para o Branch de Destino                       │
│  ┌───────────────────────────────────────────┐                  │
│  │ Mesclagem direta (branch desprotegido)    │                  │
│  │ OU                                         │                  │
│  │ Solicitação de mesclagem (branch protegido)│                  │
│  └───────────────────────────────────────────┘                  │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Criar um AI Branch

Use branch create --type ai:

apidog branch create \
  --project 123456 \
  --type ai \
  --name "ai/20260312-from-main-userRegister" \
  --from main

Recomendação de nomeação: ai/AAAAJJDD-from-sourceBranch-featureOrModule

Editar Recursos em um AI Branch

Quando o CLI escreve recursos do projeto, use o parâmetro --branch para escrever no AI Branch:

Workflow recomendado:

# 1. Obter esquema
apidog cli-schema get endpoint-create

# 2. Validar antes de escrever
apidog cli-schema validate endpoint-create --file ./endpoint.json

# 3. Escrever para AI Branch (não para o principal)
apidog endpoint create \
  --project 123456 \
  --branch "ai/20260312-from-main-userRegister" \
  --file ./endpoint.json

Importar Recursos Existentes

Para modificar recursos existentes, importe-os primeiro do branch de origem:

apidog branch pick-to \
  --project 123456 \
  --from main \
  --to "ai/20260312-from-main-userRegister" \
  --endpoint-ids 1001,1002

Isso garante que a IA trabalhe com a versão base correta.

Revisar Alterações Antes de Mesclar

Antes de mesclar, visualize as diferenças:

apidog merge-request preview \
  --project 123456 \
  --from "ai/20260312-from-main-userRegister" \
  --to main

Ou veja a diferença completa no cliente Apidog.

Mesclar um AI Branch

Após a revisão, mescle as alterações:

Mesclagem Direta (Branch Desprotegido)

apidog branch merge \
  --project 123456 \
  --from "ai/20260312-from-main-userRegister" \
  --to main \
  --endpoint-ids 1001,1002

Solicitação de Mesclagem (Branch Protegido)

apidog merge-request create \
  --project 123456 \
  --from "ai/20260312-from-main-userRegister" \
  --to main \
  --reviewer-ids 20001,20002 \
  --endpoint-ids 1001,1002

Importante: Os comandos de mesclagem processam apenas a lista de recursos explicitamente fornecida. Confirme as dependências (diretórios, modelos, componentes de resposta, testes) antes de mesclar.

Arquivar e Excluir

Depois que as alterações forem mescladas ou não forem mais necessárias:

# Arquivar
apidog branch archive "ai/20260312-from-main-userRegister" \
  --project 123456 --type ai

# Excluir (após arquivamento)
apidog branch delete "ai/20260312-from-main-userRegister" \
  --project 123456 --type ai

Permissões de Edição de IA Externa

Por padrão, o CLI escreve para o AI Branch. Isso mantém as alterações geradas por IA isoladas até a confirmação do usuário.

Para habilitar a edição direta do branch principal:

Configurações do Projeto → Configurações de Recursos → Configurações de Recursos de IA → Permissões de Edição de IA Externa

Recomendação: Mantenha o isolamento do AI Branch habilitado. Habilite a edição direta apenas quando os workflows de automação claramente precisarem dela.

Melhores Práticas

AI Branch no Workflow CLI + SKILL

O AI Branch se integra naturalmente ao CLI + SKILL:

Cada escrita passa pelo AI Branch → revisão humana → mesclagem.

Resumo de Segurança

Juntas, essas camadas criam um loop mais seguro para as alterações de projeto impulsionadas por Agentes.

O Que Vem a Seguir

Com o AI Branch fornecendo a camada de segurança, todas as peças estão no lugar:

• MCP para conexão de ferramentas (Parte 1)
• CLI + SKILL para execução de workflow (Partes 2-5)
• Resultados de validação (Parte 6)
• Workflows práticos (Parte 7)
• Base CI/CD (Parte 8)
• AI Branch para segurança (Parte 9)

Agora é a hora da visão.

Na Parte 10, Spec-First Foi Ontem. Bem-vindo ao Skill-First., descreveremos como o desenvolvimento de API evolui com Agentes de IA — e o que as equipes devem fazer a seguir.

Principais Conclusões

• AI Branch oferece edição isolada para operações de IA/CLI
• As alterações não afetam o branch principal até a confirmação humana
• Crie com branch create --type ai, escreva com o parâmetro --branch
• Importe recursos existentes com branch pick-to antes de editar
• Visualize com merge-request preview, então mescle ou crie uma solicitação de mesclagem
• Permissões de edição direta podem ignorar o AI Branch — use com cuidado
• Melhor prática: um AI Branch por tarefa, validar antes de escrever, revisar antes de mesclar

Baixe 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 workflows de Agente de IA.