Advertising:

Prompt proyecto existente: Difference between revisions

From Zabbix-ES
Jump to navigation Jump to search
Created page with "Actúa como un Arquitecto de Software Senior especializado en ingeniería inversa y configuración de entornos para Claude Code. Tu objetivo es analizar en profundidad este repositorio —que hasta ahora no ha estado bajo tu control— para comprenderlo por completo y generar la base de memoria y documentación necesaria para que tú y futuros agentes podáis trabajar sobre él con precisión, sin repetir contexto y sin contradecir reglas, patrones o funcionalidades ya e..."
 
No edit summary
 
(2 intermediate revisions by the same user not shown)
Line 1: Line 1:
Actúa como un Arquitecto de Software Senior especializado en ingeniería inversa y configuración de entornos para Claude Code. Tu objetivo es analizar en profundidad este repositorio —que hasta ahora no ha estado bajo tu control— para comprenderlo por completo y generar la base de memoria y documentación necesaria para que tú y futuros agentes podáis trabajar sobre él con precisión, sin repetir contexto y sin contradecir reglas, patrones o funcionalidades ya existentes.
Actúa como un Arquitecto de Software Senior especializado en ingeniería inversa y optimización de contexto para Claude Code. Tu objetivo es analizar en profundidad este repositorio —que hasta ahora no ha estado bajo tu control— para comprenderlo por completo y generar una arquitectura de memoria jerárquica y documentación que permita a Claude y a futuros agentes trabajar con máxima precisión, mínimo consumo de tokens y sin contradecir reglas, patrones o funcionalidades ya existentes.


Sigue estrictamente estas fases y reglas.
Sigue estrictamente estas fases y reglas.
Line 11: Line 11:
3. **Cero suposiciones silenciosas:** Si algo no puede deducirse con certeza del repositorio (reglas de negocio implícitas, integraciones externas no documentadas, etc.), márcalo explícitamente como `[POR CONFIRMAR]`.
3. **Cero suposiciones silenciosas:** Si algo no puede deducirse con certeza del repositorio (reglas de negocio implícitas, integraciones externas no documentadas, etc.), márcalo explícitamente como `[POR CONFIRMAR]`.
4. **Higiene de seguridad:** NUNCA copies secretos, contraseñas, tokens, claves API ni valores reales de ficheros `.env` en ningún documento. Documenta únicamente los nombres de las variables y su propósito.
4. **Higiene de seguridad:** NUNCA copies secretos, contraseñas, tokens, claves API ni valores reales de ficheros `.env` en ningún documento. Documenta únicamente los nombres de las variables y su propósito.
5. **Optimización de contexto (Progressive Disclosure):** `CLAUDE.md` se carga en cada sesión. Mantenlo conciso, denso en valor y orientado a la acción (idealmente < 200 líneas), delegando los detalles extensos a ficheros específicos dentro de `docs/` y enlazándolos desde `CLAUDE.md`.
5. **Optimización extrema de contexto (Jerarquía y Carga Perezosa):**
  - El `CLAUDE.md` raíz se carga **siempre** en cada sesión: debe ser ultra-conciso (objetivo: < 120-150 líneas) y contener únicamente información global.
  - Aprovecha la carga bajo demanda de Claude Code creando ficheros **`CLAUDE.md` locales dentro de los directorios funcionales** de la aplicación para que su contexto solo se cargue cuando se trabaje en esa zona.
  - **Cero duplicación (DRY):** Nunca repitas en un `CLAUDE.md` local reglas que ya estén en el `CLAUDE.md` raíz, ni metas detalles de un submódulo en el `CLAUDE.md` raíz.
  - Delega diagramas extensos y referencias exhaustivas a `docs/`, enlazándolos solo donde sean relevantes.


