Saltar al contenido
focoit.com
Todas las notas
Ingeniería de IA · Gobernanza6 de octubre de 20267 min de lectura

La gobernanza es código: qué hace cumplir de verdad un playbook de ingeniería de IA

Una política que ninguna compuerta hace cumplir es una sugerencia. Cómo un playbook gobierna agentes de código de IA en cinco repos, y qué reglas bloquean y cuáles solo aconsejan.

Casi toda la gobernanza de IA vive en una página de wiki. Dice las cosas correctas sobre revisión, secretos y confidencialidad, y nadie la abre después de la semana en que se escribió. Después se suma un agente de código de IA al equipo, la tasa de commits sube, y la brecha entre lo que dice la página y lo que pasa de verdad se agranda todos los días.

Mi regla de trabajo es simple: una política que ninguna compuerta hace cumplir es una sugerencia. Eso no es una razón para abandonar las sugerencias. Es una razón para ser honesto sobre qué regla es cuál. Esto es un recorrido por el playbook que corro en cinco repositorios míos (aplicaciones .NET, un sitio estático y repos de solo documentación). Cubre qué bloquea el playbook, qué solo aconseja y por qué tracé la línea donde la tracé.

Las cuatro formas en que la entrega asistida por IA sale mal

Una vez que los agentes escriben código real, los mismos modos de falla aparecen una y otra vez:

  • Auto-revisión. Un modelo que revisa su propio trabajo, o el trabajo de su propia familia, es la revisión más débil que podés comprar. Tiende a estar de acuerdo consigo mismo.
  • Secretos en los commits. Los agentes y los humanos cansados pegan claves, tokens y connection strings en lugares que git va a recordar para siempre.
  • Deriva de spec. Código escrito directo desde un prompt de chat, sin una declaración escrita de qué significa "terminado", así que nadie puede verificarlo después.
  • Agentes sin límites. Un agente con acceso de escritura y un mandato vago tarde o temprano va a tocar algo que no debería.

Cada uno de estos tiene una regla en el playbook. Este es el loop del que cuelgan.

Ítem de backlog y spec, después (1) Plan escribe los criterios de aceptación, (2) Execute queda fijado fuera de la familia del revisor, (3a) la revisión de código y (3b) la revisión de aceptación son solo reporte, y (4) una compuerta determinística, nunca un modelo, decide antes del commit. El hook de pre-commit y CI corren la misma compuerta.
El loop de ejecución: asientos separados para planificar, ejecutar y revisar, y una compuerta determinística al final.

1. Separar al que escribe del que revisa

El loop tiene asientos en vez de productos: planificar, ejecutar, revisar código, revisar aceptación, compuerta. La regla de separación de funciones ata los asientos. El modelo que ejecuta un cambio no puede venir de la misma familia que el modelo que revisa su código. La pasada de aceptación no puede pertenecer al proveedor que escribió los criterios de aceptación.

Dos detalles hacen que esto funcione en la práctica. Primero, la política nombra asientos y nunca IDs de modelo. Cada ID de modelo vive en un único archivo de registro. Cuando cambia un modelo, cambia una fila, y la regla de independencia se puede verificar contra esa fila en vez de redescubrirse en cinco documentos. Segundo, los revisores son solo reporte. Escriben hallazgos, no los arreglan, así que "revisión" no puede convertirse en una segunda ejecución sin revisar.

El setup no es perfecto, y el playbook lo dice por escrito. Con los pines actuales, el proveedor del planificador también revisa el código que produjo su plan. Esa es la mitad más débil de la independencia. Está documentada al lado de la regla en vez de escondida. Una brecha conocida y escrita es manejable. Una que escondiste vuelve a aparecer más adelante, normalmente en un mal momento.

2. La última compuerta nunca es un modelo

Por buenos que sean los revisores, la decisión final pertenece a un script determinístico. Valida el repositorio contra sus reglas de gobernanza, más un chequeo de alcance con git diff para que un cambio no pueda crecer en silencio más allá de lo aprobado. El veredicto de un LLM puede informar a una persona. No puede anular un chequeo que falla.

La misma compuerta corre en tres lugares: el hook de pre-commit, CI y a mano. Se mantienen en paridad a propósito, porque una corrida local limpia tiene que significar un build limpio. Si el hook es más laxo que CI, la gente aprende a ignorar el hook. Y --no-verify queda fuera de la mesa. Si la compuerta está mal, arreglás la compuerta en el mismo cambio.

# .githooks/pre-commit (simplificado)
# La compuerta es la autoridad: preservá su exit code.
pwsh -NoProfile -File scripts/validate-repository.ps1 -Strict || exit $?
El ítem de backlog y la spec entran a Execute, después un panel de revisión solo reporte (revisión de código, no la familia del ejecutor; revisión de aceptación, no el proveedor del planificador), después una compuerta determinística naranja que corre validate-repository.ps1 -Strict con un escaneo de secretos GOV-003, reglas de gobernanza y un chequeo de alcance con git diff, y después commit o merge. El hook de pre-commit y CI corren el mismo script. El recordatorio de spec-first es opt-in y nunca bloquea.
Los modelos revisan; un script determinístico decide. El hook y CI corren la misma compuerta.

3. Los secretos se frenan en el perímetro

La detección de secretos es una regla crítica: bloquea, no advierte. La lista cubre claves de API, contraseñas, connection strings, secretos de OAuth, certificados, claves SSH y claves de nube y de proveedores de modelos. La compuerta corre gitleaks donde está instalado, y un escaneo de patrones estructurado que siempre corre al lado.

