jimweller/documenter-plugin

Actualizar Documentación del Proyecto

Dos responsabilidades:

1. CLAUDE.md — resumen conciso del proyecto (siempre se carga)
2. .llmdocs/ — documentos detallados por concepto (se cargan bajo demanda). Todos los archivos aquí son documentos de diseño persistentes.

---

1. CLAUDE.md — El Mapa

Alcance

Encuentra todos los directorios CLAUDE.md y .llmdocs/ en el proyecto y actualiza cada uno. Presta atención a las capas de subcarpetas, alcance y contextos acotados. No filtres conceptos entre documentos en diferentes capas. Cada CLAUDE.md y .llmdocs/ cubre su propio nivel de directorio y los inferiores, nunca las preocupaciones del nivel superior.

Si el usuario proporcionó orientación o áreas de enfoque específicas, aplica ese contexto al decidir qué documentos actualizar y qué enfatizar.

Recopilar Contexto

Nunca ejecutes git directamente. El script base que viene con este plugin cubre todo lo que este skill necesita de git. Ejecuta cada comando desde la raíz del repositorio y escribe la ruta completa del script cada vez, porque las variables de shell no persisten entre comandos.

Comienza con el plan. Encuentra cada CLAUDE.md y su .llmdocs/, incluidos los archivos requeridos que aún no existen, resuelve la línea base de cada documento, lista qué ha cambiado desde esa línea base y dice qué hacer con cada documento. Cuando la guía del usuario nombre directorios en los que enfocarse, pásalos después de llmdocs. De lo contrario, no pases nada.

bash "${CLAUDE_SKILL_DIR}/../../scripts/doc-baseline.sh" plan llmdocs [<focus-dir>...]

El plan imprime un bloque por acción.

• ## update nombra una línea base, un alcance y los documentos que lo comparten, seguido de los commits, el diff stat y el estado desde esa línea base. Actualiza estos documentos. Un documento al que los cambios no afectan mantiene su contenido.
• ## new lista documentos para escribir a partir del código actual. No necesitan historial.
• ## unchanged y ## outside the focus listan documentos que deben dejarse exactamente como están.

head none significa que el repositorio no tiene commits. Cada documento es nuevo.

Para un bloque de actualización, cuenta los archivos en su stat. Si son más de 20, omite el diff completo y lee los archivos modificados directamente. Si son 20 o menos, lee el diff. Los archivos no rastreados, marcados con ??, no aparecen en ningún diff, así que léelos directamente de todos modos. El alcance puede ser el alcance del bloque o un solo archivo, porque es un pathspec de git.

bash "${CLAUDE_SKILL_DIR}/../../scripts/doc-baseline.sh" diff <sha> <scope>

Luego, para cada par CLAUDE.md/.llmdocs/ con documentos que actualizar o escribir:

1. Lee el CLAUDE.md actual y cada archivo en .llmdocs/ (si existen)
2. Explora el codebase en ese nivel de directorio y los inferiores
3. Revisa el historial de la conversación en busca de decisiones, cambios o lecciones aprendidas relevantes
4. Usa los cambios y el contexto de la conversación para identificar qué cambió. Los llmdocs son una especificación del estado actual, no un registro de cambios, no un registro de decisiones, no un registro histórico. Nunca registres información histórica o decisiones tomadas, solo la especificación tal como está en el momento de escribir los llmdocs.

Escribir/Actualizar CLAUDE.md

Objetivo: menos de 500 líneas. Cada línea debe ganarse su lugar.

# <Nombre>

<1-2 líneas de propósito de este directorio/componente>

## Stack

<lista con viñetas: lenguaje, frameworks, dependencias clave relevantes para este nivel>

## Layout

<directorios clave y lo que contienen en este nivel>

## Comandos

<build, test, lint, deploy — solo comandos>

## Convenciones

<estilo, nomenclatura, patrones — solo lo que previene errores>

## Conceptos Clave

<términos del dominio, lógica de negocio que Claude debe conocer en este nivel>

## Documentos LLM

Documentos detallados en `.llmdocs/`:

- @.llmdocs/architecture.md — <descripción de 1 línea>
- @.llmdocs/data-model.md — <descripción de 1 línea>

Reglas de CLAUDE.md

• SIN explicaciones verbosas — Claude infiere
• SIN duplicar contenido de .llmdocs/ — solo referenciar con descripción corta
• La sección ## Documentos LLM DEBE listar todos los archivos .llmdocs/ con una descripción de 1 línea cada uno
• Un CLAUDE.md que lista sus archivos .llmdocs/ bajo ## Docs es anterior al encabezado actual. Renombra ese encabezado a ## Documentos LLM cada vez que actualices el archivo
• Conserva las instrucciones personalizadas existentes (flujo de trabajo de git, variables de entorno, etc.)
• Elimina contenido solo cuando el código lo contradiga, y nombra cada eliminación en el resumen
• Cuando el código elimine una función, bandera o módulo, busca en cada documento de este nivel su nombre, luego relee cada acierto y la línea de propósito de cada documento para una descripción en lenguaje natural de lo mismo. Eliminar el nombre de un documento no es suficiente

grep -rn '<nombre eliminado>' <dir>/CLAUDE.md <dir>/.llmdocs

• Nunca incluyas la línea de marcador en el texto que escribes o editas. finish la añade después de escribir. Al editar un documento que ya termina con uno, deja esa línea intacta
• Usa @.llmdocs/nombre-archivo.md para importar si un documento debe cargarse siempre

---

2. .llmdocs/ — El Territorio

Proceso

