deepinit

Habilidad Deep Init

Crea documentación AGENTS.md jerárquica y completa en todo el código base.

Concepto Principal

Los archivos AGENTS.md sirven como documentación legible por IA que ayuda a los agentes a entender:

• Qué contiene cada directorio
• Cómo se relacionan los componentes entre sí
• Instrucciones especiales para trabajar en esa área
• Dependencias y relaciones

Sistema de Etiquetado Jerárquico

Cada AGENTS.md (excepto la raíz) incluye una etiqueta de referencia al padre:

<!-- Parent: ../AGENTS.md -->

Esto crea una jerarquía navegable:

/AGENTS.md                          ← Raíz (sin etiqueta padre)
├── src/AGENTS.md                   ← <!-- Parent: ../AGENTS.md -->
│   ├── src/components/AGENTS.md    ← <!-- Parent: ../AGENTS.md -->
│   └── src/utils/AGENTS.md         ← <!-- Parent: ../AGENTS.md -->
└── docs/AGENTS.md                  ← <!-- Parent: ../AGENTS.md -->

Plantilla AGENTS.md

<!-- Parent: {ruta_relativa_al_padre}/AGENTS.md -->
<!-- Generated: {marca_de_tiempo} | Updated: {marca_de_tiempo} -->

# {Nombre del Directorio}

## Propósito
{Párrafo de una línea describiendo qué contiene este directorio y su rol}

## Archivos Clave
{Listar cada archivo significativo con una descripción de una línea}

| Archivo | Descripción |
|---------|-------------|
| `file.ts` | Breve descripción del propósito |

## Subdirectorios
{Listar cada subdirectorio con breve propósito}

| Directorio | Propósito |
|------------|-----------|
| `subdir/` | Qué contiene (ver `subdir/AGENTS.md`) |

## Para Agentes de IA

### Trabajando en Este Directorio
{Instrucciones especiales para agentes de IA al modificar archivos aquí}

### Requisitos de Prueba
{Cómo probar cambios en este directorio}

### Patrones Comunes
{Patrones de código o convenciones usadas aquí}

## Dependencias

### Internas
{Referencias a otras partes del código base de las que esto depende}

### Externas
{Paquetes/bibliotecas externas clave utilizadas}

<!-- MANUAL: Cualquier nota añadida manualmente debajo de esta línea se conserva al regenerar -->

Flujo de Ejecución

Paso 1: Mapear Estructura de Directorios

Task(subagent_type="explore", model="haiku",
  prompt="Lista todos los directorios de forma recursiva. Excluye: node_modules, .git, dist, build, __pycache__, .venv, coverage, .next, .nuxt")

Paso 2: Crear Plan de Trabajo

Genera elementos de tarea para cada directorio, organizados por nivel de profundidad:

Nivel 0: / (raíz)
Nivel 1: /src, /docs, /tests
Nivel 2: /src/components, /src/utils, /docs/api
...

Paso 3: Generar Nivel por Nivel

IMPORTANTE: Genera los niveles padres antes que los niveles hijos para garantizar que las referencias padre sean válidas.

Para cada directorio:

1. Leer todos los archivos del directorio
2. Analizar propósito y relaciones
3. Generar contenido AGENTS.md
4. Escribir archivo con la referencia padre adecuada

Paso 4: Comparar y Actualizar (si existe)

Cuando AGENTS.md ya existe:

1. Leer contenido existente
2. Identificar secciones:
   • Secciones generadas automáticamente (se pueden actualizar)
   • Secciones manuales (<!-- MANUAL --> preservadas)
3. Comparar:
   • ¿Se agregaron nuevos archivos?
   • ¿Se eliminaron archivos?
   • ¿Cambió la estructura?
4. Fusionar:
   • Actualizar contenido generado automáticamente
   • Preservar anotaciones manuales
   • Actualizar marca de tiempo

Paso 5: Validar Jerarquía

Después de la generación, ejecutar verificaciones de validación:

Verificación	Cómo Verificar	Acción Correctiva
Las referencias padre resuelven	Leer cada AGENTS.md, comprobar que la ruta <!-- Parent: --> existe	Corregir la ruta o eliminar huérfano
Sin AGENTS.md huérfanos	Comparar ubicaciones de AGENTS.md con la estructura de directorios	Eliminar archivos huérfanos
Integridad	Listar todos los directorios, verificar que tengan AGENTS.md	Generar archivos faltantes
Marcas de tiempo actuales	Comprobar fechas de <!-- Generated: -->	Regenerar archivos desactualizados

Patrón de script de validación:

# Encontrar todos los archivos AGENTS.md
find . -name "AGENTS.md" -type f

# Verificar referencias padre
grep -r "<!-- Parent:" --include="AGENTS.md" .

Delegación Inteligente

Tarea	Agente
Mapeo de directorios	explore
Análisis de archivos	architect
Generación de contenido	writer
Escritura de AGENTS.md	writer

Manejo de Directorios Vacíos