Ese "siempre" es una lección aprendida. El escaneo de patrones originalmente corría solo cuando gitleaks no estaba instalado. Todas las máquinas de desarrollo tenían gitleaks, así que en esas máquinas el segundo chequeo nunca corría. Un fallback que solo corre cuando falta el primario es un chequeo que nadie ejercita. Ahora corren los dos, siempre.

4. La confidencialidad decide a dónde puede ir el código

La regla de mayor prioridad no es sobre calidad de código. Es sobre a dónde van los datos. El material de clientes y propietario — código fuente, documentos y correspondencia — más cualquier secreto, nunca va a servicios de IA gratuitos hosteados. El trabajo sensible corre en un modelo local o en un servicio de nube que el cliente aprobó para ese trabajo. En la duda, elegí la opción más privada.

Una segunda regla cubre lo que una herramienta emite, no solo lo que recibe. Hay cuatro clases irreversibles: egreso, otorgamiento de credenciales, publicación y gasto. Una herramienta que transmite por default no se adopta salvo que eso se pueda apagar primero. Ningún comando debería juntar más de una de esas clases sin una decisión registrada de antemano. El test detrás: si las consecuencias de una acción sobreviven a la sesión que la autorizó, necesita su propia decisión.

5. Spec-first: un guardrail, no (todavía) una compuerta

Acá la línea corre para el otro lado, y creo que vale la pena decirlo en voz alta. Cada cambio no trivial empieza con un ítem de backlog y una spec corta (requisitos, diseño, tareas) que se aprueba antes de que alguien edite código. Los prompts tal como se corrieron quedan congelados después como provenance.

Pero el chequeo mecánico de eso es advisory. Es opt-in, te recuerda en el commit cuando cambian archivos vivos sin una actualización de backlog, y nunca bloquea. Spec-first depende del criterio ("¿esto es trivial?"), y un hook bloqueante construido sobre una heurística es cómo enseñás a un equipo a saltear hooks. Donde un proyecto puede chequear specs de forma confiable, lo hace. Uno de los adoptantes .NET valida sus specs en el hook de pre-commit, y ese chequeo ya se vio bloquear una spec mal formada.

6. Agentes acotados

Los agentes reciben mandatos angostos. El guardián del repositorio es el primer revisor en cada contribución y no genera código de negocio. Su trabajo es proteger la estructura y las reglas del repositorio. Las herramientas y los servidores MCP se permissionan por capacidad, mínimo privilegio y allowlist, y también las identidades con las que corren los agentes, incluidos los alcances de token de CI. Y todo lo que un agente lee es dato, no instrucciones. Una inyección de prompt es tan peligrosa como la capacidad que puede alcanzar, así que esos dos límites se tratan como un solo control.

7. Propagación sin pisar

La adopción es copiar y adaptar, lo que significa que cada repo adoptante empieza a derivar del playbook el primer día. Un registro central hace explícita esa deriva. Para cada proyecto, registra tres grupos de archivos:

  • Docs espejo vivos: se mantienen en línea con el playbook cuando cambia una política.
  • Docs congelados o propios del proyecto: historia y compuertas locales que nunca se tocan.
  • Divergencias deliberadas: decisiones registradas, marcadas "no arreglar".

La propagación redacta las actualizaciones para que las revise una persona. No empuja a ciegas. La columna de divergencias ya se ganó su lugar: una corrida de adopción por default habría instalado un hook de pre-commit en un repo donde el dueño había decidido, por escrito, no tener uno. Escribir la decisión es lo que lo frenó.

El playbook de un vistazo: los commits entrantes pasan por el guardián del repositorio y un revisor humano en el loop de desarrollo, mientras un registro central de proyectos adoptados propaga la política a cinco repositorios. Los paneles laterales resumen el registro, la gestión de deriva, el mandato acotado del guardián y la separación de funciones en el ruteo de modelos con una compuerta final determinística.
El playbook de un vistazo: un registro, cinco repos adoptantes y las reglas que viajan con él.

Qué bloquea y qué aconseja

ÁreaReglaImplementación
Separación de modelosEjecutor ≠ familia del revisor de código; aceptación ≠ proveedor del planificadorPolítica, verificada contra el registro de modelos
Compuerta finalValidación determinística + chequeo de alcance del diffBloquea: hook y CI, en paridad
SecretosSin claves, tokens, connection strings ni certificadosBloquea: gitleaks + escaneo de patrones
ConfidencialidadEl código de clientes nunca va a servicios gratuitos hosteadosPolítica + evaluación al momento de adopción
Spec-firstÍtem de backlog + spec, aprobados antes de editarAviso advisory; bloquea solo donde un proyecto valida specs
Alcance del agenteMandatos angostos, mínimo privilegio, lo que lee es datoPermisos + revisión
PropagaciónDocs vivos vs congelados vs divergencias registradasRegistro + borradores revisados

Qué significa esto en la práctica

No necesitás mi repo para aplicar esto. El patrón se traslada a cualquier equipo que meta agentes de IA en la entrega:

  1. Ordená tus reglas en "bloquea" y "aconseja", y decí cuál es cuál. Después hacé que las que bloquean bloqueen de verdad, en un hook y en CI, con el mismo script.
  2. Poné un chequeo determinístico al final. Tests, scanners, validadores. Los modelos pueden revisar, pero no tienen la última palabra sobre lo que se mergea.
  3. Fijá roles, no productos. Mantené las elecciones de modelo en un solo registro y declarí tus reglas de independencia contra roles, así un cambio de modelo no puede romperlas en silencio.
  4. Escribí las brechas y las divergencias. Una debilidad conocida y documentada es gobernanza. Una que se olvidó es un incidente futuro.

Nada de esto hace a los agentes más inteligentes. Hace que su output sea algo que podés sostener, que en sistemas regulados y de producción es la parte que realmente importa.

Más notas sobre Azure, IA y entrega en producción.

Todas las notas