Airframe

Por qué Airframe

Listo para un agente de código

Airframe se diseñó desde el principio con un agente de código como colaborador. Un cambio que escribe un agente de código pasa exactamente por los mismos controles que el de una persona, y la aprobación que permite fusionarlo viene de la cuenta de una persona con nombre en el catálogo que no lo escribió ni hizo commits en él.

El ciclo de un agente de código

  1. Las skills enseñan la plataforma

    El repositorio platform-skills da a todo agente de código que lo carga los patrones de la plataforma: dónde va un cambio, el catálogo, las raíces de un producto y los módulos de golden-path, los nombres, y las reglas del paquete de políticas con sus mensajes. Cuatro de las cinco skills traen ejemplos que el paquete de políticas, terraform validate o el lint del catálogo deben aceptar o rechazar como dice la skill, y en la visión general de la plataforma se verifican las rutas que nombra. Estas verificaciones se ejecutan en cada cambio a las skills, contra el paquete de políticas de la versión de la plataforma que las skills fijan, y otra vez cuando una versión nueva se verifica antes de permitirse.

  2. Validar localmente, como lo hace el merge request

    airframe validate ejecuta la validación del merge request en la computadora portátil, sin credenciales ni estado: el formato, terraform validate, el validate de OpenTofu y tflint donde están instalados, y el paquete de políticas sobre las raíces de Terraform, el archivo de pipeline y los Dockerfiles declarados. Lo que necesita la plataforma queda en el pipeline: las verificaciones de la compuerta de aprobación, la detección de secretos, el análisis de dependencias y el análisis estático de GitLab, la compilación y las pruebas de la aplicación, el plan, la revisión del plan por el paquete y su precio.

  3. Leer el mensaje, corregir, validar otra vez

    Una regla que falla nombra el recurso y qué está mal en él, y muchas también dicen qué hacer en su lugar, así que el ciclo es corto: escribir, validar, leer el mensaje, corregir, validar otra vez y luego abrir el merge request. Una advertencia no hace fallar la ejecución; las skills le indican a un agente de código que la corrija o que dé su razón en el merge request.

  4. Los mismos controles que todos

    El merge request ejecuta los mismos jobs inyectados y las mismas reglas sin importar quién lo escribió; nada en ellos depende del autor. Por la convención que enseñan las instrucciones de la plataforma para un agente de código y sus skills, los commits de un agente de código llevan un trailer Generated-by que nombra al agente y al modelo, y sus merge requests llevan la etiqueta agent. Todavía nada verifica ninguno de los dos.

  5. Aprueba una persona con nombre

    La política de aprobación de GitLab cuenta solo la aprobación de una persona que el catálogo nombra y que no escribió el cambio ni hizo commits en él, y la compuerta de aprobación aprueba solo cuando lo aprobaron los responsables actuales del cambio. Un agente de código con una cuenta propia no está nombrado en ninguna parte, así que su aprobación nunca cuenta. Uno que trabaja con la cuenta de una persona es esa persona para GitLab: no puede dar la aprobación que cuenta en un cambio que escribió con ella, y nada lo distingue de la persona.

Pruébalo

Sigue a un agente de código a lo largo de un cambio. Cada mensaje de abajo es lo que airframe validate imprimió para ese archivo, en la versión de la plataforma que describe este sitio.

Paso 1 de 4

El agente escribe un bucket

Al pedirle un bucket de exportaciones, el agente declara uno con una sola etiqueta. La validación falla antes de enviar nada.

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

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

    Cada recurso lleva las etiquetas de la plataforma, que registran quién lo gestiona, la organización, el dominio y el producto a los que pertenece, su entorno y su criticidad.

  • Advertencia 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)

    Un recurso que el producto declara por sí mismo, en lugar de componer un módulo, necesita una razón en el merge request. El paquete de políticas lo advierte; la aprobación de la plataforma para él está diseñada, y hoy una advertencia no detiene nada.

  • Advertencia 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)

    Un nombre que el producto escribe por sí mismo empieza por el slug del producto, para que diga a dónde pertenece.

Qué lo hace cierto

Una skill dice lo que hacen las verificaciones de la plataforma.
Los jobs skills:policy, skills:validate, skills:catalog y skills:references del pipeline de platform-skills verifican los ejemplos de cada skill contra el paquete de políticas en el commit de control-plane que las skills fijan, terraform validate y el lint del catálogo, y verifican que exista cada ruta que nombra una skill; GitLab fusiona un cambio a las skills solo cuando pasan. El release:check de control-plane exige que ese commit sea el de la versión, y release:verify ejecuta los mismos jobs en los commits de una versión nueva antes de permitirla. Si un agente de código carga una skill depende del agente y de su usuario.
La computadora portátil ejecuta la validación del merge request.
airframe validate (el script de validación local de la plataforma) ejecuta los comandos de formato, terraform validate y paquete de políticas del componente validate sin backend y sin credenciales; OpenTofu y tflint se ejecutan solo donde están instalados. Lee el paquete del clon de control-plane desde el que se instaló, no de la versión que fija el producto, y no ejecuta el lint del catálogo, la compuerta de aprobación, las pruebas de la aplicación, el plan ni su precio.
El trabajo de un agente de código queda etiquetado.
Una convención, no una verificación: las instrucciones para un agente de código del espacio de trabajo y de la plantilla de producto, y la skill airframe-platform, piden un trailer Generated-by en cada commit y la etiqueta agent en el merge request, y la configuración de GitLab de la plataforma define la etiqueta. Ningún job ni regla verifica ninguno de los dos, así que registran lo que declara un agente de código o su usuario.
Solo la aprobación de una persona con nombre permite fusionar un cambio.
La política de aprobación del proyecto security-policies lista a sus aprobadores por nombre, las personas activas del catálogo con cuenta de GitLab, y excluye al autor y a quienes hicieron commits; hoy, en todos los repositorios salvo security-policies, que contiene las propias reglas de aprobación, también se exige la aprobación de la compuerta de aprobación, que cuenta solo las aprobaciones de los responsables actuales del cambio, con las mismas exclusiones. Un agente de código con cuenta propia no está en ninguna de las dos listas. Uno que actúa con la cuenta o el token de una persona es esa persona para GitLab, y nada distingue a uno de la otra.