Tienes un problema y todavía no lo sabes: tu documentación empezó a mentir en cuanto la publicaste. Cambias un archivo, mueves una carpeta, renombras un componente — y el README, el diagrama y la wiki interna siguen describiendo la web de la semana pasada. Context Driven Development invierte el orden para que eso no pueda ocurrir: el contexto se especifica primero y manda, el código es su consecuencia, y un validador impide que ambos se contradigan.
El problema: documentación que envejece más rápido de lo que la escribes
Casi todo el software se documenta después. Primero se programa, y cuando ya funciona, alguien escribe un README o dibuja un diagrama para explicarlo. El problema es estructural: en cuanto el código vuelve a cambiar —y cambia cada día—, esa documentación deja de ser cierta y nadie la actualiza. Acabas con dos versiones de la verdad que se contradicen, y la gente (o una IA) toma decisiones leyendo la equivocada.
La causa de raíz no es pereza, es el orden. Si la documentación llega al final, siempre va por detrás. La única forma de que deje de mentir es que deje de ir al final.
La idea: el contexto manda, el código es su consecuencia
Esta web no nace en el editor de código, sino en un blueprint. Antes de que exista un solo componente, ya está escrito qué secciones habrá, cómo se relacionan y de qué piezas está hecha cada una. A esa forma de trabajar la llamo Context Driven Development: el contexto se especifica primero y el código es su consecuencia.
Es una variante aplicada de Spec-Driven Development. La diferencia: en lugar de una spec por funcionalidad que se archiva, mantengo un mapa vivo de todo el proyecto. Toda la web se sostiene sobre tres capas que hablan el mismo idioma: el Context —el blueprint que manda—, el design system —los tokens y componentes con los que se construye— y apps/web —la aplicación Next que ensambla las dos anteriores—. Lo interesante no es cada capa por separado, sino cómo se conectan.
«El código es la consecuencia del blueprint, no su origen. Si el Context y el código se contradicen, manda el Context.»
Cómo se conectan las piezas
Lo que sigue es ese sistema hecho interactivo. Cada caja es una capa real de la web y cada flecha, una relación: el Context especifica los nodos, cada nodo declara qué componentes del design system usa y dónde vive su código, y apps/web ensambla todo. Arrastra las cajas para seguir las conexiones.
Diagrama hecho con React Flow: el artículo enseñando, en vivo, cómo está conectada la web que lo muestra.
Dos conexiones merecen atención, y cada una resuelve un problema concreto. La flecha de puntos en burdeos es la sincronización bidireccional: ataca el problema del envejecimiento. Y Connections —Obsidian, Figma, las bases de datos— ataca otro: el de copiar datos que luego se quedan obsoletos. Son fuentes vivas que se consultan bajo demanda, no se copian dentro del blueprint. Veamos las dos piezas que hacen que todo esto se sostenga: qué hay dentro de un nodo, y por qué la sincronización no se rompe.
Qué hay dentro de un nodo: cinco capas
El problema de «¿dónde toco esto?» se resuelve en el nodo. Cada página vive en el Context como un nodo: una ficha cuyo frontmatter tiene cinco capas, cada una resolviendo una pregunta distinta:
- Identidad semántica — qué es este concepto y con quién se relaciona (su hiperónimo, sus hipónimos, sus hermanos). Es la capa que teje el knowledge graph.
- SEO + URL — su título, su descripción, su slug canónico, su
hreflang. Para que la encuentren las personas. - GEO — la pregunta que responde y la respuesta corta y extraíble. Para que la citen ChatGPT, Perplexity o las AI Overviews.
- Sitemap técnico — prioridad, frecuencia de cambio, idiomas.
- Implementación — y aquí está la más útil en el día a día: los hot-paths, la ruta exacta de los archivos que hacen funcionar la página, más los componentes del design system que usa.
Gracias a los hot-paths no hace falta leer todo el repositorio para tocar una sección. Abro el nodo, leo su capa de implementación y voy directo al archivo correcto. Una IA hace lo mismo: encuentra el sitio a la primera, sin perderse entre carpetas. El nodo convierte «buscar dónde está esto» en «ya sé dónde está esto».
La sincronización bidireccional no es magia: es protocolo más validador
Aquí está la pregunta honesta: si el código y el Context viven en sitios distintos, ¿qué impide que vuelvan a divergir? La respuesta no es un demonio mágico corriendo en segundo plano. Son dos cosas mucho más simples:
- Protocolo. Cuando muevo o creo código, actualizo la capa de implementación del nodo en el mismo commit. No es un paso aparte que se posponga: es parte del cambio.
- Validador. Un script (
pnpm validate:context) comprueba que cadaruta-codigoy cada componente que declara un nodo existen de verdad. Si moví un archivo y olvidé actualizar el nodo, la validación falla.
Por eso es bidireccional: el nodo te dice dónde escribir el código (Context → código), y el validador te impide mentir si el código se movió y el nodo se quedó atrás (código → Context). Ninguna dirección depende de la buena memoria. El problema del envejecimiento no se resuelve con disciplina heroica, sino haciendo que la mentira rompa el build.
¿Enlaces o vectores? Para qué sirve cada uno
Cuando explico esto, la pregunta técnica que más me hacen es: ¿el grafo de conocimiento funciona con enlaces tipo Obsidian o con vectores (embeddings)? Hoy la respuesta es clara: enlaces, no vectores. Y conviene entender por qué, porque cada herramienta resuelve un problema distinto.
Las relaciones del Context son wikilinks ([[Otro término]]) en el frontmatter, que un script resuelve en relaciones tipadas y explícitas: es-un (hiperónimo ↑), tipo-de (hipónimo ↓), relacionado (↔). Un enlace tipado dice exactamente por qué dos conceptos se tocan. Un vector solo diría que están cerca, sin el motivo.
| Enlaces tipados (lo que uso) | Vectores / embeddings | |
|---|---|---|
| Qué afirman | «X es un tipo de Y», con el porqué | «X está cerca de Y», sin el porqué |
| Fuertes en | precisión y citabilidad | descubrimiento difuso |
| En git | una línea revisable y diffeable | opaco; hay que re-embeddear |
| Mejores para | la columna vertebral del grafo | «artículos parecidos», búsqueda semántica |
La conclusión defendible es enlaces primero: son deterministas, se revisan en un pull request como cualquier línea de código, y cada relación lleva su motivo —que la propia web muestra al decirte por qué un término es cercano a otro—. Los vectores son una capa futura útil para lo que los enlaces no cubren: enlazar un concepto mencionado con palabras distintas a su nombre. No es «ambos hoy»; es enlaces para la estructura, vectores cuando haga falta recall.
El design system: una sola fuente de componentes
La segunda capa resuelve el mismo problema de fondo —que las cosas se contradigan— pero en lo visual. Sin un design system, cada página reinventa sus botones y su color, y tarde o temprano dejan de parecerse entre sí. Con él, los tokens de marca —color, tipografía, espacios— y los componentes reutilizables viven en un único lugar. apps/web no inventa botones: los toma de ahí. Así, un cambio de marca se hace una vez en los tokens y se propaga a toda la web, sin recorrer página por página.
El propio diagrama de arriba es un ejemplo: no es un dibujo suelto, es el componente ds:integrations/flow del design system. El artículo usa las mismas piezas que describe.
En la práctica
Antes de cambiar un término del glosario abro su nodo, leo sus hot-paths y edito solo eso. Si muevo el código, actualizo la capa de implementación del nodo en el mismo commit. Sincronización bidireccional, sin excepciones.
Esto es, en el fondo, lo que resuelve Context Driven Development: pensar y construir dejan de ser dos fases separadas con un handoff en medio —ese punto donde la documentación se queda atrás— y se convierten en un mismo sistema, donde el blueprint, el design system y el código siempre cuentan la misma historia.
