---
name: estructura-proyecto-claude
description: >
  Genera y valida estructuras de proyecto Claude-ready según las guías oficiales
  "Claude Code Project Structure" y "Claude Code Workflow Cheatsheet".
  Cargar al inicializar proyecto nuevo, migrar proyecto existente al sistema SWL,
  auditar estructura Claude-ready, agregar extensiones (commands, skills, agents,
  hooks, plugins), o configurar MCP. Cubre arquitectura de 4 capas, jerarquía
  de memoria, 6 tipos de extensión, 27 hook events, frontmatter de skills/agents/commands
  y settings avanzados.
version: "1.0.0"
herramientasPermitidas: [Read, Write, Edit, Bash, Glob, Grep]
exclusiones:
  - "No cargar para iniciar un proyecto desde cero — ese flujo usa `/swl:nuevo-proyecto` que incluye entrevista de contexto antes de generar la estructura; este skill genera estructura pero no recoge requisitos de negocio."
  - "No cargar para agregar o actualizar un agente o skill específico dentro de un proyecto ya estructurado — eso es trabajo directo sobre el frontmatter del componente; cargar este skill solo cuando se auditea o crea la estructura completa del proyecto."
  - "No cargar para configurar permisos de tools individuales en un agente — `seguridad-agentes` cubre la decisión de permisos; este skill cubre la estructura del proyecto, no la política de permisos de cada agente."
  - "No cargar solo para leer la documentación de un tipo de extensión Claude Code — la guía oficial vía Context7 MCP es más actualizada para detalles de API específicos de extensiones."
evolvable: true  # default para skill estandar
---
# Estructura de Proyecto Claude-ready

Fuentes oficiales:
- `referencias/Claude Code Project Structure.jpg`
- `referencias/Claude Code WorkFlow Cheatsheet.jpg`
- https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview

## Cuándo cargar esta skill

- Se inicializa un proyecto nuevo (`/swl:nuevo-proyecto`)
- Se migra un proyecto existente al sistema SWL
- Se audita si un proyecto tiene estructura Claude-ready correcta
- Se agregan extensiones (commands, skills, agents, hooks, plugins)
- Se configura MCP para un proyecto

---

## Estructura base oficial

```
mi_proyecto/
+-- CLAUDE.md                              # Fuente de verdad del proyecto (L1)
+-- .claude/
|   +-- settings.json                      # Permisos, hooks y context rules
|   +-- settings.local.json                # Config local (NUNCA commitear)
|   +-- commands/                          # Slash commands del proyecto
|   +-- skills/                            # Módulos de capacidad (L2)
|   |   +-- nombre-skill/
|   |       +-- SKILL.md
|   |       +-- scripts/, references/, assets/
|   +-- agents/                            # Subagentes del proyecto (L4)
|   +-- hooks/                             # Automatizaciones event-driven (L3)
|   +-- rules/                             # Reglas con scope por paths
|   +-- plugins/                           # Plugins distribuibles
+-- .planning/                             # Estado de planificación SWL
|   +-- PROYECTO.md, REQUISITOS.md, HOJA-RUTA.md, ESTADO.md
|   +-- research/
+-- .mcp.json                              # Configuracion de servidores MCP
```

---

## Arquitectura de 4 capas

| Capa | Componente | Propósito |
|------|-----------|-----------|
| **L1** | **CLAUDE.md** | Contexto persistente — cargado SIEMPRE al inicio |
| **L2** | **Skills** | Conocimiento versionado — cargados por coincidencia |
| **L3** | **Hooks** | Seguridad y automatización — event-driven |
| **L4** | **Agents** | Subagentes con contexto propio — ejecución aislada |

---

## Jerarquía de memoria CLAUDE.md

| Scope | Path | Aplica a |
|-------|------|----------|
| **Managed Policy** | Sistema | Todos los usuarios org |
| **User** | `~/.claude/CLAUDE.md` | Todos tus proyectos |
| **Project** | `./CLAUDE.md` | Proyecto (repo) |
| **Subdirectory** | `packages/frontend/CLAUDE.md` | Paquete del monorepo |