---
---
Line 33: Line 37:
Al terminar la Fase 1, **detente** y preséntame:
Al terminar la Fase 1, **detente** y preséntame:
- Un resumen breve de lo que has entendido del proyecto.
- Un resumen breve de lo que has entendido del proyecto.
- La lista exacta de ficheros que vas a crear o actualizar.
- El **mapa propuesto de ficheros `CLAUDE.md`** (raíz + lista exacta de subdirectorios donde crearás `CLAUDE.md` locales y el motivo de cada uno).
- El resto de ficheros de documentación que crearás o actualizarás.
- Cualquier duda crítica (`[POR CONFIRMAR]`) que convenga aclarar antes de escribir.
- Cualquier duda crítica (`[POR CONFIRMAR]`) que convenga aclarar antes de escribir.


Line 40: Line 45:
---
---


## FASE 2: MEMORIA PARA CLAUDE Y AGENTES
## FASE 2: MEMORIA JERÁRQUICA PARA CLAUDE Y AGENTES


Crea la estructura de memoria siguiendo las mejores prácticas de Claude Code:
Crea la estructura de memoria en tres niveles de profundidad:


1. **`CLAUDE.md` (en la raíz del proyecto):**
### Nivel 1: `CLAUDE.md` raíz (Contexto global mínimo indispensable)
  - **Resumen del proyecto:** Qué hace y cuál es su propósito en 3-5 líneas.
Mantén este fichero por debajo de ~120-150 líneas. Debe contener únicamente:
  - **Comandos verificados:** Comandos exactos para instalar, compilar, ejecutar en local, lanzar tests, linters y desplegar (solo los que hayas verificado en el repo).
- **Resumen del proyecto:** Qué hace y cuál es su propósito en 3-5 líneas.
  - **Mapa de arquitectura:** Vista rápida de directorios y responsabilidades.
- **Comandos globales verificados:** Comandos exactos para instalar, compilar, ejecutar, lanzar tests, linters y desplegar (solo los verificados en el repo).
  - **Invariantes y reglas de no-contradicción:** Qué decisiones de diseño, contratos de API, formatos de datos o comportamientos NO deben alterarse sin aprobación explícita.
- **Mapa de módulos:** Tabla o lista compacta de directorios principales con su responsabilidad en una línea (indicando cuáles tienen su propio `CLAUDE.md`).
  - **Convenciones obligatorias:** Reglas de estilo, naming, manejo de errores y testing que cualquier agente debe respetar.
- **Invariantes globales:** Reglas críticas transversales que NUNCA deben romperse.
  - **Índice de contexto bajo demanda:** Punteros claros a los ficheros en `docs/` indicando *cuándo* debe leerlos un agente (ej. "Leer `docs/FLUJOS.md` antes de modificar endpoints o colas").
- **Convenciones globales:** Solo las que aplican a todo el repositorio.
  - *(Si el proyecto es un monorepo o tiene subproyectos muy independientes, evalúa crear `CLAUDE.md` locales en subdirectorios específicos solo si aportan reglas propias).*
- **Punteros a `docs/`:** Cuándo consultar `docs/ARQUITECTURA.md`, `docs/FLUJOS.md` o `docs/CONVENCIONES.md`.


2. **Memoria detallada en `docs/` (carga bajo demanda):**
### Nivel 2: `CLAUDE.md` locales por directorio (Carga perezosa / *Scoped Memory*)
  - **`docs/ARQUITECTURA.md`:** Diseño de componentes, interrelación entre módulos, gestión de estado, variables de entorno/configuración y diagramas en **Mermaid** (arquitectura y dependencias).
Crea un fichero `CLAUDE.md` dentro de **cada directorio funcional o módulo significativo** de la aplicación (por ejemplo: `src/api/CLAUDE.md`, `src/db/CLAUDE.md`, `internal/workers/CLAUDE.md`, `infra/CLAUDE.md`, `tests/CLAUDE.md`, etc.).
  - **`docs/FLUJOS.md`:** Flujos de entrada, procesamiento, salida y comunicación interna/externa, incluyendo diagramas de secuencia en **Mermaid** para los flujos críticos y manejo de errores.
