Idea principal

Alrededor de un producto de software gravita una familia de artefactos: la especificación, la maqueta de Figma, el changelog, la documentación de soporte, la documentación comercial. Ninguno dice lo que el producto hace hoy. Dicen lo que se quiso que hiciera, o lo que hacía en el momento en que alguien los escribió.

El código, en cambio, no puede equivocarse sobre el estado del producto: es ese estado. Un comportamiento presente en el repositorio es un comportamiento del producto, esté especificado o no; un comportamiento escrito en una especificación y ausente del repositorio no existe para nadie.

Eso no convierte al código en un buen soporte de lectura, ni en un sustituto de los demás artefactos. Solo fija una jerarquía de fiabilidad: si el repositorio y un documento se contradicen, es el documento el que se equivoca.

La misma clasificación vale para los artefactos de coordinación: un ticket y una especificación se desincronizan entre sí y respecto del producto desde la realización, y la única realidad duradera sigue siendo lo que se entrega: el código, el comportamiento observable y la documentación mantenida a partir de ellos.

Capa aportada por "El backlog no es un vertedero: es una herramienta de acción" (2026-06-03).

Dar fe del estado del producto no equivale a describirlo. El código establece cómo funciona el producto —los campos, los valores posibles, los tratamientos— y deja fuera lo que lo vuelve explotable: la regla enunciada en una frase, cuando su control está repartido en cinco archivos; los casos particulares de un objeto; las palabras que emplean los usuarios; el alcance de una noción cuando dos aplicaciones ponen un sentido distinto detrás del mismo término. Esas cuatro informaciones tampoco están en el mismo sitio: se reparten entre el núcleo del código, la base de datos, las pantallas y las traducciones. La jerarquía de fiabilidad sigue siendo cierta; no exime de escribir el sentido por encima.

Capa aportada por "Escribí la ontología de un producto. Tres veces creí haber terminado." (2026-08-11).

La jerarquía se comprueba también en el caso en que se lleva al extremo. En una herramienta interna construida sin especificación previa —alguien se lanza, construye, enseña, recibe peticiones, ajusta—, ningún documento ha descrito nunca la intención, y el producto funciona igualmente. Lo contrario no existe: no hay producto que funcione sin código. La especificación no desaparece por ello de todos los contextos, pero deja de poder afirmar que es, de forma duradera, la verdad del producto.

Capa aportada por "Cuatro días de vibe coding…" (2026-07-28).

Capa aportada por "Ontology-Driven Design: ¿y si la ontología se convirtiera en la red de seguridad del código generado por IA?" (2026-10-29). Cuando agentes de código modifican el software, la jerarquía se completa con un reparto de tres términos: el código da fe del comportamiento implementado, la ontología de negocio del sentido, y la intención de la petición de la razón por la que ese sentido puede cambiar. Dar fe del comportamiento no da la razón al código cuando contradice el modelo: una desviación introducida sin que ninguna petición la justifique es una deriva que hay que corregir, no una verdad nueva.

Por qué es importante

Esta jerarquía rara vez se enuncia, aunque se aplica todo el tiempo: un desarrollador que debe resolver un comportamiento ambiguo va a leer el código, no la especificación. Decirlo explícitamente cambia lo que se espera de los demás artefactos: se convierten en vistas, fechadas, y no en referencias.

También da un criterio para arbitrar un conflicto entre dos artefactos sin reunir a los autores: no se busca quién tiene razón, se mira el repositorio.

Matices y límites

El código dice lo que el producto hace, nunca por qué. La intención, el arbitraje, la restricción comercial que llevó a ese comportamiento no se leen en él, y esa parte sigue estando en los documentos y en los intercambios del proyecto.

La regla vale para el comportamiento entregado, no para el comportamiento deseado: un bug está en el código y forma parte igualmente de lo que habrá que cambiar.

Preguntas abiertas

• ¿Quién se da cuenta de que una intención de producto ha desaparecido, cuando el comportamiento que produjo sigue funcionando sin ella?