Sistema de Documentación Autónomo Utilizando Bloques Delimitados para Cero Desviación

Un desarrollador en r/ClaudeAI compartió una solución para mantener documentación precisa en espacios de trabajo multiproyecto donde los agentes de codificación con IA como Claude Code olvidan el contexto entre sesiones. El sistema aborda problemas con 8 proyectos, 20 funciones Lambda, 42 claves API, 12 endpoints API y 19 variables de entorno donde el agente adivinaba nombres de funciones, editaba archivos incorrectos y perdía contexto.

El Sistema de Delimitadores

En lugar de pedirle a Claude que actualice la documentación después de la implementación, el desarrollador creó un script bash de 740 líneas que extrae datos estructurados directamente de los archivos fuente y los inyecta en CLAUDE.md mediante bloques de comentarios HTML delimitados. Cada CLAUDE.md tiene delimitadores que marcan las secciones generadas automáticamente:

## Funciones Serverless <!-- auto:lambdas generated="2026-03-26" source="infrastructure/lib/api-stack.ts" -->
| Función | Ruta | Memoria | Tiempo de espera |
|----------|-------|--------|---------|
| quote-save | /quotes/save | 256MB | 15s |
| quote-get | /quotes/get | 256MB | 15s |
...20 filas extraídas de la configuración de CDK...
<!-- /auto:lambdas -->

## Arquitectura <-- escrito a mano, nunca tocado por el script

Cómo Funciona

El script:

• Analiza los archivos fuente reales (CDK TypeScript, FastAPI Python, package.json, etc.)
• Extrae datos estructurados (nombres de funciones, rutas, variables de entorno, versiones de dependencias)
• Reemplaza todo lo que está entre los delimitadores
• Actualiza la fecha de generación para mostrar frescura
• Valida: verifica que cada nombre de Lambda tenga un archivo de controlador correspondiente, que cada variable de entorno exista en .env

Las secciones escritas a mano (descripciones de arquitectura, dificultades, contexto de lógica de negocio) viven fuera de los delimitadores y nunca se tocan.

Contenido Generado Automáticamente

• Herramienta de cotización (20 Lambdas): Inventario de Lambdas, pilas CDK, variables de entorno, recuentos de pruebas, dependencias de CDK TypeScript y package.json
• Panel de ventas (12 endpoints): Rutas API, lista de temas, dependencias de decoradores FastAPI, tipos TypeScript y requirements.txt
• Análisis de datos (42 Usuarios): Datos de usuario, dependencias del archivo de credenciales Python y requirements.txt
• 5 otros proyectos: Versiones de dependencias de package.json/requirements.txt

Sistema de Advertencia de Obsolescencia

Un gancho de sincronización de documentos (se activa después de cada edición de código) verifica la fecha de generación en cada delimitador. Si alguna sección tiene más de 7 días:

Advertencia: 3 secciones generadas automáticamente en agent-quoting-tool/CLAUDE.md están obsoletas (la más antigua: 2026-03-19).
Ejecutar: ./scripts/generate-inventory.sh quoting

Esto no es bloqueante — advierte pero nunca te impide trabajar. La verificación de obsolescencia se ejecuta junto con los ganchos existentes con la misma ventana de limitación de 10 minutos, sin sobrecarga adicional.

Detalles de Implementación

La configuración utiliza bash puro con grep/sed/awk/jq, cero dependencias. Comandos:

scripts/generate-inventory.sh all # Actualizar todo
scripts/generate-inventory.sh quoting # Solo un proyecto

El script hace una copia de seguridad de cada CLAUDE.md primero (una copia por día, por proyecto). El desarrollador señala que no se deben analizar AST desde bash — su analizador TypeScript es un bucle grep/sed línea por línea que funciona para archivos controlados pero sería frágil para TypeScript arbitrario.

Ideas Clave

Los delimitadores permiten que el contenido generado automáticamente y el escrito a mano coexistan en el mismo archivo. Claude lee todo el CLAUDE.md al inicio de la sesión y obtiene ambos: datos exactos extraídos Y contexto humano que no puede inferir del código. El desarrollador recomienda comenzar con las extracciones de mayor valor (inventarios de Lambda y tablas de variables de entorno que causan errores cuando se desvían) y señala que la advertencia de obsolescencia es más valiosa que la ejecución automática.

Todo el sistema tomó aproximadamente 3 horas en construirse (diseño, implementación, pruebas, primera ejecución).