Implementing Agent Guardrails

1. A Necessidade de Limites Explícitos

Antes de mergulharmos nas implementações, é crucial entender por que os guardrails são indispensáveis. Um agente autônomo, por definição, toma decisões. Sem limites claros, ele pode tomar decisões indesejadas.

Esses "limites explícitos" são os nossos guardrails. Vamos construí-los camada por camada.

2. Camada 1: Guardrails de Plataforma (A Cerca Externa)

A primeira linha de defesa não está no agente, mas nas plataformas com as quais ele interage. A principal delas é o seu sistema de controle de versão, como o GitHub. Mesmo que o agente tente realizar uma ação proibida, a plataforma deve bloqueá-la.

A prática mais importante aqui é a proteção de branches (Branch Protection).

Para o seu agente, isso significa que:

1. O agente criará um Pull Request (PR) em uma feature branch.
2. Ele não poderá fazer o merge desse PR diretamente na branch main ou develop.
3. A regra de proteção de branch exigirá que um ou mais membros da sua equipe revisem o código gerado pelo agente.
4. Além disso, você pode exigir que todos os testes de integração contínua (CI), como os que você já usa com GitLab CI ou Jenkins, passem com sucesso antes que o merge seja habilitado.

Isso cria um ponto de verificação humano-no-loop essencial, aproveitando a velocidade do agente para a geração de código e a experiência da sua equipe para a validação estratégica.

Outro guardrail de plataforma é aplicar o PoLP nas permissões do GitHub App que você criou na lição anterior, garantindo que ele tenha acesso de escrita apenas aos repositórios do seu projeto (backend-api, frontend-app, mobile-app) e não a outros repositórios da organização.

3. Camada 2: Guardrails de Ferramentas (A Coleira do Agente)

A segunda camada de defesa está nas configurações das ferramentas que compõem o agente, como Atlassian Forge e Rovo.

Permissões Explícitas no Atlassian Forge

Como vimos, o arquivo manifest.yml de um aplicativo Forge é onde você declara as permissões (escopos) que seu agente necessita. A plataforma Forge foi projetada para ser segura por padrão.

Isso funciona como um contrato: seu agente diz exatamente o que pretende fazer, e a plataforma garante que ele não possa fazer nada além disso.

Controle de Ferramentas no Rovo Dev CLI

Para as tarefas que o agente executará localmente no ambiente de desenvolvimento ou em um executor de CI/CD, o Rovo Dev CLI oferece um mecanismo de guardrail muito granular. Você pode controlar exatamente quais ferramentas e comandos o agente pode executar.

Por exemplo, no seu arquivo config.yml, você poderia configurar algo assim:

toolPermissions:
  bash:
    default: ask # Pergunta por padrão para qualquer comando
    commands:
      - command: ls.*
        permission: allow # Permite listar arquivos sem perguntar
      - command: cat.*
        permission: allow # Permite ler arquivos sem perguntar
      - command: dotnet build
        permission: allow # Permite compilar o projeto .NET
      - command: npm install
        permission: allow # Permite instalar dependências do Node
      - command: git commit.*
        permission: ask # Sempre pergunta antes de um commit
      - command: rm .*
        permission: deny # Nega completamente a remoção de arquivos
  allowedExternalPaths:
    - "/path/to/your/project/backend-api"
    - "/path/to/your/project/frontend-app"

Este arquivo se torna um guardrail fundamental, definindo a "caixa de areia" (sandbox) operacional do seu agente.

4. Camada 3: Guardrails Comportamentais (Ensinando as Regras ao Agente)

A última camada é talvez a mais sofisticada. Ter as permissões corretas não garante que o agente as usará da maneira certa. Precisamos guiar seu comportamento. A abordagem de simplesmente dar uma instrução vaga e esperar o melhor resultado, que podemos chamar de "vibe coding", é arriscada.

A solução é uma abordagem mais estruturada chamada Spec-Driven Development (SDD).

Para o seu projeto, isso significa que em vez de dizer ao agente "Implemente a funcionalidade X descrita no JIRA-123", você o instruirá usando os princípios do SDD:

"Com base no JIRA-123 e nas regras de negócio e arquitetura, crie um plano detalhado para implementar a funcionalidade X. O plano deve listar todos os arquivos a serem modificados nos repositórios de backend (C#) e frontend (React), e indicar se uma migração de banco de dados (MariaDB) é necessária. Apresente o plano para minha revisão antes de gerar qualquer código."

Esse prompt transforma o agente de um "caixa-preta" para um parceiro de trabalho transparente, cujo plano você pode validar e corrigir, garantindo que ele siga as boas práticas e a arquitetura definidas nos seus documentos.

Conclusão

Nesta lição, você aprendeu a construir as barreiras de proteção essenciais para operar um agente de código de forma segura. Vimos que os guardrails não são uma única solução, mas um sistema de defesa em camadas.

Principais Pontos:

• Guardrails são Multi-camadas: A segurança eficaz vem da combinação de restrições na plataforma, nas ferramentas e no comportamento do agente.
• Guardrails de Plataforma: Use recursos como a proteção de branches do GitHub para impor processos de revisão humana e garantir a qualidade e segurança do código que entra em branches críticas.
• Guardrails de Ferramentas: Aproveite a configuração explícita de permissões do Atlassian Forge (manifest.yml) e o controle granular de ferramentas do Rovo Dev CLI (config.yml) para criar uma "caixa de areia" segura para o seu agente.
• Guardrails Comportamentais: Adote o Spec-Driven Development (SDD) para superar as limitações do "vibe coding". Force o agente a criar e apresentar um plano detalhado para sua revisão antes de qualquer execução, transformando-o em um colaborador transparente.

Com esses guardrails implementados, você estará muito mais perto de ter um agente que não é apenas produtivo, mas também confiável e seguro para operar no ambiente da sua empresa.

Na próxima lição, vamos abordar como garantir que esses guardrails e o comportamento geral do agente funcionem como esperado. Vamos aprender a definir um conjunto de casos de teste para validar o comportamento do agente em cenários comuns e de borda.