La objeción justa: ¿para qué otro archivo markdown?
Cualquier ingeniero riguroso debería recibir con recelo un archivo nuevo en el repositorio. Ya tienes README.md, AGENTS.md, CLAUDE.md, SOUL.md, DESIGN.md y los archivos de reglas de tu editor. Cada archivo extra cuesta tokens de contexto y compite por la atención del modelo.
Si NORTH.md fuese solo otro documento de visión o una lista de consejos, merecería borrarse. Existe para una situación que ni las reglas ni las declaraciones de visión resuelven: elegir entre caminos válidos que compiten.
El dilema
Un agente recibe una tarea de refactorización ambigua. Tres caminos pasan el CI, obedecen AGENTS.md y respetan CONSTITUTION.md:
1. El parche tímido que deja la causa raíz en su sitio.
2. La reescritura desmedida que añade dependencias y trabajo que nadie pidió.
3. El movimiento calibrado que elimina el modo de fallo sin sobrediseñar código genérico.
¿Cuál elige el agente? Nuestra hipótesis: si nada declara la dirección del proyecto, deriva hacia el 1 o el 2. NORTH.md está pensado para que el 3 sea la opción evidente.
Quién responde a qué
Cada archivo responde a una pregunta distinta:
| Archivo | Pregunta central | Lo lee | Frontera con NORTH.md |
|---|---|---|---|
| README.md | ¿Qué es este proyecto? | Personas: usuarios, colaboradores, evaluadores. | README describe lo que existe hoy; NORTH.md declara hacia dónde va y hasta dónde empujar. |
| AGENTS.md / CLAUDE.md | ¿Cómo trabajamos aquí? | Agentes de código. AGENTS.md lo leen muchas herramientas (ver agents.md); CLAUDE.md, Claude Code. | AGENTS.md le dice a un agente cómo ejecutar los tests; NORTH.md le dice qué calidad cuenta como entregada. |
| SOUL.md | ¿Quién es el agente? | El propio agente: su persona, sus valores y su tono. | SOUL.md define cómo habla y se comporta el agente; NORTH.md define qué optimiza el proyecto. |
| DESIGN.md | ¿Cómo debe verse la interfaz, y por qué? | Agentes de código que generan interfaz. | DESIGN.md define los tokens; NORTH.md dice si el pulido visual es una apuesta 10x o una superficie 1.1x. |
| VISION.md | ¿Qué futuro perseguimos? | Fundadores y planificadores. No existe una convención formal. | Una visión describe el destino; NORTH.md añade los valores por defecto que deciden la pull request de hoy. |
| CONSTITUTION.md | ¿Qué principios y fronteras son innegociables? | Agentes de código y las personas que revisan su trabajo. | Una constitución fija los límites; NORTH.md fija la dirección, la ambición y los trade-offs por defecto dentro de ellos. |
| NORTH.md | ¿Hacia dónde vamos y hasta dónde empujamos? | Personas y agentes de código que toman decisiones no triviales. | La capa de dirección que proponemos: criterio para cuando se cumplen todas las reglas y sigue habiendo más de un camino válido. |
Donde se difuminan las fronteras
1. NORTH.md frente a VISION.md
VISION.md no tiene una convención formal. Donde existe, suele describir el mundo que el proyecto aspira a crear, y está escrito para inspirar. Un agente que trabaja en una pull request un martes por la tarde no puede deducir de él si construir o comprar una cola de webhooks.
NORTH.md es operativo. Declara apuestas asimétricas concretas («10x en la exactitud de la facturación electrónica; 1.1x en la pantalla de ajustes»), negativas específicas («No construimos un CRM») y trade-offs por defecto precalculados («Seguridad antes que velocidad en el código fiscal; velocidad antes que seguridad en la administración interna»).
2. NORTH.md frente a CONSTITUTION.md
CONSTITUTION.md fija principios y fronteras innegociables. No hay un estándar único: agentconstitution.dev propone un formato a nivel de proyecto, y GitHub Spec Kit mantiene una constitución de proyecto con principios y gobernanza. Algunos formatos también recogen «pares en tensión» (X por encima de Y).
NORTH.md fija la dirección. Saber lo que nunca debes hacer no te dice qué calibre de trabajo se espera, ni dónde ser ambicioso y dónde parar. Si tu constitución ya recoge trade-offs, enlázala desde NORTH.md en lugar de repetirlos.
3. NORTH.md frente a AGENTS.md / CLAUDE.md
AGENTS.md cubre la mecánica de ejecución: cómo compilar, qué linter ejecutar, qué convenciones seguir. Evita que el agente rompa el repositorio.
NORTH.md cubre el criterio del incremento: ¿está terminada una funcionalidad cuando pasan los tests unitarios, o El Listón exige además documentación, una API pública y un registro de auditoría?
4. NORTH.md frente a DESIGN.md
DESIGN.md es un formato de Google Labs para describir una identidad visual a los agentes de código: tokens de diseño legibles por máquina en el front matter YAML, con la justificación en markdown. Está en fase alfa.
NORTH.md fija la prioridad del oficio visual: si las microanimaciones al píxel son una apuesta 10x (en una landing, por ejemplo) o una distracción sobrediseñada (en una tabla de administración interna).
Un modelo de cinco capas que proponemos
En lugar de un único archivo largo de instrucciones, proponemos cinco archivos pequeños, cada uno para una pregunta. Es un modelo, no un estándar establecido, y la mayoría de los repositorios usará solo algunas de las capas.
Capa 1: Límites
CONSTITUTION.md
Principios innegociables y fronteras.
Comunidad · agentconstitution.dev
Capa 2: Ejecución
AGENTS.md
Cómo compilar, probar y trabajar en el repositorio.
agents.md · Linux Foundation
Capa 3: Aspecto
DESIGN.md
Tokens de diseño y la razón de cada uno.
Google Labs
Capa 4: Persona
SOUL.md
La persona, los valores y el tono del agente.
soul.md
Capa 5: Dirección
NORTH.md
Propósito, ambición y trade-offs precalculados.
Esta especificación · MIT