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
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.
<pre>
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 12:
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 38:
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 46:
---
---


## 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 79:
## 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 91:
## 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 105:


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.
  -
</pre>

Revision as of 14:57, 22 November 2026

<pre> 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. - </pre>