Empieza con lo mínimo. Agrega cuando duela.
Claude Code parece intimidante porque todo el contenido disponible mezcla lo básico con técnicas avanzadas. La realidad: necesitas cuatro cosas para arrancar. Todo lo demás — skills, agentes, specs — llega solo cuando el proyecto lo pide.
La jerarquía que nadie te explica
El error más común es querer arquitectar todo desde el principio. Estos tres niveles no son opcionales entre sí — son secuenciales.
← Desliza para ver el diagrama completo →
Lo esencial
Día unoProductividad
Cuando repitas trabajoArquitectura
Proyectos grandesLa pregunta que más se repite: ¿hay que crear los agentes antes de escribir código?
No. Los subagents, skills y specs son optimizaciones que aparecen cuando el proyecto ya existe y detectas fricción. Crearlos antes es arquitectura especulativa.
Plan Mode primero, siempre
Es la diferencia entre pedirle a alguien que no toque tu comida y guardar la comida en una vitrina cerrada. Uno es una solicitud, el otro es una restricción mecánica.
En modo normal Claude Code lee tu prompt y actúa de inmediato: edita archivos, corre comandos, modifica cosas. Plan Mode le quita las herramientas de escritura. Conserva lectura completa — puede leer archivos, buscar en el código, investigar en la web — pero no puede escribir, editar ni ejecutar nada hasta que apruebes.
Escribir «no modifiques nada» en un prompt es una sugerencia que se puede ignorar. Plan Mode no.
# En la terminal, dos veces: Shift + Tab # Primera pulsación → Auto-Accept # Segunda pulsación → Plan Mode # Verás en la barra de estado: ⏸ plan mode on
← Desliza para ver el diagrama completo →
Cómo sales de Plan Mode
No tienes que cambiar de modo manualmente. Cuando apruebas un plan, Claude sale de Plan Mode automáticamente y empieza a ejecutar. La aprobación es el cambio de modo.
- «ajusta esto…»
- Le das feedback y regenera el plan. Sigues en Plan Mode. Puedes quitar pasos, reordenarlos o agregar restricciones.
- «yes»
- Sale de Plan Mode y ejecuta el plan exactamente como lo aprobaste.
- Shift + Tab
- Salir sin aprobar nada, por ejemplo si la conversación se desvió y prefieres empezar de nuevo.
Cuándo saltártelo: ediciones de un solo archivo o preguntas de solo lectura. Cuándo es obligatorio: cualquier cambio que toque tres o más archivos, cambios de esquema de datos, o código sensible a seguridad.
Dos flujos, según tu punto de partida
El patrón es el mismo — explorar, planear, implementar, commitear — pero el arranque cambia según si ya hay código que entender.
- Abrir la sesión
cd ~/mi-proyecto && claude - Activar Plan ModeShift+Tab × 2. Antes de cualquier prompt.
- Explorar«¿Qué hace este proyecto? Describe estructura, stack, entry points y cómo correr los tests.»
- Generar contexto
/initescanea el repo y genera el CLAUDE.md - Editar CLAUDE.mdAgrega lo que el código no dice: convenciones del equipo, gotchas, decisiones tomadas.
- Pedir el cambio«Implementa [feature] según el CLAUDE.md»
- Revisar el planVerifica archivos tocados, dependencias, que respete tus gotchas.
- Aprobar y ejecutar«yes» — Claude sale de Plan Mode e implementa.
- Commitear«commit my changes with a descriptive message»
- Reproducir primeroDale el síntoma exacto, no tu teoría: el error literal, los pasos para provocarlo y qué esperabas. Una hipótesis en el prompt sesga la búsqueda hacia donde tú ya miraste.
- Plan Mode para investigarShift+Tab × 2. Que lea y diagnostique sin arreglar nada.
/debugactiva el logging si necesitas más rastro. - Revisar el diagnóstico, no solo el arregloSi la causa raíz que describe no te convence, el parche tampoco servirá. Aquí es donde más rinde negarse a aprobar.
- Pedir el test antes del fix«Escribe primero un test que falle por este bug, luego arréglalo.» Sin eso no hay prueba de que se corrigió ni red contra la regresión.
- Revisar y commitear
/code-reviewsobre el diff antes de dar por cerrado. - Limpiar el contexto
/clear. Un debug largo deja intentos fallidos que contaminan lo siguiente — ver sección 06.
- SkillsRepites el mismo prompt tres o más veces.
- SubagentsUna tarea necesita contexto aislado y reglas propias.
- Specs (SDD)Un feature toca tres o más archivos. Es una práctica de trabajo, no una función del producto.
- Hooks, MCP, pluginsAutomatización, datos externos, o reusar el mismo setup en otro repositorio.
- Crear el directorio
mkdir mi-proyecto && cd mi-proyecto && claude - Activar Plan ModeShift+Tab × 2. Evita que Claude cree archivos a media conversación.
- Pedir la entrevista«Quiero construir [X]. Antes de escribir código, entrevístame: pregúntame sobre requisitos, stack, casos borde y decisiones de diseño.»
- ResponderStack, requisitos, edge cases, restricciones. Aquí es donde salen las preguntas que no habías considerado.
- Pedir la estructura«Crea la estructura, CLAUDE.md, README y git init. No implementes lógica todavía.»
- Revisar CLAUDE.mdVerifica que refleje las decisiones de la entrevista.
- Primer commit«commit inicial con estructura base»
- Pedir el feature«Implementa [módulo] según el CLAUDE.md»
- Revisar y aprobarUn feature a la vez, siempre revisando el plan.
- Commitear«commit» y al siguiente.
- SkillsRepites el mismo prompt tres o más veces.
- SubagentsUna tarea necesita contexto aislado y reglas propias.
- Specs (SDD)Un feature toca tres o más archivos. Es una práctica de trabajo, no una función del producto.
- Hooks, MCP, pluginsAutomatización, datos externos, o reusar el mismo setup en otro repositorio.
El archivo que ancla todo
Claude Code lee el CLAUDE.md al inicio de cada sesión. Sobrevive a /clear y se recarga desde disco. Es uno de los dos mecanismos que cruzan sesiones: este lo escribes tú, el auto memory lo escribe Claude.
En Claude Code el contexto pesa más que el prompt. Un buen CLAUDE.md con Plan Mode activo produce mejores resultados que el prompt más ingenioso sin contexto.
Las secciones que importan
- Qué es esto
- Dos o tres líneas. Qué problema resuelve el proyecto y para quién.
- Stack técnico
- Lenguaje, framework, librerías, base de datos, deploy, tests, linter. Con versiones cuando importen.
- Estructura
- Árbol de directorios con un comentario por módulo. Esto le dice a Claude dónde va cada cosa.
- Convenciones
- Type hints, idioma de los nombres, manejo de errores, dónde van los tests. Lo que un dev nuevo necesitaría saber.
- Comandos
- Cómo correr, testear, lintear. Claude los ejecuta directamente.
- Decisiones de diseño
- Numeradas, con el porqué. Evita que Claude proponga algo que ya descartaste.
- Gotchas
- Rate limits, secretos, trampas conocidas. La sección que más valor entrega con el tiempo.
- Fases
- Checklist de qué está hecho y qué falta. Le da a Claude sentido de progreso.
# Nombre del proyecto ## Qué es este proyecto Una o dos líneas: qué resuelve y para quién. ## Stack técnico - Lenguaje, framework, DB, deploy, tests, linter ## Estructura del proyecto src/ ├── modulo_a/ # responsabilidad └── modulo_b/ # responsabilidad ## Convenciones de código - Reglas concretas, no principios abstractos ## Comandos - Correr: `comando` - Tests: `comando` ## Decisiones de diseño 1. Decidimos X en lugar de Y porque Z ## Gotchas - Trampas conocidas, rate limits, secretos ## Fases - [ ] Pendiente - [x] Hecho
Regla de oro para las convenciones: escribe reglas verificables, no principios. «Type hints en todas las funciones públicas» sirve. «Código limpio» no sirve.
Cuando el archivo crece
Apunta a menos de 200 líneas. El CLAUDE.md se carga entero en cada sesión, así que cada línea se paga en contexto siempre — y los archivos largos no solo cuestan más, sino que se siguen peor.
Si se te desborda, la salida no es recortar a lo bruto: es mover instrucciones a .claude/rules/. Son archivos markdown temáticos, y con frontmatter paths: se cargan solo cuando Claude toca archivos que casan con el patrón.
# .claude/rules/api.md --- paths: - "src/api/**/*.ts" --- Valida siempre la entrada en los endpoints. Usa el formato de error estándar del proyecto.
Esa regla no ocupa contexto mientras trabajas en el frontend. Una regla sin paths se carga siempre, igual que el CLAUDE.md. Si ya lo tienes grande, /doctor propone recortes: quita lo que Claude puede deducir del propio código y conserva las trampas y el porqué de las decisiones.
Prompts que funcionan
Copiables tal cual. Todos asumen Plan Mode activo y CLAUDE.md en la raíz.
¿Qué hace este proyecto? Describe la estructura, lenguaje, framework, entry points y cómo correr los tests. No modifiques nada.
Quiero construir [descripción del proyecto]. Antes de escribir código, entrevístame: pregúntame sobre los requisitos, stack tecnológico preferido, casos borde y decisiones de diseño que debería considerar.
Scaffoldea el proyecto según la estructura definida en el CLAUDE.md. Crea todos los directorios, archivos con docstrings que describan su responsabilidad, el archivo de dependencias, .gitignore y .env.example. No implementes lógica todavía.
Implementa [ruta/al/archivo] según el CLAUDE.md. Incluye los modelos que necesite en [ruta/schemas]. Agrega tests en tests/ siguiendo las convenciones del proyecto.
Escribe un plan.md con los pasos para implementar [feature]. Divídelo en secciones que se puedan ejecutar en sesiones separadas. No implementes nada todavía.
Qué revisar antes de aprobar un plan
Tres verificaciones que evitan la mayoría de los problemas: que los archivos que va a tocar sean los que esperabas, que las dependencias estén completas, y que respete los gotchas del CLAUDE.md — sobre todo que los secretos no terminen en el repositorio.
Cuando Claude empieza a fallar
Repite enfoques que ya descartaste. Olvida restricciones que mencionaste al inicio. Las respuestas se ponen vagas. Eso es saturación de contexto, y se arregla con dos comandos.
Cada archivo leído, cada test corrido y cada intento fallido consume espacio. Conforme se llena, la atención del modelo se reparte entre más contenido y la información temprana pierde peso. No es que el modelo empeore — es que el contexto se ensució.
← Desliza para ver el diagrama completo →
/compact
- Quieres continuar lo que estabas haciendo
- Después de un debug largo que sí funcionó
- Entre pasos del mismo feature
- Claude se pone lento o vago pero va bien encaminado
/clear
- Cambias a una tarea sin relación con la anterior
- Claude repite el mismo error dos o más veces
- El contexto quedó contaminado con suposiciones falsas
- Terminaste un feature y vas al siguiente
Compacta antes de que sea urgente. La compactación automática se dispara cuando el contexto ya casi está lleno — pero en ese punto el modelo ya opera degradado y el resumen sale peor. Compactar manualmente, con espacio todavía disponible, produce mejores resúmenes.
# Ver qué está llenando tu contexto antes de decidir /context # Resumir conservando solo lo que importa /compact enfócate en el bug de autenticación # Sesión nueva con nombre para encontrarla después /clear nombre-del-feature # Recuperar una sesión anterior /resume
Un detalle que cambia el ritmo de trabajo: el CLAUDE.md se recarga desde disco en cada sesión nueva. Usar /clear entre features no te cuesta las decisiones del proyecto — solo la conversación.
Skills: workflows que no vuelves a explicar
Un skill es una carpeta con un archivo SKILL.md adentro. Eso es toda la mecánica.
Claude lee la descripción de cada skill al inicio de la sesión y activa la que coincida con tu petición. El resto del archivo solo se carga cuando se dispara — por eso puedes tener muchos sin saturar el contexto.
.claude/skills/mi-skill/SKILL.md # solo este proyecto ~/.claude/skills/mi-skill/SKILL.md # todos tus proyectos
--- name: revisar-seguridad description: > Úsalo cuando el usuario quiera revisar código por vulnerabilidades. Dispara con: "revisa la seguridad", "busca vulnerabilidades", "audita este endpoint", "esto es seguro?", "checa por inyección SQL". argument-hint: <ruta o módulo a revisar> --- # Revisión de seguridad ## Paso 1 — Alcance - Lee los archivos indicados - Identifica entradas de usuario y accesos a datos ## Paso 2 — Revisar Contra esta lista, en orden: - Inyección (SQL, comandos, plantillas) - Autenticación y autorización rota - Secretos en el código o en logs - Validación de entrada faltante - Dependencias con CVEs conocidos ## Paso 3 — Reportar Por cada hallazgo: severidad, ubicación exacta, por qué es explotable, y el fix concreto. ## Reglas - NO arreglar nada sin aprobación - Ordenar hallazgos por severidad, no por archivo - Si no hay hallazgos, decirlo — no inventar
El campo description es el 80% del trabajo. Es lo único que Claude lee para decidir si activa el skill. Escribe ahí las frases exactas que dirías en voz alta, no una descripción formal. Si no coincide con cómo hablas, el skill nunca se dispara.
Skill, comando o subagente
- Skill
- Un workflow que quieres que Claude siga igual cada vez. Claude la activa sola cuando la descripción encaja, y tú con
/nombre— ambas cosas van de fábrica, sin configurar nada. - Hook
- Un script que corre automáticamente antes o después de una acción. No es conversacional — es plomería.
- Subagente
- Un asistente con su propio contexto y herramientas limitadas. Úsalo cuando la tarea generaría mucho ruido en tu sesión principal.
Quién puede disparar la skill. Por defecto la disparan los dos: Claude cuando la descripción encaja, y tú con /nombre. Dos campos cambian eso.
disable-model-invocation: true impide que Claude la dispare sola — imprescindible en skills con efectos secundarios, como un deploy, donde quieres ser tú quien decide. Y user-invocable: false la oculta del menú /, útil cuando es conocimiento de fondo y no una acción que tenga sentido invocar.
Un skill debe tener un solo trabajo bien definido. «Revisar seguridad» es un buen skill. «Ayudar con calidad de código» es demasiado amplio y nunca se activa de forma confiable.
Las que ya vienen incluidas
Antes de escribir la tuya, revisa lo que Claude Code trae de fábrica. /code-review revisa el diff, un PR o una ruta, con niveles de esfuerzo de low a max y --fix para aplicar los hallazgos. /simplify limpia y refactoriza sin cazar bugs. /security-review busca vulnerabilidades en el diff. /doctor diagnostica tu configuración. Y /batch parte un cambio masivo en unidades independientes y lanza un subagente por cada una en worktrees aislados.
Cuándo agregar cada pieza
No por calendario. Por síntoma.
| Herramienta | La señal que te dice que ya toca |
|---|---|
| Skill | Escribiste el mismo prompt por tercera vez. Guárdalo como workflow en lugar de re-explicarlo. |
| Hook | Quieres que algo pase automáticamente después de cada edición — lint, format, tests. |
| Subagente | Una tarea recurrente necesita reglas propias y contexto aislado, o genera tanto ruido que ensucia tu sesión. |
Regla con paths | Tu CLAUDE.md pasa de 200 líneas. Mueve lo específico de un lenguaje o carpeta a .claude/rules/. |
| Spec / SDD práctica | Un feature toca tres o más archivos. Escribe el documento de diseño antes de implementar. No es una función de Claude Code, es una forma de trabajar. |
| MCP server | Necesitas datos que viven fuera del repo — tickets, documentos, calendario, CRM. |
| Plugin | Un segundo repositorio necesita el mismo setup. Empaqueta skills, hooks, subagents y MCP en una unidad instalable. |
| Worktree | Necesitas que varias sesiones trabajen sin pisarse en el mismo repositorio. |
| Agent team experimental | Partes genuinamente independientes que además necesitan hablarse entre sí. Viene desactivado por defecto: hay que habilitarlo. |
El principio que conecta todo: la Fase de optimización no es prerequisito de nada. Es consecuencia de haber trabajado lo suficiente en las fases anteriores como para saber qué te está costando tiempo.
El ciclo completo, en una línea
Plan Mode → contexto en CLAUDE.md → pedir → revisar plan → aprobar → ejecutar → commit → /clear → repetir
Comandos del día a día
Hay unos setenta comandos. Estos son los que se usan de verdad mientras programas. Filtra por texto o por categoría.
24 comandos
/clear [nombre]Sesión nueva con el contexto vacío. El nombre la etiqueta para encontrarla luego en /resume.
/resumeVolver a una conversación anterior desde un selector.
/rewindDeshacer código y conversación hasta un punto anterior.
/branch [nombre]Ramificar la conversación para probar otro camino sin perder este.
/statusEstado de la sesión actual.
/context [all]Ver qué está llenando el contexto, como rejilla de colores.
/compact [instrucciones]Resumir la conversación y seguir. Las instrucciones enfocan el resumen.
/memoryEditar los CLAUDE.md y ver o desactivar el auto memory.
/usageTokens consumidos en la sesión. También /cost.
/plan [descripción]Entrar en Plan Mode desde el prompt, sin usar Shift+Tab.
/initGenerar el CLAUDE.md analizando el repositorio.
/subtask <instrucción>Delegar una tarea lateral a un subagente que reporta de vuelta.
/btw [pregunta]Pregunta suelta que no entra en el historial de la conversación.
/code-review [nivel] [--fix]Revisar el diff, un PR o una ruta. Niveles de low a max. También /review.
/security-reviewBuscar vulnerabilidades en el diff.
/simplifyLimpiar y refactorizar. No caza bugs; para eso está /code-review.
/diffVisor interactivo de los cambios sin commitear.
/debug [descripción]Activar el logging de depuración. La descripción enfoca el análisis.
/doctorDiagnóstico de la configuración; propone recortes a un CLAUDE.md grande.
/permissionsGestionar las reglas de permitir, preguntar y denegar.
/model [modelo]Cambiar de modelo y guardarlo como predeterminado.
/mcpGestionar las conexiones a servidores MCP.
/hooksVer la configuración de hooks por evento.
/helpAyuda y lista completa de comandos disponibles.
Ningún comando coincide con ese filtro.
Atajos que ahorran tiempo
Los comandos son skills. Los personalizados y los de fábrica funcionan igual, así que los tuyos aparecen en este mismo menú / junto a los de arriba — ver sección 07.