- **Criterio de exclusión:** No crees `CLAUDE.md` en carpetas triviales, estáticas o de un solo fichero simple (ej. `assets/`, `images/`, `dist/`).
  - **`docs/CONVENCIONES.md`:** Patrones internos detectados, estructura de código, estándares de commits/PRs, deuda técnica conocida y "trampas" (*gotchas*) que un agente debe evitar.
- **Contenido de cada `CLAUDE.md` local (objetivo: < 80-100 líneas):**
  - **Propósito del directorio:** Qué responsabilidad exacta tiene este módulo.
  - **Ficheros clave:** Lista breve de los ficheros importantes de este directorio y su rol.
  - **Entradas, salidas y dependencias locales:** Cómo entra/sale la información en este módulo y con qué otros directorios interactúa.
  - **Variables y configuración local:** Variables de entorno, flags o estado que afectan específicamente a este directorio.
  - **Invariantes y *gotchas* locales:** Reglas específicas del módulo, efectos secundarios o trampas que un agente debe evitar al editar aquí.
  - **Comandos locales (si aplica):** Cómo testear o ejecutar únicamente este módulo.
 
### Nivel 3: Memoria detallada en `docs/` (Referencia profunda bajo demanda)
- **`docs/ARQUITECTURA.md`:** Diseño global de componentes, interrelación entre módulos, gestión de estado, variables de entorno/configuración y diagramas en **Mermaid** (arquitectura y dependencias).
- **`docs/FLUJOS.md`:** Flujos de entrada, procesamiento, salida y comunicación interna/externa, con diagramas de secuencia en **Mermaid** para los flujos críticos y manejo de errores.
- **`docs/CONVENCIONES.md`:** Patrones internos detallados, estructura de código, estándares de commits/PRs y deuda técnica conocida.


---
---
Line 62: Line 78:
## FASE 3: DOCUMENTACIÓN GENERAL (`README.md`)
## FASE 3: DOCUMENTACIÓN GENERAL (`README.md`)


Crea o actualiza el `README.md` en la raíz (si ya existe, preserva la información válida y actualiza lo obsoleto). Debe cubrir de forma clara y orientada a humanos:
Crea o actualiza el `README.md` en la raíz (preservando información válida y actualizando lo obsoleto). Orientado a humanos:
- Contexto del proyecto, objetivos y alcance (qué incluye y qué queda fuera de alcance).
- Contexto del proyecto, objetivos y alcance (qué incluye y qué queda fuera de alcance).
- Funcionalidades principales.
- Funcionalidades principales.
Line 74: Line 90:
## FASE 4: DOCUMENTACIÓN PARTICULAR DE CADA FICHERO
## FASE 4: DOCUMENTACIÓN PARTICULAR DE CADA FICHERO


Crea un catálogo estructurado en **`docs/REFERENCIA_FICHEROS.md`** (o una carpeta `docs/ficheros/` organizada por módulo si el proyecto supera los ~30 ficheros de código relevantes) que documente cada fichero significativo del proyecto (excluyendo archivos generados, `node_modules`, `vendor`, binarios o lockfiles):
Crea un catálogo exhaustivo en **`docs/REFERENCIA_FICHEROS.md`** (o una carpeta `docs/ficheros/` organizada por módulo si el proyecto supera los ~30 ficheros de código relevantes) que documente cada fichero significativo (excluyendo generados, `node_modules`, `vendor`, binarios o lockfiles):
- **Ruta y propósito:** Qué responsabilidad única cumple el fichero.
- **Ruta y propósito:** Responsabilidad única del fichero.
- **Entradas y salidas:** Parámetros, eventos, endpoints o datos que recibe y devuelve.
- **Entradas y salidas:** Parámetros, eventos, endpoints o datos que recibe y devuelve.
- **Dependencias e interrelaciones:** Qué módulos/servicios importa y quién depende de él.
- **Dependencias e interrelaciones:** Qué importa y quién depende de él.
- **Variables, constantes y configuración:** Variables de entorno, flags o estado relevante que utiliza.
- **Variables, constantes y configuración:** Variables de entorno, flags o estado relevante.
- **Efectos secundarios y notas críticas:** Escrituras en BBDD, llamadas externas, mutaciones de estado o precauciones al editarlo.
- **Efectos secundarios y notas críticas:** Escrituras en BBDD, llamadas externas, mutaciones de estado o precauciones al editarlo.
*(Nota: Esta documentación detallada vive en `docs/` para no inflar los `CLAUDE.md` locales, que solo deben contener resúmenes accionables y punteros a este catálogo si hace falta).*


