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:

Mantiene el estado: fase actual, decisiones clave, mapa del proyecto, estado del backlog
Se automejora: cada vez que un agente detecta que le faltó contexto relevante o le sobró información obsoleta, lo corrige
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 operations.md.
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.md → La puesta al día de versión).

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

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).

Contenido mínimo

Qué es el proyecto: una frase
Versión de Argui: contra qué versión de la metodología corre el proyecto
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.

Plantilla

Ver CLAUDE.md.template para el punto de partida.