20260915 #6 — Dos lectores, dos documentos

Hoy en el repo de Matching hay dos archivos llamados README.md con la misma hora de modificación: 2026-08-18 04:43:43 el de la raíz, 04:43:24 el de la carpeta del código. Hace casi un mes que nadie los toca. Al lado, en el mismo repositorio, CLAUDE.md tiene 886 líneas y su última edición es del 10 de septiembre — veintitrés días después de esos dos README. Tres documentos en el mismo repo: dos congelados, uno vivo. La diferencia no es casualidad. Es quién los lee.

Por qué dos y no uno

La única sesión documentada de ese 18 de agosto cerró a las 04:48 sin registrar a qué hora había arrancado. El objetivo, una sola línea: "Crear el README.txt del proyecto". El pedido original era doble —un README "para el asistente general" y otro dentro de la carpeta del código— aunque ni siquiera acerté el nombre de esa carpeta, y en el camino se aclaró que ambos debían ser .md y no .txt. El segundo reemplazó directo el boilerplate que traía Vite por defecto, sin convivir con nada aparte.

Lo que quedó en cada uno no es simétrico, es complementario. El de la raíz es una guía para quien retoma trabajo en el repo, persona o asistente: estructura de carpetas, agentes, skills, reglas de backlog, sistema de sesiones, sistema de tickets. El otro es la guía del producto en sí: stack (React 19, Vite 8, Supabase), setup, scripts, variables de entorno, deploy. Esa misma exploración dejó, de paso, dos hallazgos anotados al backlog fuera de alcance —la referencia de stack desactualizada y una carpeta de costos duplicada—, hoy los dos resueltos.

Lo que envejeció y lo que no

El README del código todavía dice que el deploy a producción "está en estado blocked" y que no hay que asumir que la app ya está desplegada. El deploy real ocurrió el 22 de agosto —está en el changelog, con URL de Vercel y todo— así que ese archivo lleva 24 días afirmando algo que dejó de ser cierto el mismo mes en que se escribió. La tabla de agentes del README de la raíz tampoco resistió: lista seis, la carpeta de agentes tiene hoy doce archivos, y uno de esos seis ya ni vive ahí — el de costos pasó a nivel de usuario, fuera del repo.

Lo que no envejeció es tan revelador como lo que sí. Los dos punteros del README raíz a secciones de CLAUDE.md siguen resolviendo hoy: la sección de routing de agentes y la de convención de nombres de sesión están donde el README dice que están. La estructura de carpetas que describe sigue existiendo tal cual. Y la afirmación de que no hay .claude/skills/ ni .claude/commands/ en el repo —los skills son globales del usuario— sigue siendo cierta. Lo que se pudrió fueron los estados: un ticket, un conteo de archivos. Lo que aguantó fueron los punteros y las convenciones.

Ese mismo 18 de agosto el changelog del proyecto registra seis cambios de producto: landing pública, asistente guiado de matching, vista de candidatos, descripción introductoria, buscador de temas, y el rename de "Materia" a Área en todo el stack. Ninguna sesión los documenta. El día que escribí cómo se documenta el repo es, también, el día del que menos quedó documentado.

Lo que quedó

La convención sobrevivió aunque los archivos no. El molde que uso para cada proyecto nuevo sigue trayendo los dos como plantilla: 391 líneas la de CLAUDE.md, 137 la del README.md. De los doce proyectos que tengo hoy, los doce tienen README.md y diez tienen CLAUDE.md. La separación por audiencia ganó; mantenerla al día en cada proyecto, no. ¿Cuál de tus dos documentos está hoy al día, y qué te dice eso sobre quién lo está leyendo?

Tags: documentación · CLAUDE.md · README · dos audiencias · deuda de documentación