---
---
Line 86: Line 104:


Antes de dar la tarea por terminada:
Antes de dar la tarea por terminada:
1. Verifica que todas las rutas de ficheros, símbolos y comandos citados en `CLAUDE.md`, `README.md` y `docs/` existen realmente en el repositorio.
1. Verifica que todas las rutas de ficheros, símbolos y comandos citados en los `CLAUDE.md`, `README.md` y `docs/` existen realmente en el repositorio.
2. Comprueba que no se ha filtrado ningún secreto ni credencial.
2. Audita la jerarquía de `CLAUDE.md`: comprueba que el raíz es compacto (< 150 líneas), que los `CLAUDE.md` locales no duplican información del raíz ni se contradicen entre sí, y que no se han creado en carpetas triviales.
3. Entrega un resumen final con:
3. Comprueba que no se ha filtrado ningún secreto ni credencial.
   - Ficheros creados/actualizados.
4. Entrega un resumen final con:
   - Árbol de ficheros creados/actualizados (destacando todos los `CLAUDE.md` generados y su tamaño aproximado en líneas).
   - Discrepancias detectadas entre la documentación antigua y el código real.
   - Discrepancias detectadas entre la documentación antigua y el código real.
   - Lista consolidada de puntos `[POR CONFIRMAR]` para que pueda validarlos.
   - Lista consolidada de puntos `[POR CONFIRMAR]` para que pueda validarlos.

Latest revision as of 14:59, 22 November 2026

Actúa como un Arquitecto de Software Senior especializado en ingeniería inversa y optimización de contexto para Claude Code. Tu objetivo es analizar en profundidad este repositorio —que hasta ahora no ha estado bajo tu control— para comprenderlo por completo y generar una arquitectura de memoria jerárquica y documentación que permita a Claude y a futuros agentes trabajar con máxima precisión, mínimo consumo de tokens y sin contradecir reglas, patrones o funcionalidades ya existentes.

Sigue estrictamente estas fases y reglas.


REGLAS DE ORO (OBLIGATORIAS)

  1. No modifiques código funcional: En esta tarea NO debes alterar lógica de negocio, configuraciones de producción ni código fuente ejecutable. Solo crearás o actualizarás ficheros de documentación y memoria.
  2. El código es la fuente de verdad: Si la documentación preexistente contradice al código actual, prevalece el código. Registra explícitamente cualquier discrepancia encontrada.
  3. Cero suposiciones silenciosas: Si algo no puede deducirse con certeza del repositorio (reglas de negocio implícitas, integraciones externas no documentadas, etc.), márcalo explícitamente como [POR CONFIRMAR].
  4. Higiene de seguridad: NUNCA copies secretos, contraseñas, tokens, claves API ni valores reales de ficheros .env en ningún documento. Documenta únicamente los nombres de las variables y su propósito.
  5. Optimización extrema de contexto (Jerarquía y Carga Perezosa):
    • El CLAUDE.md raíz se carga siempre en cada sesión: debe ser ultra-conciso (objetivo: < 120-150 líneas) y contener únicamente información global.
    • Aprovecha la carga bajo demanda de Claude Code creando ficheros CLAUDE.md locales dentro de los directorios funcionales de la aplicación para que su contexto solo se cargue cuando se trabaje en esa zona.
    • Cero duplicación (DRY): Nunca repitas en un CLAUDE.md local reglas que ya estén en el CLAUDE.md raíz, ni metas detalles de un submódulo en el CLAUDE.md raíz.
    • Delega diagramas extensos y referencias exhaustivas a docs/, enlazándolos solo donde sean relevantes.

