AI 2026-09-09 8 min

El Chasis de la Gobernanza: Constitución vs. AGENTS.md (Y cómo no ahogarte en deuda de sincronización)

Aprende a estructurar la gobernanza de agentes de IA en tu repositorio usando el Patrón Adapter para separar el contexto ambiental del bajo demanda.

Escrito por Samir El Azem Crovetto • Senior Backend Engineer & DevSecOps

Si has intentado meterle mano al desarrollo asistido por IA en proyectos reales, seguro que has acabado con la cabeza como un bombo al ver la cantidad de archivos de configuración que florecen en la raíz del repositorio. Entre .cursorrules, .cursor/rules/*.mdc, CLAUDE.md, AGENTS.md, .github/copilot-instructions.md y la famosa constitution.md de Spec Kit, parece que hace falta un máster solo para enseñarle a la IA cómo queremos que escriba una función.

(Por cierto, si te pilla de nuevas: Spec Kit es un toolkit de código abierto patrocinado por GitHub y Microsoft que sirve para estructurar y poner orden en todo este flujo de desarrollo agéntico. Es básicamente la navaja suiza que usamos en el sector para obligar a las IA a seguir un proceso riguroso en lugar de improvisar, y tienes todo su código y documentación pública en su repositorio oficial en GitHub: github/spec-kit.)

Es muy común caer en la trampa de pensar: "Vaya sopa de letras. ¿No es esto duplicar trabajo? Si ya tengo mis reglas de estilo en el archivo de Cursor, ¿para qué demonios necesito una Constitución?"

Hoy vamos a bajar este caos a la tierra. Vamos a ver por qué tener todos estos archivos mezclados es la receta perfecta para volver loca a la IA, cómo separarlos de forma limpia usando el Patrón Adapter para no violar el principio DRY (Don't Repeat Yourself), y cerraremos con una historia real de terror (un bug de Spec Kit) que demuestra lo que pasa cuando el sistema de gobernanza tiene amnesia mid-desarrollo.

1. La frontera invisible: Contexto Ambiental vs. Contexto Bajo Demanda

La clave para que tu repositorio no se convierta en un vertedero de tokens está en entender que los archivos de contexto no juegan en la misma liga. Se dividen en dos categorías muy claras que nunca, bajo ningún concepto, deben fusionarse:

┌─────────────────────────────────────────────────────────────────────────┐
│                           El Ecosistema de Contexto                     │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  Contexto AMBIENTAL (Operativo)                                         │
│  - Archivos: AGENTS.md, CLAUDE.md, copilot-instructions.md               │
│  - Misión: Cómo se comporta el agente dentro del repo (linters, tests)  │
│  - Frecuencia: Se inyecta en CADA petición.                             │
│                                                                         │
│                                   VS                                    │
│                                                                         │
│  Contexto BAJO DEMANDA (Arquitectura / Producto)                        │
│  - Archivos: memory/constitution.md (o .specify/...)                    │
│  - Misión: Qué se está construyendo (reglas lógicas de negocio)         │
│  - Frecuencia: Solo se carga en fases críticas de diseño/validación     │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

Contexto Ambiental (El manual de operaciones)

Aquí es donde viven archivos como AGENTS.md, CLAUDE.md o .github/copilot-instructions.md. Su función no es explicar el negocio, sino definir cómo debe comportarse el agente dentro del repositorio. Son reglas puramente operativas e instrumentales:

"No instales librerías de NPM sin preguntar antes."
"Antes de dar una tarea por terminada, ejecuta npm run test."
"Usa el comando git commit con formato conventional commits."
"Ignora los archivos de la carpeta dist/."

Este contexto es ambiental porque los editores y terminales agénticos lo leen y lo inyectan en cada mensaje del chat. Por eso tiene que ser extremadamente corto y directo (menos de 100 o 200 líneas). Si lo engordas demasiado, pagarás la temida "tasa de tokens": cada pregunta tonta que le hagas a la IA consumirá gran parte de su memoria en recordar reglas operativas que ni siquiera vienen al caso en ese momento.

Contexto Bajo Demanda (Las leyes del producto)

Aquí es donde entra la Constitución (como la memory/constitution.md de Spec Kit). Su misión es radicalmente distinta: define qué se está construyendo y cuáles son las leyes arquitectónicas del sistema. Son reglas inmutables de ingeniería y decisiones lógicas de diseño:

"Todos los valores monetarios se procesan como enteros BigInt en céntimos; prohibido usar decimales flotantes."
"Todo backend debe seguir un aislamiento estricto de arquitectura hexagonal."
"La base de datos se migra únicamente mediante archivos SQL reversibles con funciones up y down."

Este contexto es bajo demanda porque no se envía al LLM en cada interacción cotidiana. Solo entra en juego cuando ejecutas comandos de diseño, planificación o auditoría (como /speckit.plan o /speckit.analyze). El motor del pipeline carga la constitución en esos hitos específicos para validar si el plan o el código propuesto se alinean con las leyes del sistema. De esta forma, mantienes la memoria del chat diaria ultra ligera, pero conservas un validador con dientes de acero para cuando toca integrar código.

2. El peligro de la "fuga de contexto" (Context Bleed)

El error más habitual cuando se empieza con estas herramientas es meter reglas de arquitectura y negocio directamente en el archivo del editor (por ejemplo, en .cursor/rules/react-patterns.mdc). Esto provoca una patología llamada Context Bleed (fuga de contexto), que te machaca por dos flancos:

Bloqueo de proveedor (Vendor Lock-in): Si tus reglas de arquitectura solo existen en la carpeta .cursor/rules/, el día que un compañero de equipo use Claude Code en la terminal, o decida trabajar con Windsurf o VS Code con Copilot, estará programando "a ciegas". Tu gobernanza se ha quedado encerrada dentro de un editor específico.
Deuda de sincronización infernal: Si para solucionar lo anterior decides copiar y pegar la regla de "usar BigInt para dinero" en AGENTS.md, CLAUDE.md, .cursorrules y en la Constitución, acabas de crear un monstruo de mantenimiento. El día que decidas cambiar a otra estrategia para la moneda, tendrás que actualizar cinco archivos distintos en tres formatos diferentes. Al segundo sprint, la mitad de tus archivos de contexto estarán desactualizados y la IA empezará a contradecirse a sí misma.

3. La solución limpia: El Patrón Adapter (Adaptador)

Para evitar este infierno y mantener el repositorio completamente DRY, la solución que se suele aplicar en producción es súper elegante: establecer una única jerarquía donde un archivo manda y los demás actúan como punteros.

La Constitución (memory/constitution.md) se mantiene como la única fuente de verdad de las directrices arquitectónicas de tu software, versionada y auditada en Git.

Los archivos de los editores o agentes (como .cursor/rules/ o CLAUDE.md) se configuran como adaptadores delgados (slim adapters). En lugar de contener las reglas pesadas, solo contienen una línea que le dice al agente dónde ir a leer la verdad.

Por ejemplo, puedes crear una regla global de Cursor en .cursor/rules/00-gobernanza.mdc que se aplique siempre (alwaysApply: true) pero que consuma poquísimos tokens:

---
description: Estándares arquitectónicos globales y reglas de diseño del proyecto
alwaysApply: true
---

Para cualquier decisión de diseño de código, patrones de base de datos o
arquitectura, debes leer primero el archivo canónico de gobernanza en:
@memory/constitution.md

Sigue sus directrices de forma obligatoria y sin improvisar.

¡Y listo! Cursor, al ver la referencia con @, sabe que tiene que cargar ese archivo Markdown cuando haga falta. Claude Code leerá su CLAUDE.md y verá una indicación similar. Tu repositorio es ahora agnóstico respecto a la herramienta, tus tokens están a salvo de la inflación y tienes un único lugar donde cambiar las leyes de tu arquitectura. Cada capa hace su curro: la Constitución gobierna qué construimos y cómo se estructura; tus archivos de agentes gobiernan cómo opera la IA en local.

4. El Bug #2459 de Spec Kit: Cuando la Amnesia Rompe el Feedback Loop

Para entender por qué esto de la gobernanza no es un capricho teórico de arquitectos aburridos, vale la pena recordar un bug real y divertidísimo que ocurrió en el desarrollo de Spec Kit (la Issue #2459).

El pipeline de Spec Kit funciona, a grandes rasgos, de forma muy estructurada mediante comandos secuenciales:

/speckit.constitution – Define tus leyes en constitution.md.
/speckit.specify – Describe el "qué" en una especificación en Markdown.
/speckit.plan – Genera la arquitectura y los modelos técnicos.
/speckit.tasks – Desglosa todo en un checklist secuencial.
/speckit.implement – Se pone el mono de trabajo y pica el código.
/speckit.analyze – Audita el repositorio entero contra la constitución para ver si hay desviaciones.

Durante el desarrollo de la herramienta, se dieron cuenta de un comportamiento desesperante: los agentes de desarrollo entraban en bucles infinitos de diseño erróneo. Ejecutabas el analizador (/speckit.analyze) y te reportaba de forma brillante: "¡Ojo! El código generado para el carrito de compra viola el Artículo I de la Constitución porque estás acoplando la lógica directamente en la app en lugar de abstraerla en una librería independiente".

Hasta ahí, brutal. El validador funcionaba de lujo.

El marrón venía en el siguiente paso. Le decías al agente: "Vale, corrige la implementación para pasar la validación". El agente ejecutaba el comando de ejecución (/speckit.implement), se ponía a reescribir el código... ¡y volvía a cometer exactamente la misma pifia de acoplamiento! Volvías a pasar el analizador, volvía a saltar el error constitucional, volvías a implementar, y la IA volvía a violar la regla. Era el día de la marmota.

¿Cuál era el problema técnico?

Al destripar la plantilla de comandos de Spec Kit en templates/commands/implement.md, los desarrolladores descubrieron un vacío de gobernanza absurdo: el comando de implementación cargaba las especificaciones, los planes de datos, la lista de tareas y los contratos de API, pero omitía cargar el archivo constitution.md.

El agente que picaba el código estaba completamente ciego respecto a las leyes de la Constitución. El analizador tenía las leyes en su contexto y auditaba con rigor, pero el ejecutor no las conocía, así que improvisaba basándose únicamente en el plan técnico.

Este fallo de diseño rompía por completo el bucle cerrado de feedback (feedback loop). Se solucionó de forma sencillísima en la PR #2460 (vía Spec Kit v0.8.6) inyectando una simple validación condicional en la plantilla de implementación:

- IF EXISTS: memory/constitution.md

Esta pifia nos deja una lección de oro: no puedes gobernar un sistema auditando decisiones con un reglamento que tus ejecutores no tienen permitido leer. Si tu arnés de ejecución de IA no comparte las mismas restricciones duras que tu pipeline de validación, estás tirando el dinero de tus tokens y garantizando que tus agentes vuelvan a introducir los mismos fallos arquitectónicos una y otra vez.

Resumen para el lunes por la mañana

Si vas a estructurar la gobernanza de tu repositorio hoy mismo, quédate con estos tres pilares prácticos:

No mezcles manzanas con naranjas: Deja AGENTS.md o CLAUDE.md solo para reglas de comportamiento del agente (linters, commits, comandos locales). La arquitectura y la lógica de negocio van a la Constitución.
Aplica el Patrón Adapter: Haz que las reglas de tu editor (.mdc de Cursor) sean punteros delgados que apunten al archivo memory/constitution.md. Te ahorrarás kilos de tokens y deudas de sincronización.
Gobernanza de extremo a extremo: Asegúrate de que tanto el agente que planifica como el que escribe y el que valida leen el mismo archivo de Constitución. Si alguno de ellos tiene amnesia, tu bucle de autocorrección se romperá por el eslabón más débil.

En el siguiente artículo, El Pipeline SDD en la Práctica: De la Sintaxis EARS a las Tareas Atómicas nos dejaremos de tanta teoría organizativa y abriremos la consola de comandos. Haremos un walkthrough real de cabo a rabo utilizando la CLI de Spec Kit para ver cómo la sintaxis de requisitos EARS evita que la IA asuma cosas que no debe, y cómo la fase de clarificación con /speckit.clarify nos obliga a tomar decisiones de arquitectura difíciles antes de escribir una sola línea de código. ¡Nos vemos en las trincheras!

📚 Serie Spec-Driven Development (SDD)

Extra: 🚀 CHEATSHEET: El Ciclo SDD en Google Antigravity con Spec Kit