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.
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 $?
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ó.
Qué bloquea y qué aconseja
| Área | Regla | Implementación |
|---|---|---|
| Separación de modelos | Ejecutor ≠ familia del revisor de código; aceptación ≠ proveedor del planificador | Política, verificada contra el registro de modelos |
| Compuerta final | Validación determinística + chequeo de alcance del diff | Bloquea: hook y CI, en paridad |
| Secretos | Sin claves, tokens, connection strings ni certificados | Bloquea: gitleaks + escaneo de patrones |
| Confidencialidad | El código de clientes nunca va a servicios gratuitos hosteados | Política + evaluación al momento de adopción |
| Spec-first | Ítem de backlog + spec, aprobados antes de editar | Aviso advisory; bloquea solo donde un proyecto valida specs |
| Alcance del agente | Mandatos angostos, mínimo privilegio, lo que lee es dato | Permisos + revisión |
| Propagación | Docs vivos vs congelados vs divergencias registradas | Registro + 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:
- 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.
- 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.
- 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.
- 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.