### Comportamiento de carga

- **Ancestor (ARRIBA)**: al inicio, carga TODOS los CLAUDE.md desde cwd hasta la raíz del sistema de archivos — siempre se cargan
- **Descendant (ABAJO)**: lazy — solo carga cuando Claude navega a un subdirectorio
- **Siblings**: NUNCA se cargan entre sí
- Solo las **primeras 200 líneas** de cada CLAUDE.md se inyectan al prompt del sistema

**Reglas clave**: Menos de 200 líneas por CLAUDE.md. Subdirectorios agregan, NUNCA sobreescriben.

---

## 6 tipos de extensión

| Tipo | Activación | Ubicación |
|------|-----------|-----------|
| **Skills** | Auto-activación | `.claude/skills/` |
| **Commands** | Manual (`/comando`) | `.claude/commands/` |
| **Subagents** | Spawn por orquestador | `.claude/agents/` |
| **Hooks** | Event-driven | `settings.json` hooks |
| **MCP Servers** | Siempre disponibles | `.mcp.json` |
| **Plugins** | Instalación | `.claude/plugins/` |

---

## Anatomía de una skill — Tres niveles de carga

| Nivel | Qué carga | Cuándo | Costo |
|-------|-----------|--------|-------|
| **Level 1** | Frontmatter (name + description) | Siempre | ~100 tokens |
| **Level 2** | Cuerpo de SKILL.md | Al activarse | <5k tokens |
| **Level 3** | scripts/, references/, assets/ | Bajo demanda | Sin límite |

### Frontmatter completo de SKILL.md

```yaml
---
name: nombre-skill              # kebab-case, max 64 chars
description: >                  # max 1024 chars — QUÉ + CUÁNDO
  Describe qué hace y cuándo Claude debe auto-activarla.
allowed-tools: ["Read", "Grep", "Glob"]
paths:
  - "src/api/**/*.ts"
context: fork                   # fork = subagente aislado
---
```

Ver referencia completa en [recursos/frontmatter-y-hooks-referencia.md](recursos/frontmatter-y-hooks-referencia.md).

---

## Hook Events (14 críticos de 27 oficiales)

| Evento | Cuándo se dispara | Uso típico |
|--------|-------------------|-----------|
| **PreToolUse** | Antes de ejecutar herramienta | Bloquear ops inseguras |
| **PostToolUse** | Después de ejecutar herramienta | Auto-lint, format |
| **SessionStart** | Al iniciar sesión | Cargar contexto |
| **Stop** | Al completar respuesta | Verificar tarea |
| **PreCompact** | Antes de compactar | Salvar estado crítico |
| **PostCompact** | Después de compactar | Re-inyectar contexto |
| **Notification** | Claude espera input | Alertas desktop |

Los 20 eventos restantes, frontmatter de agents (16 campos) y commands (13 campos),
opciones avanzadas de hooks y orden de resolución en
[recursos/frontmatter-y-hooks-referencia.md](recursos/frontmatter-y-hooks-referencia.md).

---

## 7 secciones obligatorias de CLAUDE.md

| # | Sección | Contenido |
|---|---------|-----------|
| 1 | **Tech Stack** | Lenguaje, framework, BD, herramientas con versiones |
| 2 | **Conventions** | Estilo, tipo hints, formato, imports |
| 3 | **Architecture** | Directorios clave y qué contiene cada uno |
| 4 | **Security** | No secretos, validación, queries parametrizadas |
| 5 | **Testing** | Framework de tests, cómo correr, cobertura mínima |
| 6 | **Git Workflow** | Branch strategy, commit format, PR rules |
| 7 | **Common Workflows** | Comandos de build, test, deploy, dev server |

Ver template completo en [recursos/claude-md-template.md](recursos/claude-md-template.md).

---

## Gestión de contexto

| Rango | Accion |
|-------|--------|
| **0-40%** | Trabajar normalmente |
| **40-70%** | Monitorear uso de contexto |
| **70-90%** | Ejecutar `/compact` |
| **90-100%** | Detener, compactar, o nueva sesion |

