Dentro de la Carpeta .claude

Cada proyecto en el que trabajo tiene una carpeta .claude/ en la raíz. Su fuente vive 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 #

tu-proyecto/
├── .mcp.json               # servidores MCP compartidos (solo en la raíz)
└── .claude/
    ├── CLAUDE.md           # onboarding del proyecto
    ├── settings.json       # permisos, hooks, env
    ├── settings.local.json # ajustes personales, en .gitignore
    ├── skills/             # procedimientos, cargados bajo demanda
    ├── rules/              # convenciones, alcance opcional
    ├── hooks/              # scripts para hooks
    └── 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 frena los errores obvios, pero compara el texto del comando, no lo que hace. find . -delete se salta una regla deny sobre rm. Para un bloqueo real, usa un hook.

Las reglas deny frenan lo obvio. Los hooks imponen el resto.

Procedimientos y barandillas #

Skills: procedimientos que puedes ejecutar #

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

Un skill es una carpeta en .claude/skills/ con un SKILL.md dentro: una descripción corta más los pasos. Solo la descripción ocupa contexto. Claude carga el skill completo cuando lo invocas con una barra, o por su cuenta cuando la tarea encaja con la descripción.

Algunos de Phel:

• /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 carga en cada sesión. Las rules solo cuando aplican. Los archivos en .claude/rules/ apuntan a áreas del código con patrones glob, así el contexto se mantiene ligero.

Las rules no son sugerencias. Un cambio de convención y su rule van 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.

Los hooks son 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, así que añádela la ú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, así la sesión principal se mantiene limpia mientras el especialista profundiza. La ganancia es foco, no solo coste. 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.

¿Carpeta vacía? Deja que el agente la empiece. /init redacta un CLAUDE.md a partir de tu repo. Luego pregunta: “¿Qué convenciones repito en este código? Propón rules y skills para ellas.”

¿Ya tienes una? Pide al agente que la audite: “Revisa .claude/ contra la documentación actual de Claude Code. ¿Qué está desactualizado, sin usar o mal?” Las herramientas cambian rápido, y tu setup envejece con ellas. Así se actualizó este post por última vez.

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

Una spec para equipos con más de una herramienta de IA #

Si tu equipo solo usa Claude Code, puedes parar aquí.

.claude/ tiene un límite: solo Claude Code la lee. Codex lee AGENTS.md, Cursor lee .cursor/rules/. En un equipo mixto, las mismas rules se copian a cada formato, y las copias se desincronizan.

Por eso construí agnostic-ai. Escribe tus rules, skills, agents y hooks una vez. agnostic-ai sync los convierte en los archivos que lee cada herramienta. Commiteas la spec, y las carpetas generadas se quedan fuera de git. Esta web y Phel funcionan así.

.claude/ le enseña tu proyecto a una herramienta. Una spec se lo enseña a todas.

Trata tu setup de agentes como infraestructura. Versiónalo. Revísalo. Hazlo evolucionar con el código.