Personalizando Claude Code: Lo que aprendí al perderlo todo

Imagina que has pasado semanas creando un conjunto de comandos slash personalizados en Claude Code. Atajos que conocen tu flujo de trabajo, tus estándares de código y tu pipeline de despliegue. Y un día desaparecen. Cambiaste de equipo, se corrompió una configuración o simplemente olvidaste versionarlos.

Eso me ocurrió. Tenía multitud de comandos como xgit para flujos de git, xdocs para generar documentación y xsecurity para validar requisitos de seguridad más allá de las herramientas deterministas.

Más tarde descubrí que los había configurado dentro de un proyecto que ya no usaba. Al cambiar de contexto, todo se esfumó. Personalicé sin hacerlo portátil ni persistente.

La ironía fue clara. Siempre he defendido versionarlo todo en desarrollo de software, pero al aprender Claude Code me confié y traté estos comandos como experimentos desechables. La facilidad para crearlos me hizo olvidar su valor hasta que los perdí.

Así que lo reconstruí todo, pero esta vez con un sistema diseñado para sobrevivir a cambios de proyecto y de máquina.

Construyendo personalizaciones que perduran

La lección: toda personalización debe ser portable entre proyectos, máquinas y equipos.

El toolkit se distribuye como paquete NPM, lo que hace que la instalación sea sencilla y consistente en todas las plataformas. Si quieres ver la colección completa de ejemplos y patrones, visita repositorio de claude code.

Puedes instalarlo con estos pasos escritos tal cual para copiarlos y pegarlos:

1. Instala Claude Code si aún no lo tienes: npm install -g @anthropic-ai/claude-code

2. Instala Claude Dev Toolkit vía NPM: npm install -g @paulduvall/claude-dev-toolkit

3. Despliega comandos en Claude Code: claude-commands install --active

4. Instala subagentes de Claude Code opcional: claude-commands subagents --install

5. Configura opciones opcional: claude-commands config --list para ver plantillas disponibles y claude-commands config --template nombre-de-plantilla para aplicar tu favorita. Más info en documentación de settings.

El toolkit automatiza el despliegue y evita la fragmentación que provocó mi pérdida original. El paquete NPM incluye comandos, plantillas y archivos de configuración.

Si te interesa explorar el código o contribuir, puedes clonar opcionalmente: git clone https://github.com/PaulDuvall/claude-code.git

El paquete NPM es autosuficiente, por lo que puedes instalar, configurar y personalizar Claude Code sin necesidad del repositorio.

La persistencia real la aporta el archivo CLAUDE.md, la guía de referencia de Claude Code para tu proyecto. Este archivo hace que la personalización sea verdaderamente portable. Cuando perdí mis comandos, también perdí el contexto sobre por qué existían y cómo usarlos. La estructura propuesta en CLAUDE.md captura filosofía, categorías de comandos y pautas de desarrollo.

Funciones avanzadas en profundidad

Comandos personalizados

Algo clave: los comandos slash personalizados brillan cuando la herramienta determinista no alcanza, cuando necesitas criterio, creatividad o reconocimiento de patrones con inteligencia artificial. A veces me desvié de esta regla. Algunos, como xtest, podrían ser simples scripts de shell. Pero el poder real aparece cuando la IA potencia la herramienta.

Piensa en xdebug o xarchitecture. Aprovechan la IA para analizar patrones, sugerir mejoras y tomar decisiones que un script puro no puede. La magia ocurre al combinar herramientas deterministas ejecutar tests, linting con razonamiento de IA entender contexto, proponer arquitectura, generar soluciones creativas.

Los comandos personalizados se guardan como archivos markdown en rutas bien definidas para que sean portables:

Ámbito de máquina: ~/.claude/commands/

Ámbito de proyecto: .claude/commands/

Cada archivo contiene nombre, descripción y un prompt de sistema. Más detalles en la documentación de comandos. En mi caso uso el prefijo x para distinguir comandos personalizados.

Mis comandos activos surgieron de necesidades reales del día a día:

- xtest, xquality, xgit para el flujo de desarrollo

- xsecurity, xrefactor para mejora y seguridad

- xdebug, xarchitecture para resolver problemas complejos con apoyo de IA

- xspec, xdocs para requisitos y documentación

- xpipeline, xrelease, xconfig para CI CD

Crearlos es directo. Escribe archivos markdown en .claude/commands y estarán disponibles al instante. El valor se dispara cuando los encadenas, por ejemplo:

xtest ejecuta pruebas con cobertura

xsecurity analiza vulnerabilidades

xquality comprueba la calidad del código

xgit hace commit y push con mensaje generado por IA

Este flujo sustituye decenas de pasos manuales por cuatro comandos. Versiona siempre tu carpeta .claude. Es tu póliza de seguro de personalización.

Hooks interceptando operaciones de Claude Code

Los hooks son scripts de shell que interceptan operaciones de Claude Code. Se disparan en eventos como UserPromptSubmit al enviar un mensaje, PreToolUse antes de ejecutar comandos, PostToolUse tras editar archivos y SessionStart al iniciar la sesión. Guárdalos en:

Ámbito de máquina: ~/.claude/hooks/

Ámbito de proyecto: .claude/hooks/

El toolkit incluye hooks y subagentes que cooperan. Los hooks aplican controles deterministas, los subagentes aportan análisis y decisiones con IA. Así no dependes de que la IA recuerde verificar algo, lo haces obligatorio en cada ciclo.

Comienza a construir

1 Instala con npm install -g @paulduvall/claude-dev-toolkit

2 Despliega comandos con claude-commands install --active

3 Crea CLAUDE.md con el contexto del proyecto

4 Define tus comandos en .claude/commands

5 Instala Subagents para contexto persistente con claude-commands subagents --install

6 Versiona absolutamente todo

Algunas de mis personalizaciones se inspiraron en patrones de ai development patterns.

En Q2BSTUDIO somos una empresa de desarrollo de software que diseña aplicaciones a medida y software a medida, especialistas en inteligencia artificial, agentes IA, ciberseguridad, servicios cloud aws y azure, y servicios inteligencia de negocio con power bi. Si buscas llevar estas prácticas a tu organización e integrar IA para empresas en tus pipelines, podemos ayudarte a crear un stack robusto, portable y seguro que combine automatización, control y creatividad. Descubre cómo aplicamos IA y agentes inteligentes en productos y procesos en soluciones de inteligencia artificial y cómo escalamos plataformas multiplataforma en desarrollo de software a medida.

No quiero volver a perder mis personalizaciones. Por eso todo vive en control de versiones, portable entre proyectos, máquinas y equipos. Cuando construyas tu sistema, recuerda esta idea: personalizar te permite centrarte en arquitectura y resolución de problemas, pero solo si sobrevive en el tiempo. Empieza pequeño, crea de forma sistemática, versiona todo, incorpora ciberseguridad desde el diseño y aprovecha la inteligencia artificial con disciplina.

Profundiza más

Para técnicas avanzadas y ejemplos detallados de comandos, configuración y hooks, visita el artículo Claude Code Advanced Tips Using Commands Configuration and Hooks en guía avanzada de claude code.