# Gobierno del contexto > Los cuatro instrumentos que impiden que la documentación se despegue del proyecto: Zonas Prohibidas, registro de decisiones, permisos del repositorio y la medición de entropía > *La cadena de artefactos resuelve cómo empezar bien. El gobierno del contexto resuelve cómo seguir bien doscientas sesiones después.* Nota **Varias skills del paquete ejecutan lo que este capítulo prescribe.** Cinco dan por hecho el `docs/ADR.md` y le mandan cada decisión arquitectónica como fila nueva: `protocolo-arranque`, `protocolo-features`, `protocolo-cambios`, `protocolo-cierre` e `information-architecture`. La primera es anterior a los cuatro protocolos de la Parte III: abre el registro con la decisión de stack y declara en `AI-FIRST.md` las Zonas Prohibidas que la arquitectura crea. Es también la única que corre una sola vez por proyecto, o una vez por giro grande de producto; las otras cuatro son recurrentes. Dos, `protocolo-features` y `protocolo-cambios`, además piden aprobación antes de tocar una Zona Prohibida. La matriz de permisos no la invoca ninguna: es un instrumento para humanos. Si este capítulo cambia, esas skills se revisan con él. [Ver las skills del paquete](https://ai-first.falcux.com/docs/referencia/skills/) *** ## El problema que aparece en el mes cuatro Los capítulos anteriores resuelven el arranque: una cadena de artefactos que alimenta a la AI, un AGENTS.md que le da reglas, una guía de diseño que crece con el proyecto. Con eso, un proyecto nuevo deja de tener restarts. Pero hay un segundo problema, y no aparece en la primera semana. Aparece cuando el proyecto lleva meses, cientos de sesiones y más de una persona trabajando encima. El AGENTS.md dice que la lógica de negocio va en los casos de uso — y hace seis semanas alguien la puso en un controller porque tenía prisa, y nadie actualizó nada. La guía de diseño documenta un componente que se renombró en marzo. El PRD apunta a una spec que se borró. Y cuando alguien pregunta por qué la cola de trabajos usa este proveedor y no aquel, nadie se acuerda: la decisión se tomó en una sesión de agosto y su justificación, si quedó escrita, está en alguna parte de un registro de veintisiete mil líneas. Nada de eso rompe el build. Todo eso hace que la AI trabaje con información falsa. **Esa distancia entre lo que el proyecto documenta y lo que el proyecto es se llama entropía documental.** No es desorden: es un desajuste que crece solo, porque el código cambia en cada sesión y la documentación solo cambia cuando alguien se acuerda. La diferencia entre las dos velocidades es la entropía. El gobierno del contexto es el conjunto de instrumentos que la mantienen acotada. *** ## El síntoma que nadie mide Un dato de un proyecto real —un CRM de compliance multi-tenant, en producción, construido enteramente con esta metodología— para ver la escala del problema: | Artefacto | Tamaño | | ---------------- | -------------------------------------------- | | `SESSION_LOG.md` | 27.682 líneas, 626 sesiones | | `TECH_NOTES.md` | 1.587 líneas de gotchas por stack | | Cambios formales | 385 documentos `CHG-XXX` | | `AGENTS.md` | 201 líneas, contra un techo declarado de 200 | Ese proyecto está bien documentado. Tiene los cuatro protocolos activos, cierra cada sesión y enruta sus aprendizajes con un árbol de decisión explícito. No es un caso de negligencia — es lo que pasa cuando la metodología funciona durante meses. Y aun así: si alguien pregunta hoy por qué se eligió un patrón de arquitectura sobre otro, la respuesta está enterrada en una de las 626 entradas del registro o en uno de los 385 cambios. No hay índice. Buscarla cuesta más que volver a decidir, así que en la práctica nadie la busca — y la decisión se vuelve a tomar, a veces al revés. El `AGENTS.md` de ese proyecto tiene un árbol de decisión de documentación con siete destinos. Vale la pena leerlo con atención, porque es bueno: | Tipo de contenido | Destino | | ----------------------------------------------- | ------------------------------ | | Invariante arquitectónico o convención vigente | `AGENTS.md` | | Fix histórico, cicatriz de una librería o stack | `TECH_NOTES.md` | | Estado de fase, progreso, lo pendiente | `SESSION_LOG.md` | | Cambio formal con diseño y rollback | `CHG-XXX.md` → `CHANGE_LOG.md` | | Reglas de diseño, UX, microinteracciones | `GUIA_DISENO.md` | | Detalles de un módulo | `specs/{modulo}.md` | | Arquitectura, pilares, stack | `ARQUITECTURA.md` | Siete destinos, y **ninguno responde «por qué se eligió esto en vez de aquello»**. Están el qué es la regla, el qué se rompió, el qué pasó, el qué cambió, el cómo se ve, el qué hace el módulo y el cómo está armado. Falta el porqué. Esa fila faltante es el primero de los cuatro instrumentos que siguen. *** ## Instrumento 1 — Zonas Prohibidas Una Zona Prohibida es una ruta o un patrón del repositorio que el agente no modifica sin aprobación explícita. Migraciones de base de datos, infraestructura, secretos, archivos de licencia. La instrucción en sí no es nueva: cualquiera le ha escrito a un agente «no toques la carpeta de migraciones». Lo que cambia es dónde vive. Escrita en un prompt, dura lo que dura la ventana de contexto y se pierde en la sesión siguiente. Declarada como sección del AGENTS.md, la lee cualquier agente en cualquier herramienta, al abrir la sesión y sin que nadie se acuerde de repetirla. ```markdown ## Zonas Prohibidas No se modifican sin aprobación explícita: /migrations esquema vivo en producción /infra terraform, DNS y secretos .env* credenciales ``` **Qué la distingue de un `.gitignore` o de un CODEOWNERS.** Ninguno de los dos sirve para esto. Un `.gitignore` saca el archivo del control de versiones, que es lo contrario de lo que se quiere: una migración tiene que estar versionada. Un CODEOWNERS pide revisión de una persona al abrir un PR, cuando el cambio ya está hecho. Una Zona Prohibida no impide el cambio ni espera al PR: lo **hace visible en el momento**, para que un humano decida antes de que el trabajo se acumule encima. La regla práctica al declararlas: una Zona Prohibida se justifica cuando el costo de revertir un error ahí es desproporcionado respecto al costo de pedir permiso. Una migración mal ordenada contra una base con datos de producción no se revierte sin ventana de mantenimiento. Un componente mal escrito se reescribe en diez minutos. El primero es zona prohibida; el segundo, no. Declarar demasiadas las vuelve ruido, y el ruido se ignora. *** ## Instrumento 2 — El registro de decisiones Un ADR —*Architecture Decision Record*— es el registro de por qué se tomó una decisión, qué alternativas se descartaron y qué consecuencias trajo. Una fila por decisión, en orden, sin borrar nunca. La idea no es de esta metodología: los ADR existen desde hace años. Lo que este capítulo agrega es dónde encajan en la cadena de artefactos y por qué ninguno de los artefactos anteriores los reemplaza. ### Por qué no lo cubre nada de lo que ya hay * **`ARQUITECTURA.md` no lo cubre.** Es un documento de estado: describe cómo está armado el sistema hoy. Cuando la decisión cambia, el documento se reescribe y la justificación anterior se sobrescribe. Queda el qué y se pierde el porqué — justo lo que hace falta para saber si la decisión sigue siendo válida o si su premisa ya no aplica. * **`TECH_NOTES.md` no lo cubre.** Guarda cicatrices: qué se rompió y cómo se arregló. «Prisma genera los tipos pero no el cliente que corre» es un hallazgo, no una decisión. No hubo alternativas que evaluar. * **`SESSION_LOG.md` no lo cubre.** Es cronología. La decisión aparece ahí mezclada con todo lo demás que pasó ese día, y a las seiscientas sesiones es inencontrable. * **`CHG-XXX` no lo cubre.** Documenta un cambio a algo que ya funciona, con su diseño y su rollback. Muchos cambios no son decisiones arquitectónicas, y varias decisiones arquitectónicas no pasan por un cambio formal. ### Qué entra y qué no Un ADR se justifica cuando la decisión cumple las tres condiciones: 1. **Es difícil de revertir.** Si deshacerla cuesta una tarde, no hace falta registrarla. 2. **Tenía alternativas reales que se descartaron.** Si no había otra opción, no hubo decisión: hubo una restricción. 3. **Alguien va a preguntar por qué dentro de seis meses.** Es el filtro que más descarta. | Sí es ADR | No es ADR | | --------------------------------------------------- | ------------------------------------------ | | Elegir Postgres sobre Mongo | Subir una versión menor de una librería | | Pasar de una cola propia a un servicio administrado | Arreglar un gotcha de la librería de turno | | Que el dominio no importe de infraestructura | Cambiar el color de un botón | | Adoptar monorepo | Modificar un feature que ya funciona | Las cuatro de la derecha tienen destino en el árbol: `SESSION_LOG`, `TECH_NOTES`, `GUIA_DISENO` y `CHG-XXX`, respectivamente. ### El formato ```markdown ## ADR-007 — La cola de trabajos pasa a un servicio administrado - **Fecha:** 2026-09-12 - **Estado:** aceptada - **Supera a:** ADR-003 **Contexto.** La cola propia sobre Postgres aguantaba 200 trabajos por minuto y el pico de cierre de mes llegó a 1.400. Escalarla significaba operar reintentos, visibilidad y letra muerta a mano. **Decisión.** Se adopta el servicio administrado con cola de letra muerta. El módulo de cola pasa a ser un adaptador. **Alternativas.** Redis con una librería de colas: menos latencia, pero suma una pieza que hay que operar. Subir la cola propia: más barato hoy, y nos deja manteniendo infraestructura que no es el producto. **Consecuencias.** Dependemos del proveedor en una pieza más. Los tests de integración necesitan un doble local. El costo de infraestructura sube. ``` **Un ADR no se edita cuando cambias de opinión.** Se agrega uno nuevo que lo supera, y el viejo queda marcado como superado con el enlace al que lo reemplaza. Editarlo destruye la única información que el artefacto existe para conservar: que en su momento, con la información de entonces, esa decisión tenía sentido. Es un registro, no un estado. Es lo que lo hace distinto de todo lo demás en la cadena. *** ## Instrumento 3 — Permisos del repositorio Quién puede modificar qué parte del repositorio: personas, equipos y agentes. Una tabla, versionada junto al código. ```markdown | Superficie | Quién modifica | Agentes | |---------------------|-----------------------------|----------------| | `packages/prisma/` | backend | con aprobación | | `packages/ui/` | diseño y frontend | sí | | `infra/` | solo la persona de infra | no | | `docs/ADR.md` | quien toma la decisión | solo propone | ``` La columna que no existe en ninguna herramienta de control de acceso es la tercera. Los permisos de un repositorio se diseñaron para personas: un agente que trabaja bajo las credenciales de quien lo ejecuta hereda todos sus permisos, y no hay forma de decir «esta persona sí, pero su agente no». Esta tabla es lo que llena ese hueco, y por eso es un documento y no una configuración. Cuidado con el nombre En muchos productos ya existe una «matriz de permisos» que significa otra cosa: los roles y permisos **de la aplicación** —quién aprueba, quién consulta, quién administra—, que es un artefacto del producto y suele vivir en `docs/`. Son dos tablas distintas con el mismo nombre y conviven sin problema, pero conviene titular esta explícitamente **«Permisos del repositorio»** para que nadie las confunda al buscar. **Cuándo hace falta.** Trabajando solo, no hace falta: la tabla diría lo mismo en todas las filas. Empieza a pagar cuando hay más de una persona y más de un agente sobre el mismo repositorio, que es exactamente donde aparecen los conflictos que nadie atribuye a nadie. *** ## Instrumento 4 — Medir la entropía Los tres instrumentos anteriores declaran. Este verifica que la declaración siga siendo cierta, porque una Zona Prohibida que nadie comprueba es una advertencia enterrada en un documento, que es donde empezamos. La clave es que las verificaciones corran **en código puro** —control de versiones, sistema de archivos y expresiones regulares—, sin modelo y sin API key. Tres razones: no cuesta tokens, es determinista (la misma entrada da el mismo resultado, siempre), y sale con código de salida, así que el mismo comando sirve en un hook local y en integración continua. Cinco verificaciones cubren la mayor parte del desajuste real, y sólo una corta el flujo: tocar una Zona Prohibida. Las otras avisan de una decisión que llegó al código sin llegar al registro, de un alcance que creció más de lo que la spec declaraba, de documentos que apuntan a cosas que ya no existen y de una librería de componentes que cambió sin que su inventario se enterara. Tres de las cinco son deterministas y no admiten discusión: una ruta cambió o no cambió, un archivo referenciado existe o no existe, un componente aparece en el inventario o no. La que detecta decisiones no lo es, porque «se tomó una decisión arquitectónica» no cabe en una expresión regular; se resuelve declarando en qué superficies un cambio se presume decisión, en vez de adivinarlo, y tiene que poder silenciarse con una anotación en el commit. Una verificación que no se puede silenciar termina desactivada entera, que es peor que tenerla ruidosa. Los hallazgos se resumen en un número de 0 a 100 que **mide entropía, no salud**: 0 es documentación alineada, y un solo P0 mueve la aguja por sí solo, porque una Zona Prohibida tocada no se compensa con documentación impecable en todo lo demás. El valor no está en el número sino en la serie: ver en un PR que la entropía pasó de 12 a 68 dice algo que ninguna lista de hallazgos dice con la misma fuerza. Todo eso ya corre: es `npx @falcux/ai-first@latest audit`, y `init` deja escritos los dos puntos donde se mide, un hook de git `pre-push` que sólo corta ante un P0 y un flujo de integración continua que corre con `--estricto` en cada pull request. Es un hook de git, no del agente. Qué detecta cada verificación y con qué severidad está en [Las cinco verificaciones](https://ai-first.falcux.com/docs/referencia/verificaciones/); las opciones, el puntaje y los códigos de salida, en [`ai-first audit`](https://ai-first.falcux.com/docs/referencia/audit/); cómo montarlo, en [Auditar en local y en CI](https://ai-first.falcux.com/docs/guias/auditar-en-local-y-en-ci/). Los cuatro instrumentos de este capítulo no dependen del comando: las Zonas Prohibidas, el registro de decisiones y la tabla de permisos son documentos que se escriben a mano, y `audit` los verifica, no los redacta. *** ## Qué no es gobierno del contexto * **No es control de acceso.** Nada de esto impide técnicamente un cambio. Lo hace visible. Un agente decidido a tocar una Zona Prohibida puede hacerlo; lo que no puede es que pase inadvertido. * **No es más documentación.** Es la documentación que ya existe, con los cuatro huecos que deja tapados. Si al agregar estos instrumentos el proyecto termina con más páginas que nadie lee, se aplicó mal. * **No reemplaza a los protocolos.** Los cuatro protocolos de la Parte III siguen siendo cómo se trabaja. El gobierno del contexto es qué se declara y qué se verifica, que es otra cosa. * **No sirve en la primera semana.** En un proyecto de dos sesiones no hay entropía que medir. Esto empieza a pagar cuando hay historia que perder. *** ## Resumen accionable 1. **Declara las Zonas Prohibidas en el AGENTS.md**, no en un prompt. El criterio es el costo de revertir un error, no la importancia del archivo. Pocas, o se vuelven ruido. 2. **Abre un `docs/ADR.md` hoy, aunque empiece vacío.** Es el artefacto que ninguno de los otros cubre, y el único cuyo valor depende de haberlo empezado temprano: un registro de decisiones que arranca en el mes seis nace con seis meses de huecos. 3. **Una decisión entra al ADR si es difícil de revertir, tenía alternativas reales y alguien va a preguntar por qué.** Las tres, no dos. 4. **Nunca edites un ADR para cambiar de opinión.** Agrega uno nuevo que lo supere. La justificación vieja es información, no basura. 5. **Agrega la tabla de permisos cuando entre la segunda persona**, no antes. Su columna útil es la de los agentes, que ninguna herramienta de control de acceso tiene. 6. **Lo que no se verifica, se degrada.** Cualquier verificación que corra en código puro y salga con código de salida sirve — empieza por las deterministas, que se montan en una tarde y no admiten discusión.