Buenas Prácticas para Comandos, Hooks y Subagentes Personalizados

Estas son las convenciones que vale la pena adoptar una vez que un proyecto comienza a depender de comandos, hooks y subagentes personalizados más allá de un experimento único.

Cada regla a continuación refleja un modo de fallo real, un matcher ambiguo, un prompt de tarea vago, un hook que se ejecuta de manera demasiado amplia, que aparece rápidamente una vez que estos puntos de extensión se utilizan para trabajo real.

Cómo Usar Esta Lista

• Trata las reglas como valores predeterminados de los que desviarse deliberadamente, no como leyes, ya que la tolerancia al riesgo de cada proyecto difiere.
• Revisa las secciones de hooks y comandos cada vez que settings.json o .claude/commands/ crezca más allá de un puñado de entradas; las convenciones decaen más rápido bajo una acumulación silenciosa.
• Aplica las reglas de subagente por tarea, ya que la cantidad adecuada de delegación varía con la independencia y el tamaño real del trabajo.
• Empareja las reglas de PreToolUse con una lista real de rutas protegidas para tu proyecto; una regla sin un objetivo concreto no impone nada.

A - Nomenclatura y Descubrimiento

• Asigna a cada comando una description en su frontmatter. Sin ella, un comando es invisible en el autocompletado, y los compañeros de equipo recurren a reimplementar la misma solicitud desde cero.
• Nombra los comandos por la acción, no por el solicitante. /pre-review se lee claramente meses después; /chris-check no sobrevive a la salida de la persona del equipo.
• Mantén los nombres de archivo y slugs de los comandos estables una vez compartidos. Renombrar un comando rompe la memoria muscular de cada compañero de equipo y cualquier documentación que lo referencie por nombre.
• Agrupa comandos relacionados con un prefijo compartido cuando el conjunto crezca. /pr-review, /pr-summarize y /pr-changelog se leen como una familia en el autocompletado; tres nombres no relacionados no lo hacen.

B - Delimitación del Alcance de los Matchers de Hooks

• Empareja los hooks con el conjunto de herramientas más estrecho que realice el trabajo. Un hook de formato necesita Edit|Write, no un match sin delimitar en cada llamada a herramienta.
• Prefiere un archivo de script dedicado sobre un comando en línea largo en settings.json. Un script es comprobable y comparable por sí solo; una línea única y extensa en JSON no lo es.
• Protege contra datos de eventos faltantes o mal formados antes de actuar. Un hook que asume que una ruta de archivo siempre está presente fallará ruidosamente, o silenciosamente, la primera vez que no lo esté.
• Mantén los hooks rápidos. Un hook PostToolUse se ejecuta en cada edición coincidente; uno lento (una suite de pruebas completa, una compilación grande) agrega esa latencia a cada edición individual, no solo a las que importan.
• Controla versiones de cada script de hook junto con el proyecto. Un hook que solo existe en la máquina de un contribuidor es un hook que el resto del equipo realmente no tiene.

C - Uso de PreToolUse para Límites Reales

• Reserva PreToolUse para reglas que deben cumplirse incluso contra un prompt engañoso. Cualquier cosa formulada como "esto nunca debería suceder" pertenece aquí, no en un paso de limpieza PostToolUse.
• Emite una decisión de bloqueo explícita, no solo un código de salida distinto de cero. Una respuesta estructurada {"decision": "block", "reason": "..."} es la señal confiable; los códigos de salida solos pueden interpretarse de manera inconsistente.
• Escribe razones de bloqueo para un humano que lea la transcripción más tarde. "Bloqueado" no explica nada; "esta ruta está protegida, pide a un humano que haga este cambio directamente" sí lo hace.
• Ancla los patrones de rutas protegidas a la estructura de directorios real, no solo a una extensión de archivo. Un patrón como *.json que protege un archivo de bloqueo terminará bloqueando cada archivo JSON en el proyecto.
• Empareja una protección PreToolUse con protecciones normales a nivel de repositorio. Un hook solo se activa dentro de la ruta de llamada a herramientas de Claude Code; no es un sustituto de la protección de ramas o los permisos de archivo aplicados en otros lugares.

D - Delegación de Trabajo a Subagentes

• Escribe los prompts de tareas de subagente como si el subagente no hubiera visto nada más. Porque no lo ha hecho; cualquier cosa que la sesión principal sepa y no repita simplemente no está disponible para el subagente.
• Delimita las herramientas de un subagente a lo que su trabajo realmente requiere. Un subagente de investigación que nunca edita archivos no debería tener Edit o Write en su lista de herramientas, como cuestión de aplicación, no solo de orden.
• Pide un resumen, no el contenido completo del archivo, en la instrucción de reporte. Un subagente que devuelve archivos completos al principal anula el propósito de ahorro de contexto de delegar en primer lugar.
• Solo distribuye subagentes en paralelo cuando las piezas sean genuinamente independientes. Una tarea donde un subagente necesita los hallazgos de otro primero debe ejecutarse secuencialmente, no concurrentemente.
• Empareja el número de subagentes paralelos con cuánta síntesis la sesión principal puede hacer realmente después. Generar más subagentes de los que puedes leer y combinar de manera significativa solo retrasa la respuesta.
• Reserva subagentes para tareas lo suficientemente grandes o aisladas como para justificar la sobrecarga. Una búsqueda de una línea rara vez necesita su propia ventana de contexto; una exploración de cuarenta pasos usualmente sí.

E - Evitar que los Tres Puntos de Extensión Colisionen

• No pidas a un hook que tome una decisión. Un hook no tiene razonamiento de modelo adjunto; si la decisión requiere sopesar el contexto, pertenece al prompt de un comando o a la tarea de un subagente, no a un script de shell.
• No uses un comando donde un hook garantizaría el resultado. Si algo debe suceder cada vez sin excepciones, un comando que un usuario debe recordar escribir es el mecanismo incorrecto; usa un hook en su lugar.
• Documenta cuál de los tres puntos de extensión utiliza una nueva automatización y por qué. Un miembro del equipo que depura un comportamiento inesperado necesita saber rápidamente si debe buscar en .claude/commands/, settings.json, o una definición de subagente.
• Revisa los hooks de settings.json y .claude/commands/ juntos durante la incorporación. Ambos están controlados en el repositorio y ambos dan forma a lo que significa "escribir una solicitud" o "ocurrir una edición"; omitir cualquiera de ellos deja a un nuevo miembro del equipo con una imagen incompleta.

Preguntas Frecuentes

Relacionado

• Comandos, Hooks y Subagentes Personalizados: Para Qué Sirve Cada Uno - la distinción fundamental sobre la que se basan estas prácticas.
• Escribiendo Tu Primer Comando Personalizado con Frontmatter Markdown - donde las convenciones de nomenclatura y descripción se aplican directamente.
• Bloqueo de Ediciones de Archivos Riesgosas con un Hook PreToolUse - un ejemplo completo y funcional de las prácticas PreToolUse anteriores.
• Generación de Subagentes Paralelos para Tareas de Investigación Aisladas - las prácticas de distribución en un recorrido completo.
• Eventos Comunes de Hooks y Cuándo Usar Cada Uno - emparejar el evento de un hook con su trabajo real.

Versiones de Stack: Escrito contra la línea de modelos Claude actual a partir de ~junio de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado) y Claude Haiku 4.5. Los nombres de modelos, precios y características del producto cambian rápidamente; verifica los detalles actuales en platform.claude.com/docs antes de confiar en ellos.