Como as rules e policies centralizadas do Elastra enforçam governança em todos os agentes de IA

Quando agentes de código com IA operam sem governança centralizada, o comportamento torna-se uma função da sessão individual: o que o engenheiro escreveu no system prompt hoje, o que o IDE captou de um ficheiro de configuração local, o que o modelo decidiu com base no seu comportamento padrão. O resultado é drift comportamental — agentes que produzem output inconsistente entre engenheiros, IDEs e sessões, sem mecanismo para detetar, medir ou corrigir.

As consequências operacionais são bem conhecidas por equipas que as viveram. Inconsistências de estilo de código que sobrevivem à revisão porque os revisores não têm contexto sobre o que foi dito ao agente. Decisões que contradizem guidelines de arquitetura porque o agente nunca as recebeu. Prompting corretivo repetido que consome tempo de engenharia e introduz nova variabilidade a cada iteração.

A causa raiz é arquitetural: se as rules vivem no cliente — num ficheiro local, uma configuração de IDE ou um system prompt mantido manualmente — então a governança é por engenheiro, por sessão e por máquina. Não há single source of truth, sem precedência enforçada, sem audit trail e sem mecanismo para a organização exercer controlo.

A resposta do Elastra é mover a governança para o backend: as rules são armazenadas na base de dados, resolvidas pelo servidor e enviadas para os agentes através de canais enforçados — independentemente do IDE, modelo ou engenheiro envolvido na sessão.

O Elastra armazena rules em seis scopes distintos: organização, projeto, namespace, repositório, equipa e utilizador. Cada scope serve um propósito de governança diferente. As rules de organização definem a baseline que se aplica em todo o lado. As rules de projeto especificam constraints e convenções para um determinado projeto. As rules de namespace restringem o comportamento a um contexto de trabalho específico dentro de um projeto. As rules de repositório aplicam-se a uma codebase específica. As rules de equipa refletem convenções partilhadas para uma determinada equipa de engenharia. As rules de utilizador permitem preferência individual dentro dos limites definidos pelos scopes superiores.

Quando um agente solicita o seu effective ruleset — através do comando CLI elastra rules materialize ou da ferramenta MCP elastra_rules — o backend resolve todas as camadas aplicáveis e funde-as num único EffectiveRuleset. A resolução segue uma precedência determinística: as rules de utilizador têm prioridade máxima, seguidas das rules de repositório, rules de namespace, rules de equipa, rules de projeto e rules de organização como baseline. O output fundido é um único documento Markdown que o agente recebe como instruções de operação.

Esta arquitetura tem uma propriedade crítica: a organização tem sempre uma voz. Mesmo que um utilizador tenha rules pessoais ou um projeto tenha overrides específicos, a camada de organização não pode ser removida do pipeline de resolução. A baseline aplica-se sempre. Uma policy definida ao nível de organização é uma constraint, não uma sugestão.

As rules são persistidas em PostgreSQL através da Console API do Elastra. Todas as operações CRUD — create, read, update e delete — requerem a capability ManageRules, que é uma named role capability enforçada na camada do servidor antes de qualquer lógica de handler ser executada. Um engenheiro sem esta capability não pode ler nem escrever rules para a organização, independentemente de como interage com a API.

Cada operação de rules é registada como um evento de consola auditável com um payload estruturado: o ator (sessão e utilizador), a organização, o scope target (UUID de projeto, UUID de namespace, UUID de repositório) e a operação realizada. Estes eventos são armazenados e consultáveis, fornecendo um registo rastreável de quem mudou qual rule, quando e para qual scope. Este é o audit trail que torna a governança centralizada operacional e não teórica.

Quando uma rule é criada ou atualizada, o backend sincroniza automaticamente o seu conteúdo com a knowledge base como um documento estruturado. Isso significa que as rules não são apenas enforçáveis através de materialização e da ferramenta MCP — são também recuperáveis como contexto de primeira classe quando um agente realiza uma busca semântica. Um agente a procurar convenções de código encontrará as rules da organização nos resultados. Esta sincronização acontece de forma síncrona na escrita e é registada como aviso se falhar, garantindo que o conteúdo das rules seja sempre descobrível.