Un archivo de concepto más allá de los siete requeridos es tuyo para agregar, y el plan nunca lo nombra. finish lo sella de todos modos, junto con cada otro documento de este nivel creado durante la ejecución.

1. Evaluar: usa los bloques de actualización del plan para identificar qué documentos están afectados
2. Identificar: determina qué documentos existentes están afectados, o si se necesita un nuevo documento
3. Actualizar CLAUDE.md: asegúrate de que la sección ## Documentos LLM liste cualquier archivo de documento nuevo

Si no ha cambiado nada que justifique actualizaciones de documentación, dilo y continúa.

Ubicación

Usa la ruta que nombre la primera importación bajo el encabezado ## Documentos LLM de CLAUDE.md, o bajo ## Docs en un CLAUDE.md anterior a eso. De lo contrario, por defecto es .llmdocs/ en el nivel de directorio objetivo. CLAUDE.md y .llmdocs/ pueden existir en cualquier nivel de directorio del proyecto.

Estructura

Plana, 1 archivo por concepto. Los primeros 7 archivos son requeridos y siempre deben existir. testing.md se crea cuando el proyecto tiene un conjunto de pruebas y se omite cuando no tiene ninguno. Los archivos de concepto adicionales se crean según sea necesario.

.llmdocs/
  architecture.md    # Componentes, interacciones, flujo de datos (requerido)
  api.md             # Endpoints, solicitud/respuesta, autenticación, autorización (requerido)
  data-model.md      # Esquema, modelos, relaciones (requerido)
  deployment.md      # Proceso de despliegue, entornos (requerido)
  ops.md             # Runbooks, mantenimiento, resolución de problemas (requerido)
  observability.md   # Logs, métricas, trazas, health checks, dashboards, alertas (requerido)
  security.md        # Límites de confianza, manejo de secretos, authn/authz, modelo de amenazas (requerido)
  testing.md         # Diseño de pruebas, ejecutor, fixtures, cómo ejecutar la suite (cuando el proyecto tiene pruebas)
  <concept>.md       # Específico del dominio según sea necesario

Formato de Archivo de Documento

# <Concepto>

<propósito de 1 línea>

## <Sección>

<contenido: encabezados, tablas, bloques de código — sin párrafos de prosa>

Reglas de .llmdocs/

• Máximo 500 líneas por archivo — divide si es más grande
• Incluye rutas de archivo con referencias de línea donde sea útil (src/auth/login.ts:42)
• Actualiza los documentos existentes de forma incremental, no los reescribas desde cero
• Si un documento es preciso y no se ve afectado por los cambios recientes, deja su contenido intacto. finish aún actualiza su marcador.
• Precisión sobre cobertura: solo documenta lo que sea verificable desde el código
• observability.md contiene las señales que emite el sistema, y ops.md contiene las acciones que realiza un operador. Un endpoint de salud, un formato de log o una alerta pertenecen a observability.md. Un proyecto sin métricas ni trazas aún documenta su stdout, stderr y códigos de salida allí
• Nunca incluyas la línea de marcador en el texto que escribes o editas. finish la añade después de escribir. Un archivo de concepto que creas es la trampa aquí, porque cada archivo hermano que acabas de leer termina con uno. Copiar esa línea escribe un sha obsoleto que afirma que el documento fue verificado contra un commit que nunca vio. Termina un archivo nuevo en su última línea de contenido y deja que finish añada el marcador

---

3. Finalizar

Ejecuta finish, cada vez, incluso en una ejecución que no escribió nada. plan dejó un archivo de plan y solo finish lo elimina, por lo que una ejecución que omite finish deja estado para que la siguiente lo encuentre.

bash "${CLAUDE_SKILL_DIR}/../../scripts/doc-baseline.sh" finish llmdocs

Sella cada documento que el plan marcó como nuevo o actualizado, y cada documento creado desde el plan, como testing.md, con el HEAD que el plan verificó. El sello es una línea de marcador al final del documento, un comentario HTML que nombra ese commit. finish deja intactos los documentos no modificados y los documentos fuera del enfoque, y no sella nada cuando el repositorio no tiene commits. Salida 4 significa que falta un documento planificado. Escríbelo y ejecuta finish de nuevo.

• Nunca llames a stamp directamente y nunca escribas o edites la línea de marcador manualmente. finish la escribe.
• El marcador es metadato. La regla contra el registro de historial no se aplica a él.

---

4. Resumen de Salida

Después de ejecutar, genera este resumen. Completa cada línea desde la ejecución y escribe "ninguno" donde una lista esté vacía. En Sellados, copia las propias líneas de finish textualmente, una por documento. Nunca escribas un sha allí, y nunca añadas una palabra que finish no haya impreso.

Una oración reformulada para eliminar una capacidad es una eliminación. Nómbrala bajo Eliminados con la redacción que desapareció, incluso si la misma línea aún existe.

Ejemplo completo, de una ejecución donde el código eliminó el conteo de caracteres.

Archivos creados: ninguno
Archivos modificados: CLAUDE.md, .llmdocs/api.md
Secciones de CLAUDE.md agregadas, actualizadas o eliminadas: Conceptos Clave actualizados
Eliminados porque el código lo contradice:
- CLAUDE.md: "o caracteres" de la línea de propósito, y el concepto clave --chars
- .llmdocs/api.md: la fila count_chars
Sellados:
- sellado CLAUDE.md (marcador)
- sellado .llmdocs/api.md (marcador)

Cuando los cambios no justifiquen una actualización de documentación, escribe "no se necesitan cambios en la documentación" arriba del resumen.