Airframe

Por que o Airframe

Pronto para um agente de código

O Airframe foi projetado desde o início com um agente de código como colaborador. Uma mudança que um agente de código escreve passa exatamente pelas mesmas verificações que a de uma pessoa, e a aprovação que permite fazer o merge dela vem da conta de uma pessoa com nome no catálogo que não a escreveu nem fez commits nela.

O ciclo de um agente de código

  1. As skills ensinam a plataforma

    O repositório platform-skills dá a todo agente de código que o carrega os padrões da plataforma: onde fica uma mudança, o catálogo, as raízes de um produto e os módulos do golden-path, os nomes, e as regras do pacote de políticas com as suas mensagens. Quatro das cinco skills trazem exemplos que o pacote de políticas, o terraform validate ou o lint do catálogo devem aceitar ou recusar como a skill diz, e na visão geral da plataforma são verificados os caminhos que ela nomeia. Essas verificações rodam a cada mudança nas skills, contra o pacote de políticas da versão da plataforma que as skills fixam, e de novo quando uma versão nova é verificada antes de ser permitida.

  2. Validar localmente, como o merge request faz

    O airframe validate executa a validação do merge request no notebook, sem credenciais nem estado: a formatação, o terraform validate, o validate do OpenTofu e o tflint onde estão instalados, e o pacote de políticas sobre as raízes do Terraform, o arquivo de pipeline e os Dockerfiles declarados. O que precisa da plataforma fica no pipeline: as verificações do controle de aprovação, a detecção de segredos, a análise de dependências e a análise estática do GitLab, o build e os testes da aplicação, o plano, a verificação do plano pelo pacote e o seu preço.

  3. Ler a mensagem, corrigir, validar de novo

    Uma regra que falha nomeia o recurso e o que está errado nele, e muitas também dizem o que fazer no lugar, então o ciclo é curto: escrever, validar, ler a mensagem, corrigir, validar de novo e depois abrir o merge request. Um aviso não faz a execução falhar; as skills dizem a um agente de código que o corrija ou que dê o seu motivo no merge request.

  4. As mesmas verificações que todos

    O merge request executa os mesmos jobs injetados e as mesmas regras seja quem for que o escreveu; nada neles depende do autor. Pela convenção que as instruções da plataforma para um agente de código e as suas skills ensinam, os commits de um agente de código levam um trailer Generated-by que nomeia o agente e o modelo, e os seus merge requests levam o rótulo agent. Nada verifica nenhum dos dois ainda.

  5. Uma pessoa com nome aprova

    A política de aprovação do GitLab conta só a aprovação de uma pessoa que o catálogo nomeia e que não escreveu a mudança nem fez commits nela, e o controle de aprovação aprova só quando os responsáveis atuais da mudança aprovaram. Um agente de código com uma conta própria não é nomeado em lugar nenhum, então a sua aprovação nunca conta. Um que trabalha com a conta de uma pessoa é essa pessoa para o GitLab: não pode dar a aprovação que conta numa mudança que escreveu com ela, e nada o distingue da pessoa.

Experimente

Acompanhe um agente de código ao longo de uma mudança. Cada mensagem abaixo é o que o airframe validate imprimiu para esse arquivo, na versão da plataforma que este site descreve.

Passo 1 de 4

O agente escreve um bucket

Ao receber o pedido de um bucket de exportações, o agente declara um com um único rótulo. A validação falha antes de enviar qualquer coisa.

Negado
resource "google_storage_bucket" "exports" {
  name     = "exports"
  location = "US-CENTRAL1"
  labels   = { product = "orders" }
}
  • Negado naming.labels

    google_storage_bucket.exports: missing labels ["criticality", "domain", "env", "managed_by", "tenant"]

    Todo recurso carrega os rótulos da plataforma, que registram quem o gerencia, a organização, o domínio e o produto a que pertence, seu ambiente e sua criticidade.

  • Aviso naming.raw-resource

    google_storage_bucket.exports: a raw google_storage_bucket in a product root needs a reason in the merge request (platform approval); compose the registry's modules where one covers it (skill airframe-naming)

    Um recurso que o produto declara por conta própria, em vez de compor um módulo, precisa de uma justificativa no merge request. O pacote de políticas emite um aviso; a aprovação da plataforma para ele está projetada, e hoje um aviso não bloqueia nada.

  • Aviso naming.slug-prefix

    google_storage_bucket.exports: name "exports" does not start with the product's slug "orders" (docs/contracts.md 2; skill airframe-naming)

    Um nome que o produto escreve por conta própria começa com o slug do produto, para dizer a que ele pertence.

O que torna isso verdade

Uma skill diz o que as verificações da plataforma fazem.
Os jobs skills:policy, skills:validate, skills:catalog e skills:references do pipeline do platform-skills verificam os exemplos de cada skill contra o pacote de políticas no commit do control-plane que as skills fixam, o terraform validate e o lint do catálogo, e verificam que existe cada caminho que uma skill nomeia; o GitLab faz o merge de uma mudança nas skills só quando eles passam. O release:check do control-plane exige que esse commit seja o da versão, e o release:verify executa os mesmos jobs nos commits de uma versão nova antes de permiti-la. Se um agente de código carrega uma skill depende do agente e do seu usuário.
O notebook executa a validação do merge request.
O airframe validate (o script de validação local da plataforma) executa os comandos de formatação, terraform validate e pacote de políticas do componente validate sem backend e sem credenciais; o OpenTofu e o tflint rodam só onde estão instalados. Ele lê o pacote do clone do control-plane a partir do qual foi instalado, não da versão que o produto fixa, e não executa o lint do catálogo, o controle de aprovação, os testes da aplicação, o plano nem o seu preço.
O trabalho de um agente de código fica rotulado.
Uma convenção, não uma verificação: as instruções para um agente de código do espaço de trabalho e do template de produto, e a skill airframe-platform, pedem um trailer Generated-by em cada commit e o rótulo agent no merge request, e a configuração do GitLab da plataforma define o rótulo. Nenhum job nem regra verifica nenhum dos dois, então eles registram o que um agente de código ou o seu usuário declara.
Só a aprovação de uma pessoa com nome permite o merge de uma mudança.
A política de aprovação do projeto security-policies lista os seus aprovadores por nome, as pessoas ativas do catálogo com conta no GitLab, e exclui o autor e quem fez commits; hoje, em todos os repositórios exceto security-policies, que contém as próprias regras de aprovação, a aprovação do controle de aprovação também é exigida, e ele conta só as aprovações dos responsáveis atuais da mudança, com as mesmas exclusões. Um agente de código com conta própria não está em nenhuma das duas listas. Um que age com a conta ou o token de uma pessoa é essa pessoa para o GitLab, e nada distingue um do outro.