O primeiro mecanismo de enforçamento é a materialização. Quando um engenheiro executa elastra rules materialize num repositório, o CLI obtém o effective ruleset do endpoint do backend GET /v1/rules/effective — passando UUID de projeto, UUID de namespace e UUID de repositório como parâmetros — e escreve o Markdown fundido num conjunto de ficheiros específicos de agente.

O Elastra mantém uma lista fixa de materialization targets, um por agente suportado. No momento da escrita, estes incluem: Claude Code (.claude/rules/elastra.md), Cline (.clinerules/elastra.md), Cursor (.cursor/rules/elastra.mdc), Windsurf (.windsurf/rules/elastra.md), Gemini CLI (GEMINI.md), Kiro (.kiro/steering/elastra.md), Augment (CLAUDE.md), Continue (.continue/rules/elastra.md), goose (.goosehints), Roo Code (.roo/rules/elastra.md), Amp (.agents/checks/elastra.md), GitHub Copilot (.github/copilot-instructions.md) e Kimi (.kimi/rules/elastra.md).

Cada ficheiro recebe o mesmo conteúdo fundido, envolvido em marcadores de comentário HTML estruturados (<!-- elastra:rules:v1 start --> e <!-- elastra:rules:v1 end -->) que permitem ao CLI identificar, atualizar ou remover o bloco com precisão sem tocar no resto do ficheiro. Se as rules forem eliminadas da base de dados e a materialização voltar a ser executada, os blocos são removidos automaticamente de todos os ficheiros target — impedindo que rules obsoletas persistam no repositório.

Este mecanismo garante que um agente a operar a partir de contexto local — lendo o ficheiro de rules específico do seu IDE na inicialização — já tem as rules efetivas atuais da organização incorporadas. Nenhuma chamada de rede é necessária durante a sessão para esta camada funcionar. As rules foram obtidas do backend quando o engenheiro configurou o seu workspace.

A materialização trata do início: as rules estão incorporadas nos ficheiros locais antes de a sessão começar. Mas as rules mudam. As policies da organização evoluem, as constraints de projeto são atualizadas, novas convenções de namespace são introduzidas. Um ficheiro materializado escrito na semana passada pode não refletir o effective ruleset de hoje.

O segundo mecanismo de enforçamento resolve isto: a ferramenta MCP elastra_rules. Quando um agente chama esta ferramenta durante uma sessão, o servidor MCP do Elastra obtém o effective ruleset atual diretamente do backend — acedendo a GET /v1/rules/effective com o scope de projeto, namespace e repositório atual — e retorna o Markdown fundido como resposta da ferramenta. O agente recebe as rules atuais e live, não uma cópia local em cache.

Isto cria um modelo de governança pull-on-demand. O agente pode solicitar as suas rules em qualquer ponto durante uma sessão — no início de uma tarefa, quando se aproxima de uma decisão sensível ou após detetar que o scope da tarefa mudou. As rules retornadas são sempre a versão atual do backend, enforçadas por RBAC e auditadas ao nível da API.

Combinado com a materialização, isto dá às organizações duas camadas de enforçamento de rules: uma camada de startup que incorpora rules antes de a sessão começar e uma camada live que mantém o agente sincronizado com a policy organizacional atual durante a sessão. Nenhuma camada é opcional — ambas fazem parte do contrato de governança.

Para além das próprias rules, o Elastra enforça um contrato comportamental no início de cada sessão de agente através do ficheiro ELASTRA.md. Este ficheiro é escrito em cada workspace pelo CLI durante a configuração e define as regras de operação que o agente deve seguir antes de qualquer tarefa começar.

