CLAUDE.md Habilidad Maestra (Crear/Actualizar/Mejorar)

--- name: claude-md-master description: Habilidad maestra para el ciclo de vida de CLAUDE.md - crear, actualizar, mejorar con contenido verificado del repositorio y soporte multimódulo. Úsala al crear o actualizar archivos CLAUDE.md. --- # Maestro de CLAUDE.md (Crear/Actualizar/Mejorar) ## Cuándo usar - El usuario pide crear, mejorar, actualizar o estandarizar archivos CLAUDE.md. ## Reglas principales - Incluir solo información verificada en el repositorio o configuración. - Nunca incluir secretos, tokens, credenciales o datos de usuario. - Nunca incluir instrucciones específicas de tareas o temporales. - Mantener conciso: raíz <= 200 líneas, módulo <= 120 líneas. - Usar viñetas; evitar prosa extensa. - Los comandos deben ser copiables y provenir de documentos/scripts/CI del repositorio. - Omitir secciones vacías; evitar relleno. ## Entradas obligatorias (analizar antes de generar) - Configuración de compilación/paquete relevante para la pila detectada (raíz + módulos). - Configuración de análisis estático usada en el repositorio (si está presente). - Estructura real de módulos y patrones de código fuente (escanea directorios/archivos reales). - Raíces de código fuente representativas por módulo para extraer: estructura de paquete/característica, tipos clave y anotaciones en uso. ## Descubrimiento (rápido + dirigido) 1. Localizar variantes existentes de CLAUDE.md: `CLAUDE.md`, `.claude.md`, `.claude.local.md`. 2. Identificar pila y puntos de entrada mediante lecturas mínimas: - `README.md`, `docs/*` relevantes - Archivos de compilación/paquete (ver referencias de pila) - Tiempo de ejecución/configuración: `Dockerfile`, `docker-compose.yml`, `.env.example`, `config/*` - CI: `.github/workflows/*`, `.gitlab-ci.yml`, `.circleci/*` 3. Extraer comandos solo si existen en scripts/configuración/documentos del repositorio. 4. Detectar estructura multimódulo: - Android/Gradle: leer includes de `settings.gradle` o `settings.gradle.kts`. - iOS: detectar múltiples objetivos/espacios de trabajo en `*.xcodeproj`/`*.xcworkspace`. - Si más de un módulo/objetivo tiene `src/` o configuración de compilación, planificar archivos CLAUDE.md de módulo. 5. Para cada candidato a módulo, leer su archivo de compilación + documentos mínimos para capturar propósito específico del módulo, puntos de entrada y comandos. 6. Escanear raíces de código fuente para: - Carpetas de paquete/característica de nivel superior y convenciones de capas. - Anotaciones/tipos clave en uso (según referencia de pila). - Convenciones de nomenclatura usadas en el código base. 7. Capturar flujos de trabajo/errores no obvios de documentos o patrones de código. Rendimiento: - Preferir listado de archivos + lecturas dirigidas. - Evitar lecturas de archivos completos cuando una sección o símbolo sea suficiente. - Omitir directorios grandes: `node_modules`, `vendor`, `build`, `dist`. ## Referencias específicas de pila (Patrón 2) Leer la referencia relevante solo cuando aparezcan señales de detección: - Android/Gradle → `references/android.md` - iOS/Xcode/Swift → `references/ios.md` - PHP → `references/php.md` - Go → `references/go.md` - React (web) → `references/react-web.md` - React Native → `references/react-native.md` - Rust → `references/rust.md` - Python → `references/python.md` - Java/JVM → `references/java.md` - Herramientas Node → `references/node.md` - .NET/C# → `references/dotnet.md` - Dart/Flutter → `references/flutter.md` - Ruby/Rails → `references/ruby.md` - Elixir/Erlang → `references/elixir.md` - C/C++/CMake → `references/cpp.md` - Otro/Desconocido → `references/generic.md` (respaldo cuando ninguna referencia específica coincide) Si se detectan múltiples pilas, leer múltiples referencias. Si no se reconoce ninguna pila, usar la referencia genérica. ## Política de salida multimódulo (obligatoria cuando se detecta) - Crear siempre un `CLAUDE.md` raíz. - Crear también `CLAUDE.md` dentro de cada raíz de módulo/objetivo significativo. - "Significativo" = tiene su propia configuración de compilación y `src/` (o equivalente). - Omitir directorios solo de herramientas como `buildSrc`, `gradle`, `scripts`, `tools`. - El archivo de módulo debe ser específico del módulo y evitar duplicación: - Incluir propósito, rutas clave, puntos de entrada, pruebas de módulo y comandos de módulo (si los hay). - Referenciar información compartida mediante `@/CLAUDE.md`. ## Política de CLAUDE.md de módulo de negocio (todas las pilas) Para directorios de lógica de negocio en monorepo (`src/`, `lib/`, `packages/`, `internal/`): - Crear `CLAUDE.md` para módulos con >5 archivos O README propio - Omitir directorios solo de utilidades: `Helper`, `Utils`, `Common`, `Shared`, `Exception`, `Trait`, `Constants` - No se requiere estructura en capas; proporcionar información del módulo independientemente de la arquitectura - Máximo 120 líneas por CLAUDE.md de módulo - Referenciar raíz mediante `@/CLAUDE.md` para arquitectura/patrones compartidos - Incluir: propósito, estructura, clases clave, dependencias, puntos de entrada ## Secciones de salida obligatorias (por CLAUDE.md de módulo) Incluir estas secciones si se detectan en el código base (omitir solo si no están presentes): - **Inventario de características/componentes**: listar directorios de nivel superior bajo la raíz de código fuente - **Módulos principales/compartidos**: directorios de código de utilidad, común o compartido - **Estructura de navegación/enrutamiento**: gráficos de navegación, rutas o enrutadores - **Patrón de capa de red/API**: clientes API, endpoints, envoltorios de respuesta - **Patrón de DI/inyección**: módulos, contenedores o configuración de inyección - **Archivos de compilación/configuración**: configuraciones específicas del módulo (proguard, manifiestos, etc.) Ver referencias específicas de pila para patrones exactos a detectar y reportar. ## Flujo de trabajo de actualización (debe seguirse) 1. Proponer solo adiciones dirigidas; mostrar diferencias por archivo. 2. Solicitar aprobación antes de aplicar actualizaciones: **Cursor IDE:** Usar la herramienta AskQuestion con estas opciones: - id: "approval" - prompt: "¿Aplicar estas actualizaciones de CLAUDE.md?" - options: [{"id": "yes", "label": "Sí, aplicar"}, {"id": "no", "label": "No, cancelar"}] **Claude Code (Terminal):** Mostrar los cambios propuestos y preguntar: "¿Apruebas estas actualizaciones? (sí/no)" Detenerse y esperar la respuesta del usuario antes de continuar. **Otros Entornos (Respaldo):** Si no hay una herramienta de pregunta estructurada disponible: 1. Mostrar los cambios propuestos claramente 2. Preguntar: "¿Apruebas estas actualizaciones? Responde 'sí' para aplicar o 'no' para cancelar." 3. Esperar confirmación explícita del usuario antes de continuar 3. Aplicar actualizaciones, preservando contenido personalizado. Si no existe CLAUDE.md, proponer un nuevo archivo para aprobación. ## Reglas de extracción de contenido (obligatorias) - Solo del código base: - Extraer: nombres de tipos/clases/anotaciones usados, patrones de ruta reales, convenciones de nomenclatura. - Nunca: valores codificados, secretos, claves API, lógica específica de negocio. - Nunca: fragmentos de código en reglas de Hacer/No Hacer. ## Verificación antes de escribir - [ ] Cada regla referencia tipos/rutas reales del código base - [ ] Sin ejemplos de código en secciones de Hacer/No Hacer - [ ] Los patrones coinciden con lo que realmente está en el código base (no desactualizado) ## Reglas de contenido - Incluir: comandos, resumen de arquitectura, rutas clave, pruebas, errores, peculiaridades de flujo de trabajo. - Excluir: mejores prácticas genéricas, información obvia, declaraciones no verificadas. - Usar importaciones `@ruta/al/archivo` para evitar duplicación. - El formato Hacer/No Hacer es opcional; mantener solo si ya se usa en el archivo. - Evitar ejemplos de código excepto comandos cortos copiables. ## Estrategia de archivo existente Detección: - Si existe `<!-- Generated by claude-md-editor skill -->` → ejecución posterior - De lo contrario → primera ejecución Primera ejecución + archivo existente: - Respaldar `CLAUDE.md` → `CLAUDE.md.bak` - Usar `.bak` como fuente y extraer solo información reutilizable y específica del proyecto - Generar un nuevo archivo conciso y agregar el marcador Ejecución posterior: - Preservar secciones y redacción personalizadas a menos que estén desactualizadas o incorrectas - Actualizar solo lo que entre en conflicto con el estado actual del repositorio - Agregar secciones faltantes solo si aportan valor real Nunca modificar `.claude.local.md`. ## Salida Después de las actualizaciones, imprimir un informe conciso: ``` ## Informe de Actualización de CLAUDE.md - /CLAUDE.md [CREADO | RESPALDADO+CREADO | ACTUALIZADO] - /<módulo>/CLAUDE.md [CREADO | ACTUALIZADO] - Respaldos: listar cualquier archivo `.bak` ``` ## Lista de verificación de validación - La descripción es específica e incluye términos de activación - Sin marcadores de posición restantes - Sin secretos incluidos - Los comandos son reales y copiables - Regla de informe primero respetada - Referencias a un nivel de profundidad