Dentro de la Carpeta .claude

Cada proyecto en el que trabajo tiene una carpeta .claude/ en la raíz. Commiteada en git, como el resto del código.

Esa carpeta convierte Claude Code de un asistente genérico en un compañero que conoce tu proyecto. Quien clone el repo hereda el mismo setup.

El agentic coding es tan bueno como el contexto que le das al agente. La carpeta .claude/ es donde vive ese contexto.

La carpeta .claude, de un vistazo

.claude/
├── CLAUDE.md         # onboarding del proyecto
├── settings.json     # permisos, hooks, env
├── skills/           # procedimientos reutilizables (slash commands)
├── rules/            # convenciones por glob
├── hooks/            # scripts que reaccionan a eventos
└── agents/           # roles especializados

Seis capas, una carpeta. Contexto, seguridad, procedimientos, barandillas, automatización, especialistas.

Los cimientos

CLAUDE.md: donde todo empieza

Claude Code lee CLAUDE.md en cada arranque. El doc de onboarding.

En Phel, el mío cubre el pipeline del compilador (Lexer → Parser → Analyzer → Emitter), la estructura de módulos, convenciones y comandos clave.

Un ~/.claude/CLAUDE.md global aplica a todos tus proyectos. El archivo de proyecto dice cómo funciona este código. El global dice cómo trabajo yo.

Cada byte viaja en cada prompt. Mantenlo corto. Si pasa de una pantalla, mueve el detalle a rules/ o skills/.

Un buen CLAUDE.md es un buen doc de onboarding. Cuanto mejor sea, menos te repites.

settings.json: seguridad antes que potencia

Antes de darle más poder al agente, bloquea lo que nunca debe hacer.

.claude/settings.json contiene tres cosas: permissions (allow/deny), hooks (comandos por evento) y env (variables). Un settings.local.json gitignoreado mantiene las configuraciones personales aparte.

{
  "permissions": {
    "allow": [
      "Bash(composer:*)",
      "Bash(./bin/phel:*)",
      "Bash(git:*)",
      "Bash(gh:*)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(sudo:*)"
    ]
  }
}

Allow desbloquea el flujo. Deny marca la línea que el agente no puede cruzar, aunque se lo pidas con buena cara.

Los permisos son el suelo. Todo lo demás se construye sobre una base segura.

Procedimientos y barandillas

Skills: procedimientos que puedes ejecutar

Siguiente dolor tras onboarding: la repetición. Los skills lo resuelven.

Un skill es un archivo markdown en .claude/skills/, un procedimiento que invocas con una barra:

• /gh-issue <número>: de issue a rama, plan TDD, PR.
• /commit: fix, análisis, tests, commit convencional.
• /refactor-check: SOLID, naming, olores de arquitectura.
• /release [version]: changelog, PHAR, tag, release.

Los skills capturan qué hacer. Las rules capturan qué no hacer.

Rules: las barandillas

CLAUDE.md se lee en cada sesión. Las rules solo cuando aplican. Los archivos en .claude/rules/ apuntan a áreas del código con patrones glob: el agente carga solo lo que corresponde, manteniendo el contexto ligero.

Las rules no son sugerencias. Viajan con el código: un cambio de convención y su rule viajan en el mismo commit. Sin drift, sin wikis desactualizadas.

Automatización y delegación

Hooks: automatización en los bordes

Las rules dicen al agente qué hacer. Los hooks se aseguran de que ocurra aunque el agente olvide.

Comandos shell disparados por eventos de Claude Code (PreToolUse, PostToolUse, Stop), conectados vía settings.json. En Phel, PreToolUse bloquea ediciones a archivos críticos (build/release.sh, .github/*, composer.lock). PostToolUse auto-formatea PHP vía php-cs-fixer.

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{ "type": "command", "command": ".claude/hooks/protect-files.sh" }]
    }],
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{ "type": "command", "command": ".claude/hooks/format-php.sh" }]
    }]
  }
}

Las rules son lo que el agente debe saber. Los hooks son lo que el sistema impone de todas formas.

Agents: roles especializados

Todo lo anterior da forma a un solo agente. Los agents añaden especialistas a los que el agente principal puede delegar, cada uno con sus propias herramientas, permisos y modelo. La pieza más avanzada. La recomiendo de última.

Algunos de Phel:

• Explorer (Sonnet, solo lectura): archivos, mapeo de estructura.
• Clean Code Reviewer: SOLID y naming en diffs.
• TDD Coach: imposición red-green-refactor.
• Domain Architect: límites de módulos, pipeline del compilador.
• Debugger: errores del compilador en todas las fases.

Cada agente corre en su propia ventana de contexto: la sesión principal se mantiene limpia mientras el especialista profundiza. La ganancia no es solo coste, es foco. Un agente con solo read y grep no puede reescribir tu código por error.

El modelo correcto para el trabajo correcto. Rápido y barato para explorar. Profundo y cuidadoso para arquitectura.

Empieza pequeño, crece con la fricción

No construyas todo esto el primer día.

El orden, guiado por fricción real:

1. Empieza con CLAUDE.md.
2. Bloquea permisos en settings.json.
3. La primera vez que te repitas, escribe un skill.
4. La primera vez que el agente rompa una convención, añade una rule.
5. La primera vez que algo malo casi se commitee, añade un hook.
6. La primera vez que un generalista no encaje, define un especialista.

Cada paso soluciona un problema que realmente tuviste. No uno que imaginaste.

El setup crece desde la fricción real, no desde el diseño anticipado.

Commitea la carpeta. Compártela. Cuando alguien se una, su sesión hereda todo.

Trata .claude/ como infraestructura. Versiónala. Revísala. Hazla evolucionar con el código.