O constraint mais crítico no ELASTRA.md é a regra obrigatória de contexto primeiro: a primeira ação do agente em qualquer tarefa deve ser chamar elastra_context. Não pode fazer grep de ficheiros, glob de diretórios ou ler código local como primeiro passo. Deve consultar a knowledge base do Elastra para arquitetura, fluxos e contexto relevante antes de tocar em ficheiros locais. Isto não é uma preferência — é um passo obrigatório, e o ficheiro bootstrap torna isso explícito com um marcador de aviso.

O bloco bootstrap também especifica a política de write-back obrigatória: se a sessão produzir descobertas duráveis, alterações de código ou conclusões, o agente deve chamar elastra_sync ou elastra_memory_write antes de responder. Isto cria um ciclo de governança que vai além da leitura de rules — governa como o conhecimento produzido durante a sessão é preservado e disponibilizado a sessões futuras.

Este modelo contract-first garante que a governança não é meramente injetada como instruções que o agente pode ou não seguir. As instruções são obrigatórias, auditáveis e estruturalmente colocadas antes de qualquer lógica de tarefa. Um agente que as viola deve reconhecer e explicar explicitamente a violação ao utilizador.

As rules governam o que o agente deve e não deve fazer. O sistema de personas governa o que o agente é. Uma persona é um AgentProfile armazenado na base de dados com um slug, um nome, um system prompt, uma lista de ferramentas permitidas e flags operacionais como enabled e isDefault. As personas têm scope de organização, são controladas por RBAC e resolvidas centralmente.

Quando uma sessão de agente começa, o system prompt da persona ativa é injetado juntamente com as rules nos ficheiros materializados, envolvido nos seus próprios marcadores de bloco (<!-- elastra:persona:v1 start --> e <!-- elastra:persona:v1 end -->). Isso significa que a identidade do agente — o seu papel, o seu formato de output, o seu modo de operação — é também definida pela organização, não deixada à configuração individual.

A combinação de rules e persona cria uma especificação comportamental completa. As rules definem as constraints de operação. A persona define o contexto de operação, o formato de output e o papel. Juntas descrevem exatamente que tipo de agente a organização está a executar nesta sessão, e ambas são rastreáveis ao backend, versionadas através de operações de update e auditáveis através do registo de eventos da consola.

A arquitetura descrita acima tem uma implicação prática: a superfície de controlo da organização sobre o comportamento dos agentes de IA é real e operacional, não aspiracional. As rules estão numa base de dados. São versionadas. São auditadas. São enforçadas através de dois canais complementares — materialização no início e recuperação MCP live. Aplicam-se a todos os agentes, todos os IDEs e todas as sessões sem exigir configuração individual por cada engenheiro.

Isto muda a economia da engenharia assistida por IA. Sem governança centralizada, o agente de cada membro da equipa comporta-se de forma diferente, o drift acumula-se invisivelmente e o esforço corretivo escala com o tamanho da equipa. Com governança centralizada, a consistência comportamental torna-se uma propriedade da infraestrutura, não uma função da disciplina individual. O custo marginal de adicionar um novo engenheiro a uma equipa assistida por IA cai porque a camada de governança absorve o overhead de configuração.

Também muda o perfil de risco. Rules e personas são auditadas. As mudanças são rastreáveis. Quando ocorre um incidente de produção envolvendo comportamento do agente, a questão 'que rules estava o agente a operar sob nesse momento' tem uma resposta precisa, suportada pela base de dados. Essa rastreabilidade não é uma conveniência de debugging — é um requisito de governança para equipas a operar IA em escala de produção.

A organização que implementa o Elastra não está apenas a usar uma ferramenta de IA. Está a operar um sistema governado: um onde os limites comportamentais são definidos centralmente, enforçados automaticamente, atualizados sem perturbar fluxos de trabalho individuais e auditados sem exigir processos manuais de compliance. É isso que torna a engenharia assistida por IA uma capacidade operacional repetível e não um experimento de produtividade.