Al encontrarse con directorios vacíos o casi vacíos:

Condición	Acción
Sin archivos, sin subdirectorios	Omitir - no crear AGENTS.md
Sin archivos, tiene subdirectorios	Crear AGENTS.md mínimo solo con listado de subdirectorios
Solo archivos generados (*.min.js, *.map)	Omitir o AGENTS.md mínimo
Solo archivos de configuración	Crear AGENTS.md describiendo el propósito de configuración

Ejemplo de AGENTS.md mínimo para contenedores solo de directorios:

<!-- Parent: ../AGENTS.md -->
# {Nombre del Directorio}

## Propósito
Directorio contenedor para organizar módulos relacionados.

## Subdirectorios
| Directorio | Propósito |
|------------|-----------|
| `subdir/` | Descripción (ver `subdir/AGENTS.md`) |

Reglas de Paralelización

1. Directorios del mismo nivel: Procesar en paralelo
2. Diferentes niveles: Secuencial (padre primero)
3. Directorios grandes: Generar un agente dedicado por directorio
4. Directorios pequeños: Agrupar varios en un solo agente

Estándares de Calidad

Debe Incluir

• Descripciones precisas de archivos
• Referencias padre correctas
• Enlaces a subdirectorios
• Instrucciones para el agente de IA

Debe Evitar

• Texto genérico de relleno
• Nombres de archivo incorrectos
• Referencias padre rotas
• Omitir archivos importantes

Ejemplo de Salida

AGENTS.md Raíz

<!-- Generated: 2024-01-15 | Updated: 2024-01-15 -->

# mi-proyecto

## Propósito
Una aplicación web para gestionar tareas de usuario con funciones de colaboración en tiempo real.

## Archivos Clave
| Archivo | Descripción |
|---------|-------------|
| `package.json` | Dependencias y scripts del proyecto |
| `tsconfig.json` | Configuración de TypeScript |
| `.env.example` | Plantilla de variables de entorno |

## Subdirectorios
| Directorio | Propósito |
|------------|-----------|
| `src/` | Código fuente de la aplicación (ver `src/AGENTS.md`) |
| `docs/` | Documentación (ver `docs/AGENTS.md`) |
| `tests/` | Suites de pruebas (ver `tests/AGENTS.md`) |

## Para Agentes de IA

### Trabajando en Este Directorio
- Instalar siempre las dependencias después de modificar el manifiesto del proyecto
- Usar modo estricto de TypeScript
- Seguir las reglas de ESLint

### Requisitos de Prueba
- Ejecutar pruebas antes de confirmar
- Asegurar >80% de cobertura

### Patrones Comunes
- Usar exportaciones de barril (index.ts)
- Preferir componentes funcionales

## Dependencias

### Externas
- React 18.x - Framework de UI
- TypeScript 5.x - Seguridad de tipos
- Vite - Herramienta de construcción

<!-- MANUAL: Las notas personalizadas del proyecto se pueden agregar debajo -->

AGENTS.md Anidado

<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2024-01-15 | Updated: 2024-01-15 -->

# components

## Propósito
Componentes React reutilizables organizados por funcionalidad y complejidad.

## Archivos Clave
| Archivo | Descripción |
|---------|-------------|
| `index.ts` | Exportación de barril para todos los componentes |
| `Button.tsx` | Componente de botón principal |
| `Modal.tsx` | Componente de diálogo modal |

## Subdirectorios
| Directorio | Propósito |
|------------|-----------|
| `forms/` | Componentes relacionados con formularios (ver `forms/AGENTS.md`) |
| `layout/` | Componentes de diseño (ver `layout/AGENTS.md`) |

## Para Agentes de IA

### Trabajando en Este Directorio
- Cada componente tiene su propio archivo
- Usar módulos CSS para estilos
- Exportar mediante index.ts

### Requisitos de Prueba
- Pruebas unitarias en el subdirectorio `__tests__/`
- Usar React Testing Library

### Patrones Comunes
- Interfaces de props definidas encima del componente
- Usar forwardRef para componentes que exponen el DOM

## Dependencias

### Internas
- `src/hooks/` - Hooks personalizados utilizados por los componentes
- `src/utils/` - Funciones de utilidad

### Externas
- `clsx` - Nombres de clase condicionales
- `lucide-react` - Iconos

<!-- MANUAL: -->

Activación del Modo de Actualización

Al ejecutarse sobre un código base existente con archivos AGENTS.md:

1. Detectar archivos existentes primero
2. Leer y analizar el contenido existente
3. Analizar el estado actual del directorio
4. Generar diff entre lo existente y lo actual
5. Aplicar actualizaciones conservando las secciones manuales

Consideraciones de Rendimiento

• Almacenar en caché listados de directorios - No volver a escanear los mismos directorios
• Agrupar directorios pequeños - Procesar varios a la vez
• Omitir si no ha cambiado - Si el directorio no ha cambiado, omitir regeneración
• Escrituras en paralelo - Varios agentes escribiendo diferentes archivos simultáneamente