Generador de CLAUDE.md
Lee el código base. Escribe un CLAUDE.md que le diga a Claude exactamente lo que necesita: ni más, ni menos.
Regla crítica: Un buen CLAUDE.md tiene menos de 100 líneas. Contiene únicamente información que Claude no puede deducir al leer el código por sí mismo. No escribas el archivo automáticamente: siempre muestra el borrador y espera la aprobación del usuario primero.
Regla de fragmentos de código: Nunca incluyas ejemplos de código en línea en el CLAUDE.md. En su lugar, usa referencias como archivo.ts:42. El código en el CLAUDE.md desperdicia tokens y se vuelve obsoleto.
Paso 1: Detectar Modo
Determina cuál de los tres modos ejecutar:
create: No existe un CLAUDE.md. Escríbelo desde cero. update: Existe un CLAUDE.md. Mejóralo sin descartar contenido personalizado. audit: Puntúa todos los archivos CLAUDE.md del proyecto con una nota A-F y genera un informe de calidad. Si el usuario dice "auditar", "verificar", "revisar" o "calificar" mi CLAUDE.md, ejecuta el modo de auditoría.
# Descubre TODAS las ubicaciones de CLAUDE.md
find . -name "CLAUDE.md" -not -path "*/node_modules/*" -not -path "*/.git/*" 2>/dev/null
ls ~/.claude/CLAUDE.md 2>/dev/null && echo "CLAUDE.md global encontrado"
ls .claude.local.md 2>/dev/null && echo ".claude.local.md encontrado"
Si se encuentran varios archivos CLAUDE.md: enuméralos. Pregunta: "Se encontró CLAUDE.md en [ubicaciones]. ¿Debo actualizar todos o solo [raíz]?"
Paso 2: Modo Auditoría (salta al Paso 3 si es create/update)
Para cada CLAUDE.md encontrado, asígnale una nota A-F usando esta rúbrica:
| Criterio | Qué verificar |
|---|---|
| Comandos | ¿Los comandos de compilación/prueba/verificación están presentes y se pueden ejecutar? |
| Arquitectura | ¿Se explica la estructura no obvia? |
| Patrones no obvios | ¿Se documentan detalles, archivos generados, orden de variables de entorno? |
| Concisión | ¿Tiene menos de 100 líneas? ¿Sin relleno evidente? |
| Actualización | ¿Los comandos siguen coincidiendo con el package.json/Makefile actual? |
| Capacidad de acción | ¿Puede un nuevo colaborador seguir esto sin hacer preguntas? |
Puntaje: 90-100 = A, 70-89 = B, 50-69 = C, 30-49 = D, 0-29 = F
Preséntalo como una tabla:
## Informe de Auditoría de CLAUDE.md
| Archivo | Puntaje | Nota | Principales Problemas |
|---------|---------|------|-----------------------|
| ./CLAUDE.md | 72 | B | Falta sección de detalles, comando de prueba desactualizado |
| ./packages/api/CLAUDE.md | 45 | D | Sin comandos, 340 líneas (demasiado largas), notas de arquitectura obsoletas |
**General: B (72/100)**
Problemas encontrados:
- ./packages/api/CLAUDE.md: 340 líneas: muy por encima del objetivo de 100 líneas
- ./packages/api/CLAUDE.md: El comando de prueba referencia `jest` pero package.json usa `vitest`
- ./CLAUDE.md: No hay sección de Detalles: falta la sección más valiosa
Después del informe, pregunta: "¿Quieres que arregle alguno de estos? (todos / solo raíz / especificar)"
Si el usuario dice que sí, continúa al Paso 3 para cada archivo que quiera arreglar.
Paso 3: Escanear la Estructura del Proyecto
# Tipo de proyecto y gestor de paquetes
ls package.json yarn.lock pnpm-lock.yaml bun.lockb requirements.txt pyproject.toml Cargo.toml go.mod 2>/dev/null
# Estructura de directorios de nivel superior
find . -maxdepth 2 -type d \
| grep -v node_modules | grep -v .git | grep -v __pycache__ \
| grep -v ".next" | grep -v dist | grep -v build | sort
Paso 4: Extraer Comandos de Compilación y Prueba
# Scripts de npm/yarn/pnpm/bun
cat package.json 2>/dev/null \
| python3 -c "
import sys, json
d = json.load(sys.stdin)
for name, cmd in d.get('scripts', {}).items():
print(f'{name}: {cmd}')
"
# Makefiles de Python, Go, Rust
cat Makefile 2>/dev/null | grep -E "^[a-z].*:" | head -20
# Go
cat go.mod 2>/dev/null | head -5
# Rust
cat Cargo.toml 2>/dev/null | grep -E "^\[" | head -10
Identifica los comandos exactos para: compilación, pruebas (todas), pruebas (un solo archivo/nombre), servidor de desarrollo, verificación lint/typecheck. Anota cualquier variable de entorno necesaria para ejecutarlos.
Paso 5: Encontrar Estilo de Código y Detalles
# Alias de importación (los más omitidos)
python3 -c "
import json, sys
try:
d = json.load(open('tsconfig.json'))
paths = d.get('compilerOptions', {}).get('paths', {})
if paths: print('Alias de importación:', json.dumps(paths, indent=2))
except: pass
" 2>/dev/null
# Variables de entorno requeridas
cat .env.example 2>/dev/null | grep -v "^#" | grep -v "^$" | head -20
# Archivos generados automáticamente (no deben editarse)
find . -path "*/node_modules" -prune -o -name "*.ts" -print \
| xargs grep -l "NO EDITAR\|@generated\|Generado por" 2>/dev/null | head -5
# Requisitos de configuración de pruebas
cat jest.config.js jest.config.ts vitest.config.ts 2>/dev/null | head -30
# Configuración de base de datos/migraciones
ls migrations/ prisma/ drizzle/ db/ 2>/dev/null
Qué cuenta como Detalle (incluye estos, omite todo lo demás):
- Archivos que son generados automáticamente (no deben editarse)
- Variables de entorno requeridas ANTES de ejecutar pruebas
- Mapeos de alias de importación no predeterminados
- Comandos de prueba que requieren un servicio en ejecución
- Peculiaridades intencionales conocidas (soluciones alternativas, no errores)
Paso 6: Generar Borrador de CLAUDE.md con Gemini
Compila todos los hallazgos y genera el borrador:
cat > /tmp/claude-md-request.json << 'ENDJSON'
{
"system_instruction": {
"parts": [{
"text": "Escribe un archivo CLAUDE.md para un proyecto de software. Reglas: (1) Menos de 100 líneas en total. (2) Incluye solo lo que Claude no puede deducir al leer el código. (3) Sin ejemplos de código en línea: usa referencias archivo.ts:42. (4) Secciones: Comandos, Estilo de Código (solo no predeterminados), Pruebas (solo si se necesita configuración), Detalles (obligatorio: lo que causa problemas). Omite cualquier sección que no tenga nada no obvio que decir. (5) Todos los comandos en bloques de código. (6) Orden preferido: Descripción General del Proyecto corta (1-2 oraciones, solo si no es obvia), Comandos, Arquitectura (solo estructura no obvia), Estilo de Código, Pruebas, Detalles. (7) No uses guiones largos. (8) Produce solo el contenido del CLAUDE.md, sin comentarios."
}]
},
"contents": [{
"parts": [{
"text": "ANALISIS_DEL_PROYECTO_AQUI"
}]
}],
"generationConfig": {
"temperature": 0.3,
"maxOutputTokens": 2048
}
}
ENDJSON
curl -s -X POST \
"https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=$GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d @/tmp/claude-md-request.json \
| python3 -c "import sys,json; d=json.load(sys.stdin); print(d['candidates'][0]['content']['parts'][0]['text'])"
Reemplaza ANALISIS_DEL_PROYECTO_AQUI con los hallazgos de los Pasos 3-5.
Para proyectos grandes (50+ archivos): Agrega un puntero @path al final del CLAUDE.md en lugar de detalles en línea:
## Referencia Extendida
Ver @docs/ai-context/architecture.md para el mapa completo de módulos.
Ver @docs/ai-context/testing.md para detalles de configuración de pruebas de integración.
Escribe los archivos referenciados en docs/ai-context/ con el detalle que no cabría en 100 líneas.
Paso 7: Auto-Verificación
Antes de presentar el borrador, verifica:
- Menos de 100 líneas (cuenta:
echo "$CONTENIDO" | wc -l) - Sin ejemplos de código en línea (solo referencias
archivo.ts:42o comandos shell) - Todos los comandos en bloques de código y ejecutables tal cual
- Sección de Detalles presente con al menos una entrada real
- Ninguna sección que solo diga cosas obvias a partir de los archivos
- Sin guiones largos
- Sin palabras de marketing o frases de relleno ("Este proyecto usa React para...")
- Alias de importación documentados si existen
- Archivos generados automáticamente marcados como "no editar" si existen
Si alguna verificación falla, revisa antes de presentar.
Paso 8: Presentar Borrador y Esperar Aprobación
Nunca escribas el archivo sin la aprobación del usuario.
Presenta el borrador en un bloque de código:
## Borrador de CLAUDE.md ([N] líneas)
[contenido completo del borrador]
---
¿Escribir esto en CLAUDE.md? (sí / editar primero / cancelar)
Si el usuario dice sí: escribe el archivo, luego confirma: "CLAUDE.md escrito ([N] líneas). Secciones: [lista de ## encabezados]."
Si el usuario dice editar primero: aplica sus cambios, vuelve a mostrar el borrador.
Si el usuario dice cancelar: detente.
Qué NO Incluir
- Versión del lenguaje/framework ("Este es un proyecto TypeScript")
- Cómo funciona el framework (Claude ya conoce React, FastAPI, etc.)
- Lista de todas las dependencias
- Reglas de estilo que el linter ya aplica (tamaño de sangría, estilo de comillas)
- Contenido que duplica el README.md
- Ejemplos de código en línea o fragmentos multilínea
- Cualquier cosa que sería idéntica para cualquier proyecto que use la misma pila