🧠 Claude Code Best Practices — Subagentes, Skills, Hooks, MCP y Memoria
El repo que destila la configuración real de Claude Code
shanraisshan/claude-code-best-practice no es un curso ni un prompt suelto: es una implementación de referencia completa de Claude Code, con la configuración viva en .claude/ y un documento por cada primitiva.
Autor:Shayan Rais (Software Architect en Disrupt.com, Karachi).
Escala:68.268 ⭐ y 6.784 forks; MIT; creado el 31-oct-2025 y actualizado el 28-oct-2026.
Versión documentada:Claude Code v2.1.312 (28-oct-2026).
Idea central: pasar de vibe coding a agentic engineering con Command → Agent → Skill.
No es documentación oficial
Es la configuración de una persona, muy buena y muy mantenida, pero no es la doc de Anthropic. Sirve como referencia y punto de partida; contrasta siempre con code.claude.com/docs.
🎯 Por qué este repo importa
Claude Code tiene muchas primitivas y poca guía sobre cómo combinarlas. El repo resuelve justo eso:
Problema típico
Lo que aporta
«Tengo 15 MCP y no sé cuál sirve»
Lista corta de 5 MCP de uso diario y cuándo usar cada uno
«Mi CLAUDE.md es gigante y no ayuda»
Cómo se carga en monorepos: ancestros al inicio, descendientes lazy
«Los subagentes no se activan»
Los 16 campos del frontmatter y el truco de PROACTIVELY
«Las skills se pisan con los commands»
Comparativa de las tres primitivas y cuándo usar cada una
«El agente dice que terminó y no funciona»
Verification loops: tests y build antes de dar por bueno
«No sé cómo orquestar»
Patrón Command → Agent → Skill con demo ejecutable
🧩 Las cinco primitivas
Primitiva
Ubicación
Qué es
Detalle en el repo
Subagents
.claude/agents/<name>.md
Sesiones hijas con rol, tools y modelo propios
16 campos de frontmatter + 5 agentes oficiales
Commands
.claude/commands/<name>.md
Atajos /nombre con argumentos
20 campos + comandos built-in
Skills
.claude/skills/<name>/SKILL.md
Paquetes de conocimiento con progressive disclosure
20 campos + 25 skills oficiales
Hooks
.claude/hooks/ + settings.json
Scripts en el ciclo de vida
Repo aparte con config y sonidos
MCP
.mcp.json y ~/.claude.json
Herramientas externas por protocolo
5 servidores recomendados + permisos
El patrón que lo une todo
flowchart LR
U["👤 /command<br/>intención"] --> A["🤖 Agent<br/>orquesta y delega"]
A --> S["📚 Skill<br/>procedimiento"]
A --> T["🔧 Tools / MCP<br/>acción real"]
S --> V["✅ Verificación<br/>tests · build · diff"]
T --> V
V --> R["📦 Resultado<br/>revisado"]
Un command captura la intención, un agent la descompone, una skill aporta el how, las tools/MCP ejecutan y la verificación cierra el ciclo. El demo del repo es /weather-orchestrator.
🤖 Subagentes
Los 5 oficiales
Agente
Modelo
Tools
Para qué
general-purpose
inherit
Todas
Investigación y tareas multi-paso
Explore
haiku
Solo lectura
Buscar archivos y responder sobre el código
Plan
inherit
Solo lectura
Investigar y diseñar antes de escribir
statusline-setup
sonnet
Read, Edit
Configurar la status line
claude-code-guide
haiku
Glob, Grep, Read, WebFetch, WebSearch
Dudas de Claude Code, SDK y API
Campos que de verdad se usan
Campo
Por qué importa
description
Es lo que decide si se invoca. PROACTIVELY fuerza la auto-invocación
tools / disallowedTools
Limita el radio de daño; Agent(tipo) restringe qué subagentes puede lanzar
model
haiku para explorar, opus para razonar, inherit por defecto
permissionMode
plan para research, acceptEdits para trabajo mecánico
skills
Precarga la skill completa en el contexto del subagente
mcpServers
Aísla servidores MCP por subagente
memory
Memoria persistente user, project o local
isolation: worktree
Corre en un git worktree temporal y lo limpia si no hay cambios
maxTurns
Corta bucles infinitos
background
Lo manda a segundo plano sin bloquear la sesión
El detalle que casi nadie usa
memory: project + un MEMORY.md convierten un subagente en algo que aprende entre sesiones. El repo lo demuestra con weather-agent.
📚 Skills vs Commands vs Subagents
Las tres son markdown con frontmatter, pero no compiten:
Criterio
Skill
Command
Subagent
Quién lo invoca
El modelo, por contexto
El usuario con /
El agente padre
Contexto
Se carga al activarse
Entra en el turno
Contexto limpio y aislado
Sirve para
Conocimiento y procedimientos
Atajos con argumentos
Delegar trabajo pesado o paralelo
Modelo
Puede fijar uno
Puede fijar uno para el turno
Modelo propio
Fork
context: fork
context: fork
Es su naturaleza
Skills: lo que aporta el repo
20 campos de frontmatter, incluidos when_to_use, paths, allowed-tools, disallowed-tools, context: fork y background.
Progressive disclosure: al inicio el agente solo ve nombre y descripción; el SKILL.md completo se lee solo si aplica. Eso mantiene el contexto barato.
Regla práctica
Si el conocimiento aplica siempre → CLAUDE.md o rule.
Si es un procedimiento que se activa a veces → skill.
Si es un atajo que tú escribes → command.
Si necesita contexto aislado o paralelismo → subagent.
Bloquear comandos peligrosos (rm -rf, push a main)
PostToolUse
Formatear, lintar o compilar tras editar
PostToolUseFailure
Diagnóstico y reintento
Stop / SubagentStop
Cerrar el turno con verificación
PreCompact / PostCompact
Preservar decisiones antes de comprimir
El repo incluye sonidos por evento (PreToolUse, Stop, PermissionRequest…) para saber qué está pasando sin mirar la pantalla, y un hooks.py con la lógica.
Los hooks son código
Se ejecutan con tus permisos. Revisa cada script antes de activarlo y nunca los apuntes a binarios que no controles.
🔌 MCP: menos es más
La cita que abre el documento lo resume: «Metí 15 MCP pensando que más era mejor. Terminé usando 4 a diario».
Esta es la parte que más malentendidos genera. Claude Code usa dos mecanismos:
Mecanismo
Dirección
Cuándo carga
Ancestor
Hacia arriba
Al arrancar, todos los CLAUDE.md del camino a la raíz
Descendant
Hacia abajo
Lazy: solo al leer o editar archivos de esa carpeta
Siblings
Ramas hermanas
Nunca
Ejemplo en un monorepo:
/mymonorepo/├── CLAUDE.md # se carga siempre├── frontend/CLAUDE.md # solo si trabajas en frontend/├── backend/CLAUDE.md # solo si trabajas en backend/└── api/CLAUDE.md # solo si trabajas en api/
Reglas de oro
Convenciones compartidas → CLAUDE.md raíz.
Detalles del componente → CLAUDE.md del componente.
Preferencias personales → CLAUDE.local.md (y al .gitignore).
Global del usuario → ~/.claude/CLAUDE.md.
Reglas modulares → .claude/rules/ en vez de un archivo de 1.000 líneas.
La lección de fondo
El contexto es un presupuesto, no un vertedero. Un CLAUDE.md corto, específico y con comandos verificables rinde más que 2.000 líneas de prosa. El repo entero está construido sobre esa idea.
No copies .claude/ entero en tu repo. Orden recomendado:
Paso
Qué hacer
Por qué
1
Copia CLAUDE.md y poda
Es la base; quita lo que no aplique
2
Añade una skill real de tu flujo
Prueba el mecanismo antes de escalar
3
Crea un subagente de solo lectura
Bajo riesgo, beneficio inmediato
4
Añade un hook PostToolUse de formato
Ganancia diaria, riesgo mínimo
5
Configura 2–3 MCP, no 10
Menos tools, mejor selección
6
Solo entonces: commands y orquestación
Requiere lo anterior estable
📊 Lectura crítica
Lo bueno:
Configuración real, no teoría: .claude/ funciona y el demo se puede ejecutar.
Un documento por primitiva, con tablas de campos y versión de Claude Code.
Actualización muy frecuente y changelogs separados: se puede ver qué cambió y cuándo.
Honestidad sobre el coste: las skills y los subagentes gastan tokens; el repo lo dice.
MIT: se puede copiar, podar y adaptar.
Lo que hay que tener en cuenta:
No es oficial. Las «best practices» son las de un arquitecto, no las de Anthropic.
Versionado agresivo. Claude Code cambia cada semana; un campo puede desaparecer. El badge dice v2.1.312, y eso caduca rápido.
README de ~74 KB. Es un índice, no un libro: usa la tabla de contenidos.
Estrellas y trending no equivalen a calidad técnica; parte del repo es difusión y patrocinio.
Los tips de Boris Cherny son citas de X y charlas, no especificación.
Commands y skills se solapan a propósito: Claude Code ha ido convergiendo ambas primitivas, y el repo documenta las dos.
MCP recomendados = opinión. Context7 y Playwright son buenos; no son obligatorios.
Para tu caso
Ya usas skills en esta bóveda y agentes en OpenCode. Lo más rentable de este repo para ti es la parte de carga de memoria en monorepos, el patrón Command → Agent → Skill y la disciplina de pocos MCP. El resto es bueno como referencia, no como plantilla para copiar entera.