FASE 1: DESCUBRIMIENTO Y ANÁLISIS PROFUNDO (SOLO LECTURA)

Antes de escribir o modificar ningún fichero, explora el repositorio de forma sistemática:

  1. Inventario y estructura: Mapea el árbol de directorios, identifica el stack tecnológico, gestores de dependencias, ficheros de infraestructura (Docker, CI/CD, IaC, Makefiles, scripts) y puntos de entrada (main, index, app, CLI, etc.).
  2. Historial reciente: Revisa el git log reciente (últimos 20-30 commits si existe repositorio Git) para detectar áreas activas, estilo de commits y decisiones recientes.
  3. Flujos de datos y comunicación: Traza los flujos principales de principio a fin:
    • Entradas (HTTP/API, CLI, colas, webhooks, ficheros, cron, eventos).
    • Procesamiento y transformaciones clave.
    • Salidas y persistencia (bases de datos, APIs externas, sistemas de ficheros, notificaciones).
    • Comunicación entre módulos internos.
  4. Componentes y variables: Identifica cómo se interrelacionan los módulos/clases/servicios, cómo fluye el estado, qué variables de entorno y ficheros de configuración controlan el comportamiento y qué dependencias críticas existen.
  5. Convenciones internas e invariantes: Detecta patrones de diseño, convenciones de nombres, gestión de errores, logging, estructura de tests y reglas críticas que no deben romperse (invariantes).
  6. Documentación preexistente: Lee cualquier README, CHANGELOG, docs/, comentarios de arquitectura o wikis internas para integrarlos y detectar qué está vigente y qué está obsoleto.

PUNTO DE CONTROL (OBLIGATORIO)

Al terminar la Fase 1, detente y preséntame:

  • Un resumen breve de lo que has entendido del proyecto.
  • El mapa propuesto de ficheros CLAUDE.md (raíz + lista exacta de subdirectorios donde crearás CLAUDE.md locales y el motivo de cada uno).
  • El resto de ficheros de documentación que crearás o actualizarás.
  • Cualquier duda crítica ([POR CONFIRMAR]) que convenga aclarar antes de escribir.

Espera mi confirmación antes de ejecutar las Fases 2 a 5.


FASE 2: MEMORIA JERÁRQUICA PARA CLAUDE Y AGENTES

Crea la estructura de memoria en tres niveles de profundidad:

Nivel 1: CLAUDE.md raíz (Contexto global mínimo indispensable)

Mantén este fichero por debajo de ~120-150 líneas. Debe contener únicamente:

  • Resumen del proyecto: Qué hace y cuál es su propósito en 3-5 líneas.
  • Comandos globales verificados: Comandos exactos para instalar, compilar, ejecutar, lanzar tests, linters y desplegar (solo los verificados en el repo).
  • Mapa de módulos: Tabla o lista compacta de directorios principales con su responsabilidad en una línea (indicando cuáles tienen su propio CLAUDE.md).
  • Invariantes globales: Reglas críticas transversales que NUNCA deben romperse.
  • Convenciones globales: Solo las que aplican a todo el repositorio.
  • Punteros a docs/: Cuándo consultar docs/ARQUITECTURA.md, docs/FLUJOS.md o docs/CONVENCIONES.md.

Nivel 2: CLAUDE.md locales por directorio (Carga perezosa / Scoped Memory)

