El CLAUDE.md vivo

El paso F0.1 de Argui — antes que cualquier otra cosa — es establecer un CLAUDE.md que evoluciona con el proyecto.

Qué es (y qué no es)

El CLAUDE.md es la memoria operativa del proyecto: el documento que cualquier agente lee primero para entender dónde está parado.

El CLAUDE.md no contiene el paso a paso de la metodología. La metodología se sigue desde su propia documentación (este repositorio); intentar embeber el workflow completo en el CLAUDE.md lo infla y queda obsoleto en cuanto el proyecto entra al ciclo iterativo. El CLAUDE.md referencia en qué paso está el proyecto — no re-explica el proceso.

Tres propiedades obligatorias:

1. Mantiene el estado: fase actual, decisiones clave, mapa del proyecto, estado del backlog
2. Se automejora: cada vez que un agente detecta que le faltó contexto relevante o le sobró información obsoleta, lo corrige
3. Conserva un tamaño pequeño: solo la información relevante para la fase actual

Directivas operativas

Además del estado, el CLAUDE.md declara las directivas del proyecto — reglas que todos los agentes obedecen siempre. La directiva mínima de Argui:

• Los agentes no ejecutan git. Proponen ramas, commits (Conventional Commits) y PRs; el humano revisa, confirma y ejecuta. El control de lo que entra al historial es humano — es parte del principio “el humano aprueba, no supervisa”. La cadencia (rama por unidad de trabajo, commit al cerrar cada paso/fase, PR al archivar un change) y el resto de la disciplina operativa están en Operaciones.
• Idioma de los artefactos: decisión del proyecto. El proyecto declara en fase 0 en qué idioma se escriben sus artefactos —PRDs (Product Requirements Document), prosa de los agentes, mensajes de commit, identificadores y comentarios de código, strings de UI (interfaz de usuario)— y todos los agentes lo respetan. Es independiente del idioma de la metodología: Argui se documenta en un idioma, pero cada proyecto produce en el que pida su contexto (cliente, equipo, mercado).
• Versión de Argui. El proyecto declara contra qué versión de la metodología fue construido o actualizado (Argui vX.Y), para poder ponerlo al día cuando la metodología evolucione (ver Brownfield → La puesta al día de versión).
• Versión de OpenSpec. El proyecto declara la versión fijada en F0.2 — la que el package.json instala y contra la que el schema argui está forkeado. No es repetir el lockfile: el lockfile dice qué está instalado y el CLAUDE.md dice contra qué versión se forkeó y se validó el ciclo. Son dos hechos distintos, y su divergencia es la señal — alguien subió la dependencia sin correr la receta de re-validación. Por eso la línea se actualiza al re-validar el ciclo, no al instalar (ver OpenSpec → Mantenimiento al subir de versión). Es también el dato que un agente necesita en sesión: el comportamiento de los comandos /opsx:* depende de esa versión.
• El proyecto no usa la memoria del asistente. Con memoria se nombra acá el almacén propio de la herramienta, fuera del repositorio —no este archivo, que en algunas herramientas también se llama así—. Un hecho del proyecto que solo vive ahí es un hecho que el proyecto no tiene: la memoria es por usuario y por máquina (no se versiona, no se revisa en un PR —Pull Request—, no viaja al equipo ni a otra herramienta) y es invisible (una memoria vieja y equivocada sigue influyendo sin aparecer en ningún diff). Lo que sería una memoria va como nota operativa en el CLAUDE.md, con el mismo tope y la misma poda que el resto del archivo. La frontera: las preferencias personales del desarrollador —cómo le gusta que le hablen, en qué idioma— pueden seguir en la memoria de su herramienta; los hechos del proyecto, no. La memoria no es mala en sí; es mala como memoria de un proyecto compartido.

Cada proyecto agrega las suyas (no tocar producción, no instalar dependencias sin aprobación, etc.).

Lo que no va: la historia

El modo de falla más común del CLAUDE.md es que acumula un registro de lo que se hizo, porque un agente que actualiza estado tiende a anexar en vez de reemplazar. De fondo hay un choque de naturalezas: un registro es append-only; el CLAUDE.md es un snapshot del presente. Los dos no caben en el mismo archivo — uno crece para siempre y el otro tiene que caber en la cabeza de cada agente que abre el proyecto.

La regla, en una frase: el CLAUDE.md no lleva historia. Si una línea empieza con una fecha, no va ahí.

No hace falta un archivo de historial nuevo: los logs ya existen y cada tipo de historia tiene el suyo.

Por qué el tamaño importa

Un CLAUDE.md grande es un CLAUDE.md que no se lee completo y que consume contexto que los agentes necesitan para trabajar. La regla práctica: si una información ya no afecta las decisiones de la fase actual, sale del CLAUDE.md (puede vivir en otra parte de la documentación).

El tope es un número, no un adjetivo. “Pequeño” no se verifica y no se cumple: el proyecto declara un tope —200 líneas por defecto, ajustable— y el pipeline lo chequea con un wc -l que falla el build al pasarse. Es el principio transversal de Estándares aplicado al archivo que más se degrada en silencio: avisa el día que pasa, no cinco ítems después. La auditoría periódica queda como red de respaldo — su foco de consumo de tokens ya nombra un CLAUDE.md inflado entre los artefactos que degradan la eficiencia.

Contenido mínimo

• Qué es el proyecto: una frase
• Versión de Argui: contra qué versión de la metodología corre el proyecto
• Versión de OpenSpec: la fijada en F0.2, contra la que el schema argui está validado
• Fase actual: en qué paso del workflow está el proyecto y qué falta para avanzar
• Directivas operativas: las reglas que aplican siempre
• Stack y decisiones clave: las decisiones arquitectónicas que afectan el trabajo diario
• Dónde está cada cosa: rutas a PRDs, prototipo, backlog, estándares, agentes
• Reglas de la fase actual: qué se puede hacer y qué no en este momento del proceso
• Estado del backlog: qué está hecho, qué está en curso, qué sigue

Mecanismo de actualización

El CLAUDE.md se actualiza obligatoriamente en estos momentos:

• Al completar cada paso del workflow (cambia la fase)
• En la fase archive de cada ciclo OpenSpec (cambia el progreso)
• Cuando un agente detecta información obsoleta o faltante (automejora)

La actualización la ejecuta un agente mantenedor económico (haiku) — resumir y podar es trabajo mecánico.

Reemplaza, no anexa. Actualizar el CLAUDE.md es reescribir la sección que cambió, no agregarle una entrada debajo. Si al actualizar aparece información con fecha, va al log que le corresponde (arriba) y no al archivo. Si el archivo pasó el tope declarado, se poda antes de seguir.

Plantilla

Ver CLAUDE.md para el punto de partida.