---

## Reglas de generación

1. **No sobrescribir sin confirmación** — verificar existencia antes de crear.
2. **Ajustar al stack detectado** — `pyproject.toml` -> Python, `package.json` -> Node.
3. **Registrar decisiones en ESTADO.md**.
4. **`.gitignore`** debe incluir `.claude/settings.local.json` y `.env`.
5. **Skills usan `references/`** dentro de `.claude/skills/`, y `recursos/` en `habilidades/`.
6. **CLAUDE.md < 200 líneas** — dividir en `.claude/rules/*.md` con `paths:` si excede.

---

## Variantes por stack

Ver [recursos/variantes-por-stack.md](recursos/variantes-por-stack.md).

| Stack | Archivo raiz | ORM / DB | Framework de test |
|-------|-------------|----------|-------------------|
| Python/FastAPI | `pyproject.toml` | SQLAlchemy + Alembic | pytest + httpx |
| Node.js | `package.json` | Prisma / Drizzle | Vitest / Jest |
| Angular | `angular.json` | N/A | Karma / Jest |
| React/Next.js | `next.config.js` | N/A | Vitest + RTL |

---

Para configuración completa de settings.json, .mcp.json, plugins y checklist detallado, ver [recursos/configuracion-y-extensiones.md](recursos/configuracion-y-extensiones.md).

## Cuándo NO cargar

- Se inicia un proyecto completamente nuevo — usar `/swl:nuevo-proyecto`, que conduce la entrevista de contexto antes de elegir estructura; este skill genera la estructura pero no recoge los requisitos del proyecto.
- Se modifica o crea un componente específico (un agente, un skill, un hook) dentro de un proyecto ya estructurado — el overhead de cargar toda la arquitectura de 4 capas no compensa para una edición puntual de frontmatter.
- Se configuran permisos de herramientas o nivel de riesgo de un agente — esa decisión requiere `seguridad-agentes`; este skill describe dónde vive la configuración, no qué valores son seguros.
- Se busca la sintaxis actual de una API de extensión específica de Claude Code — Context7 MCP tiene la documentación oficial más actualizada para APIs de comandos, hooks y settings avanzados.

## Gotchas / Errores comunes no obvios

- **CLAUDE.md supera 200 líneas sin subdirectorios y Claude Code deja de respetarlo**: el agente empieza a saltarse reglas de proyecto porque el archivo es demasiado largo para ser incluido completo en el contexto. Causa: reglas que deberían estar en `.claude/rules/*.md` con `paths:` quedan todas en el CLAUDE.md raíz. Solución: dividir en archivos en `.claude/rules/` con `paths:` filtrado por extensión o directorio — la regla 6 de este skill dice CLAUDE.md < 200 líneas.
- **`settings.local.json` committeado con permisos de desarrollo**: el archivo contiene `allowedTools` con `Bash` habilitado globalmente y queda en el repositorio. Causa: `.gitignore` no incluye `.claude/settings.local.json`. Solución: verificar que `.gitignore` tiene la entrada antes de cualquier commit que toque `.claude/` — este archivo es por definición local y nunca debe versionarse.
- **Hook declarado en `hooks/` pero sin registrar en `manifiestos/hooks-config.json`**: el hook no se ejecuta y nadie entiende por qué el evento PreToolUse no dispara. Causa: crear el archivo del hook sin actualizar el manifiesto. Solución: toda adición de hook requiere actualización de `manifiestos/hooks-config.json` y `.claude/settings.json` según la tabla de propagación en CLAUDE.md — el hook no se activa si Claude Code no sabe que existe.
- **`herramientasPermitidas` en skill declarada con tools que el agente invocador no tiene**: el skill requiere `Write` pero el agente que lo carga solo tiene `Read`. Causa: el frontmatter del skill declara herramientas sin verificar qué agentes lo invocarán. Solución: al crear un skill, verificar que los agentes que están en `skillsInvocables` del skill tienen al menos las mismas tools en su propio frontmatter — la cadena de permisos no escala hacia arriba.