Crea un fichero CLAUDE.md dentro de cada directorio funcional o módulo significativo de la aplicación (por ejemplo: src/api/CLAUDE.md, src/db/CLAUDE.md, internal/workers/CLAUDE.md, infra/CLAUDE.md, tests/CLAUDE.md, etc.).

  • Criterio de exclusión: No crees CLAUDE.md en carpetas triviales, estáticas o de un solo fichero simple (ej. assets/, images/, dist/).
  • Contenido de cada CLAUDE.md local (objetivo: < 80-100 líneas):
    • Propósito del directorio: Qué responsabilidad exacta tiene este módulo.
    • Ficheros clave: Lista breve de los ficheros importantes de este directorio y su rol.
    • Entradas, salidas y dependencias locales: Cómo entra/sale la información en este módulo y con qué otros directorios interactúa.
    • Variables y configuración local: Variables de entorno, flags o estado que afectan específicamente a este directorio.
    • Invariantes y gotchas locales: Reglas específicas del módulo, efectos secundarios o trampas que un agente debe evitar al editar aquí.
    • Comandos locales (si aplica): Cómo testear o ejecutar únicamente este módulo.

Nivel 3: Memoria detallada en docs/ (Referencia profunda bajo demanda)

  • docs/ARQUITECTURA.md: Diseño global de componentes, interrelación entre módulos, gestión de estado, variables de entorno/configuración y diagramas en Mermaid (arquitectura y dependencias).
  • docs/FLUJOS.md: Flujos de entrada, procesamiento, salida y comunicación interna/externa, con diagramas de secuencia en Mermaid para los flujos críticos y manejo de errores.
  • docs/CONVENCIONES.md: Patrones internos detallados, estructura de código, estándares de commits/PRs y deuda técnica conocida.

FASE 3: DOCUMENTACIÓN GENERAL (README.md)

Crea o actualiza el README.md en la raíz (preservando información válida y actualizando lo obsoleto). Orientado a humanos:

  • Contexto del proyecto, objetivos y alcance (qué incluye y qué queda fuera de alcance).
  • Funcionalidades principales.
  • Requisitos previos y dependencias.
  • Instalación, configuración (tabla de variables de entorno sin valores sensibles) y puesta en marcha.
  • Uso básico y ejemplos.
  • Estructura general del proyecto y enlaces a la documentación detallada en docs/.

FASE 4: DOCUMENTACIÓN PARTICULAR DE CADA FICHERO

Crea un catálogo exhaustivo en docs/REFERENCIA_FICHEROS.md (o una carpeta docs/ficheros/ organizada por módulo si el proyecto supera los ~30 ficheros de código relevantes) que documente cada fichero significativo (excluyendo generados, node_modules, vendor, binarios o lockfiles):

  • Ruta y propósito: Responsabilidad única del fichero.
  • Entradas y salidas: Parámetros, eventos, endpoints o datos que recibe y devuelve.
  • Dependencias e interrelaciones: Qué importa y quién depende de él.
  • Variables, constantes y configuración: Variables de entorno, flags o estado relevante.
  • Efectos secundarios y notas críticas: Escrituras en BBDD, llamadas externas, mutaciones de estado o precauciones al editarlo.

(Nota: Esta documentación detallada vive en docs/ para no inflar los CLAUDE.md locales, que solo deben contener resúmenes accionables y punteros a este catálogo si hace falta).


FASE 5: VERIFICACIÓN FINAL

Antes de dar la tarea por terminada:

  1. Verifica que todas las rutas de ficheros, símbolos y comandos citados en los CLAUDE.md, README.md y docs/ existen realmente en el repositorio.
  2. Audita la jerarquía de CLAUDE.md: comprueba que el raíz es compacto (< 150 líneas), que los CLAUDE.md locales no duplican información del raíz ni se contradicen entre sí, y que no se han creado en carpetas triviales.
  3. Comprueba que no se ha filtrado ningún secreto ni credencial.
  4. Entrega un resumen final con:
    • Árbol de ficheros creados/actualizados (destacando todos los CLAUDE.md generados y su tamaño aproximado en líneas).
    • Discrepancias detectadas entre la documentación antigua y el código real.
    • Lista consolidada de puntos [POR CONFIRMAR] para que pueda validarlos.