A governança de agentes de código define a autoridade, os limites de operação e as evidências necessárias para agentes de IA que realizam trabalho de desenvolvimento de software. Ela estabelece quais mudanças e operações uma tarefa permite, com qual identidade e em qual ambiente de execução, e quando essa permissão precisa ser reconsiderada.
Essa definição operacional aplica a governança de agentes de IA ao desenvolvimento. Uma delegação útil descreve mais do que a alteração desejada no código. Ela identifica os repositórios, ferramentas, dados e sistemas externos que o agente pode usar para produzir essa mudança. Revisar o diff resultante não estabelece, por si só, o que aconteceu enquanto o agente trabalhava.
O que é um agente de código?
Um agente de código é um sistema baseado em IA que usa o contexto de desenvolvimento para selecionar e realizar trabalho em direção a um objetivo de desenvolvimento de software. As ações disponíveis podem incluir inspecionar um repositório, editar arquivos, executar ferramentas ou solicitar mudanças em outro sistema. A implementação específica determina quanto desse trabalho ele pode realizar sem nova participação humana.
A interface não define a autoridade. Um assistente de IDE pode propor texto ou invocar ferramentas; um agente de CLI pode operar de forma interativa ou dar continuidade a uma tarefa delegada; um fluxo autônomo pode executar sob uma identidade de serviço. Para fins de governança, examine as operações habilitadas e o ambiente de execução, em vez de tratar esses rótulos de interface como níveis de permissão. Uma sugestão gerada não estabelece que o sistema pode executá-la.
A mesma tarefa pode passar a outro escopo de execução
Considere uma tarefa hipotética: adaptar um cliente de API a um schema de resposta revisado, atualizar fixtures sintéticas, executar o alvo de teste acordado e preparar um diff para revisão. A tarefa não autoriza publicar um pacote nem alterar um ambiente compartilhado.
Suponha que o workspace inicial esteja configurado para permitir escrita apenas no checkout da tarefa e nas saídas temporárias dos testes, sem credencial de publicação disponível e com acesso de rede limitado a um mirror de dependências aprovado. Essas são condições explícitas do exemplo, não propriedades implícitas na palavra “workspace”.
Agora suponha que a tarefa seja retomada em um runner que também possui um diretório de release gravável, um cache de build compartilhado, acesso de rede mais amplo e uma credencial autorizada a publicar o pacote. Essas são condições hipotéticas desse runner, não características universais de CI. A mudança solicitada e até o diff proposto podem continuar idênticos. A autoridade disponível para o código executado durante a tarefa mudou.
| Condição | Workspace inicial neste exemplo | Runner neste exemplo |
|---|---|---|
| Recursos graváveis | Checkout da tarefa e saídas temporárias dos testes | Também um diretório de release e um cache de build compartilhado |
| Rede | Mirror de dependências aprovado | Também destinos disponíveis para jobs de release |
| Credenciais | Sem credencial de publicação | Credencial de publicação de pacote disponível |
| Trabalho solicitado | Adaptar cliente, atualizar fixtures e executar os testes acordados | Mesma tarefa, sem autoridade adicional para release |
| Decisão de governança | Avaliar o trabalho dentro dos limites declarados | Reavaliar o ambiente antes de continuar a execução |
O responsável pelo ambiente poderia fornecer um runner com as restrições originais, ou um revisor autorizado poderia aprovar uma extensão com justificativa específica. Continuar sem mudanças apenas porque o agente se lembra da tarefa ignora essa decisão. Remover uma credencial desnecessária é uma medida diferente de pedir ao agente que não a use.
Diferencie os limites do checkout e do processo
Um repositório identifica o material de origem; um checkout identifica uma cópia de trabalho. Nenhuma dessas descrições, isoladamente, informa quais arquivos, serviços ou credenciais o processo pode alcançar. A documentação de worktrees do Git, por exemplo, descreve cópias de trabalho vinculadas que compartilham dados do repositório e mantêm parte do estado separada. Isso organiza o controle de versão; um limite de execução ainda precisa ser definido e aplicado. Documentação de worktrees do Git, em inglês.
Identifique o usuário efetivo do processo, os diretórios montados, o ambiente herdado, os mecanismos de credenciais acessíveis e os destinos de rede. Inclua recursos compartilhados graváveis que jobs posteriores possam consumir. Uma mudança fora do checkout da tarefa pode não aparecer no diff entregue, mesmo quando afeta outro fluxo de trabalho.
Diferencie também o acesso ao código de sua divulgação. Permissão para ler um repositório privado durante uma tarefa de desenvolvimento não autoriza automaticamente o envio de seu conteúdo a um serviço externo. Defina qual contexto de desenvolvimento pode sair do ambiente e por qual destino aprovado. O escopo relevante pode incluir uma conta ou um repositório dentro de um serviço, além do hostname.
Testes e operações de pacote são decisões de execução
Um comando de teste é uma forma de executar código, não uma garantia sobre seus efeitos. Dependendo do projeto, testes podem invocar rotinas de preparação, subprocessos, clientes de rede ou ambientes de integração. O responsável pela tarefa precisa saber o que o alvo de teste selecionado executa e qual autoridade essa execução recebe.
Operações de pacote exigem o mesmo exame. A documentação da versão 11 do npm descreve scripts de ciclo de vida associados à instalação e à execução de testes e explica que os scripts são passados a um shell. Portanto, um nome de comando familiar pode representar código adicional do repositório ou das dependências. Examine as ferramentas, os scripts e a configuração selecionados antes de tratar uma operação como uma verificação de escopo limitado. Documentação de scripts do npm, em inglês.
No exemplo do cliente de API, as fixtures permitem testar o comportamento de parsing sem exigir acesso ao serviço real. Se o alvo escolhido também executa uma suíte de integração, a operação solicitada muda. Decida entre selecionar um alvo mais restrito e aprovar o acesso adicional ao ambiente e aos dados. Uma falha no teste não é, por si só, permissão para obter uma credencial de produção.
Inclua ferramentas e MCP no escopo de desenvolvimento
O acesso por ferramentas pode ir além do terminal local. Uma ferramenta de repositório, um sistema de issues, um serviço de build ou um servidor MCP pode realizar operações usando uma identidade diferente da identidade do processo local do agente. Avalie a operação real, o destino e a credencial por trás de cada interface.
A especificação de ferramentas do MCP exige que os servidores validem entradas e implementem controles de acesso. Esses requisitos não estabelecem que um servidor específico aplique o escopo de uma tarefa de desenvolvimento. Passar na validação de schema, autenticar-se em um servidor e ter autorização para publicar um pacote são condições distintas. Considerações de segurança das ferramentas MCP, em inglês.
Na atualização hipotética do cliente, uma ferramenta remota que inicia um build precisa ter repositório, revisão, definição do job e identidade de execução identificados. Chamá-la de um workspace restrito não transfere as restrições desse workspace para o runner remoto. O guia de arquitetura explica como localizar essas passagens entre componentes e os pontos capazes de aplicar decisões.
Delegue classes úteis de trabalho com condições explícitas
A produtividade depende de dar aos agentes espaço suficiente para concluir uma tarefa delimitada. Exigir confirmação para cada edição de arquivo pode obscurecer as decisões que mudam a autoridade. Defina o trabalho rotineiro que pode prosseguir dentro das condições estabelecidas e diferencie-o das operações que exigem outra decisão.
Para a tarefa do cliente de API, uma organização poderia permitir edições no cliente e nas fixtures sintéticas, além da execução de um alvo de teste revisado no ambiente restrito. Alterar a estrutura que executa os testes, adicionar uma dependência, abrir uma conexão externa ou modificar a configuração de release exigiria avaliar outro escopo. Essa é uma política de exemplo, não uma classificação universal de risco no desenvolvimento.
Descreva os requisitos de forma que possam ser revisados: resultado desejado e exclusões; repositório e revisão inicial; caminhos e classes de operação permitidos; ambiente autorizado para testes e build; limites de dados e destinos; identidade de execução; e a pessoa autorizada a decidir sobre uma mudança de escopo. Essas condições podem ficar em um sistema de tarefas e políticas já estabelecido. Elas não exigem um novo checklist manual para cada edição rotineira.
Uma exceção deve explicar a operação adicional e por que o escopo existente é insuficiente. “A tarefa precisa de mais permissões” informa pouco ao revisor. “Este teste exige o ambiente de integração designado, sob uma identidade de teste restrita” apresenta uma solicitação concreta que pode ser aceita, limitada ou rejeitada.
Use o guia de governança de agentes de código para transformar esses requisitos em um piloto com casos de validação e responsáveis pela operação.
Reavalie identidade e contexto quando o trabalho mudar de ambiente
O desenvolvedor que solicitou uma mudança, a sessão do agente que realiza o trabalho e a identidade usada pela ferramenta executora cumprem papéis diferentes. Preserve a associação necessária para identificar o responsável pela tarefa, sem presumir que todo o acesso do solicitante deve ser herdado pelo agente ou pelo runner.
Ao retomar uma tarefa, reavalie mudanças relevantes: outra revisão do checkout, um script de teste alterado, um novo executor remoto, montagens adicionais, uma credencial de escopo mais amplo ou outro destino. Um identificador de sessão, isoladamente, não estabelece a continuidade dessas condições. Se a organização não consegue determinar o novo escopo, precisa de uma decisão explícita sobre se a execução pode continuar e de que forma.
A orientação de uso seguro do GitHub oferece um exemplo concreto de CI: credenciais usadas por workflows devem ter apenas os privilégios necessários, e as permissões de tokens podem ser limitadas por job. A lição geral de projeto é atribuir autoridade de execução ao trabalho que precisa dela, em vez de disponibilizar autoridade de release para etapas de desenvolvimento sem essa necessidade. Referência de uso seguro do GitHub, em inglês.
No exemplo, aprovar a mudança no cliente não justificaria manter a credencial de publicação para testes de parsing. Se a publicação se tornar uma tarefa separada depois, ela precisará de sua própria versão do código autorizada, destino e condições de execução. Isso separa uma solicitação legítima de desenvolvimento de uma ampliação acidental do ambiente disponível para realizá-la.
Posicione controles antes do efeito que precisam restringir
O controle de pré-execução avalia uma operação proposta em um ponto que ainda pode impedir seu início. Para um agente de código, esse ponto pode ser uma operação de arquivo, uma chamada de ferramenta de shell ou uma solicitação de build remoto. O escopo do controle depende do que esse ponto consegue observar e afetar.
Verificar uma solicitação inicial de shell não estabelece automaticamente cobertura de cada subprocesso, acesso a arquivo ou conexão realizada depois que o shell inicia. Combine o ponto de decisão com restrições apropriadas no ambiente de execução e no destino. Registre os caminhos fora da integração e a resposta real a falhas de avaliação. A governança de IA em runtime explica com mais detalhe os contratos de momento de aplicação e falha.
Para uma operação sensível a mudanças de escopo, decida antecipadamente se a indisponibilidade do avaliador significa reter o trabalho, rejeitá-lo ou continuar sob uma política justificada separadamente. Verifique esse comportamento no mecanismo instalado. Um requisito declarado de governança não substitui o comportamento que o executor realmente implementa.
Preserve a revisão de código e os controles de repositório
A revisão de código avalia a mudança proposta. Os controles de execução restringem como a tarefa pode operar. Os controles de repositório regulam as mudanças aceitas em branches protegidas. O GitHub, por exemplo, documenta requisitos configuráveis de revisão e verificações de status para essas branches. Esses mecanismos respondem a perguntas relacionadas em pontos diferentes do fluxo. Sobre branches protegidas, em inglês.
Uma restrição de branch não limita, por si só, o acesso de rede de um processo de teste antes de um push. Uma aprovação de execução não estabelece que o código resultante esteja correto. Preserve o valor das duas revisões: examine a mudança e sua cobertura de testes, enquanto avalia separadamente a autoridade sob a qual testes, builds e operações externas são executados.
Preste atenção especial quando um agente altera o mecanismo que valida seu próprio trabalho. Editar um alvo de teste ou workflow pode ser justificável, mas um resultado positivo obtido pelo mecanismo alterado precisa ser revisado nesse contexto. Preserve quem aprovou a mudança na validação e qual revisão foi realmente verificada.
Faça as evidências de desenvolvimento responderem a perguntas específicas
Um registro útil da tarefa conecta o objetivo aprovado à revisão do repositório, ao ambiente efetivo de execução, às operações solicitadas, às decisões aplicadas e aos artefatos produzidos. Inclua o alvo de teste ou build relevante e seu resultado, para que o revisor possa distinguir “esta verificação passou” da afirmação mais ampla “a mudança é segura”.
Mantenha as evidências proporcionais à pergunta. O registro pode identificar o papel e o escopo de uma credencial sem armazenar o segredo em si. Pode identificar um conjunto de fixtures sem copiar respostas sensíveis de serviços. Acompanhe mudanças no ambiente ou na política que expliquem por que uma execução foi permitida e outra exigiu revisão.
Quando não for possível confirmar o resultado de uma operação remota, mantenha esse desfecho sem resolução até haver evidência apropriada. Uma mensagem de conclusão da tarefa ou o diff final não é um relato completo dos efeitos externos. Em suspeitas de uso indevido, o pilar de segurança de agentes de IA acrescenta o modelo de ameaça; o registro de desenvolvimento fornece o contexto da tarefa e da execução necessário para investigá-las.
Onde a KonaSense se aplica
Na implementação Claude Code PreToolUse revisada para o Kona for Agents, solicitações propostas à ferramenta Bash são representadas como operações de shell, com o comando e o diretório de trabalho fornecidos, para avaliação de política. O adaptador pode retornar uma negativa, um pedido de aprovação ao usuário ou argumentos de ferramenta alterados. Seu caminho de erro de avaliação retorna Allow; o efeito da resposta depende do comportamento do host instalado.
Esse é um ponto de decisão específico dentro de um fluxo de desenvolvimento. Ele não estabelece isolamento do processo nem controle de todos os efeitos depois que um shell inicia. Avalie a integração junto às restrições de repositório, runner, credenciais e destinos que definem a autoridade real da tarefa.