# Estructura de Proyecto Claude-ready — Configuracion y Extensiones

Referencia extendida de la skill `estructura-proyecto-claude`. Contiene ejemplos
completos de settings.json, .mcp.json, plugins y checklists detallados.

---

## Estructura de settings.json

```json
{
  "permissions": {
    "allow": [
      "Bash(git:*)",
      "Bash(npm:*)",
      "Bash(python:*)",
      "Read(**/src/**)",
      "Write(**/src/**)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(curl * | bash:*)",
      "Bash(sudo:*)",
      "Read(**/env:*)"
    ]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "node .claude/hooks/lint-check.js" }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          { "type": "command", "command": "node .claude/hooks/format-on-save.js" }
        ]
      }
    ],
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          { "type": "command", "command": "node .claude/hooks/load-context.js" }
        ]
      }
    ]
  }
}
```

### Jerarquía de settings (mayor a menor prioridad)

1. **Managed** (MDM plist / Registry / Server-managed / `managed-settings.json`)
2. **CLI arguments** (solo sesión actual)
3. **`.claude/settings.local.json`** (personal, git-ignored)
4. **`.claude/settings.json`** (equipo, commiteado)
5. **`~/.claude/settings.json`** (global personal)

**Excepción**: los `permissions` (allow/deny) se **fusionan** entre scopes, no se
sobreescriben por precedencia simple.

---

## Settings avanzados y variables de entorno

Settings poco documentados pero de alto impacto:

| Setting | Tipo | Efecto |
|---------|------|--------|
| `plansDirectory` | string | Redirige archivos de plan a directorio custom (ej: `"./.planning"`) |
| `outputStyle` | string | Estilo de respuesta: `"Explanatory"`, `"Concise"`, etc. |
| `spinnerVerbs` | array | Verbos custom para el spinner de actividad |
| `spinnerTipsOverride` | object | `{ "tips": [...], "excludeDefault": true }` para tips personalizados |
| `enableAllProjectMcpServers` | boolean | Habilitar todos los MCP sin pedir permiso |

### Variables de entorno de control (en `"env"` de settings.json)

| Variable | Valor | Efecto |
|----------|-------|--------|
| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | `"80"` | Compactar al 80% de contexto (default: ~95%) — reduce riesgo de overflow |
| `CLAUDE_CODE_TASK_LIST_ID` | string | ID de lista de tareas compartida (Agent Teams) |
| `CLAUDE_PLUGIN_DATA` | path | Directorio de datos persistentes por skill entre sesiones |
| `ENABLE_TOOL_SEARCH` | `"true"` | Habilitar Tool Search para lazy loading de herramientas |

### Flags CLI de alto impacto

| Flag | Efecto |
|------|--------|
| `--bare` | Modo mínimo: omite auto-discovery de hooks, skills, plugins, MCP servers, auto memory y CLAUDE.md — arranque más rápido para scripts |
| `--add-dir <path>` | Agregar directorio adicional a la sesión — sesiones multi-repo sin copiar archivos. Los CLAUDE.md de esos directorios NO se cargan por defecto (`CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1` para cargarlos) |
| `-w` / `--worktree` | Git worktree aislado en `<repo>/.claude/worktrees/<nombre>` |
| `--agent <nombre>` | Usar agente custom como agente principal de la sesión |
| `--effort <nivel>` | Nivel de esfuerzo de la sesión: `low`, `medium`, `high`, `xhigh`, `max` |
| `--max-budget-usd <n>` | Tope de gasto en API antes de detenerse (solo print mode) |

### Comando `/sandbox` (Bash sandbox)

Abre el panel del sandbox de Bash: aislamiento de filesystem y red **a nivel de SO**
(Seatbelt en macOS, bubblewrap en Linux/WSL2 — no soportado en Windows nativo). En modo
auto-allow, los comandos sandboxeados corren sin diálogos de permiso; los que requieren
acceso fuera del boundary caen al flujo regular de permisos. Configuración persistente
vía `sandbox.enabled` y `sandbox.filesystem.*` en settings.json.

---

## Estructura de .mcp.json

```json
{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"]
    },
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}
```

> El GitHub MCP server oficial es remoto (`api.githubcopilot.com/mcp/`) — el paquete
> npm `@modelcontextprotocol/server-github` fue archivado. El de Playwright oficial
> es `@playwright/mcp` (Microsoft).

Ver catalogo completo en [mcp-json-template.json](mcp-json-template.json).

---

## Plugins distribuibles

Los plugins empaquetan skills + agents + hooks para distribucion:

```
mi-plugin/
+-- plugin.json              # Manifest (nombre, version, dependencias)
+-- skills/
|   +-- mi-skill/SKILL.md
+-- agents/
|   +-- mi-agent.md
+-- hooks/
|   +-- hooks.json
+-- mcp-servers/
|   +-- server.json
+-- README.md
```

Distribucion via Git, GitHub, npm o paths locales. Namespace: `plugin-name:skill-name`.

---

## Checklist completo de proyecto Claude-ready

### Estructura base
- [ ] `CLAUDE.md` existe con las 7 secciones (Stack, Conventions, Architecture, Security, Testing, Git, Workflows)
- [ ] `CLAUDE.md` tiene menos de 200 lineas
- [ ] `.claude/settings.json` existe con permisos (allow/deny) y hooks
- [ ] `.claude/settings.local.json` esta en `.gitignore`

### Extensiones
- [ ] `.claude/commands/` tiene al menos 1 comando del proyecto
- [ ] `.claude/skills/` tiene skills con SKILL.md + references/
- [ ] `.claude/agents/` tiene agentes especializados del proyecto
- [ ] `.claude/hooks/` tiene hooks configurados (al menos PreToolUse)
- [ ] `.claude/rules/` tiene reglas path-scoped si CLAUDE.md > 200 lineas

### Integraciones
- [ ] `.mcp.json` existe con al menos context7 y github
- [ ] Archivos de stack (package.json o pyproject.toml) son consistentes con CLAUDE.md

### Estado SWL
- [ ] `.planning/ESTADO.md` existe y esta actualizado
- [ ] `.planning/PROYECTO.md` define el proyecto

### Jerarquia de memoria
- [ ] CLAUDE.md de subdirectorios (si monorepo) NO sobreescriben padre
- [ ] Cada CLAUDE.md < 200 lineas
