Guía práctica · Desarrollo agéntico

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.

4Conceptos para el día uno
2Flujos según tu proyecto
1Archivo que lo ancla todo
01

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.

Nivel 1

Lo esencial

Día uno
CLAUDE.md contexto del proyecto /init lo genera por ti Plan Mode Shift+Tab × 2 Auto memory aprende solo
Nivel 2

Productividad

Cuando repitas trabajo
Skills workflows reutilizables Hooks automatizaciones MCP servers conexiones externas
Nivel 3

Arquitectura

Proyectos grandes
Subagents agentes delegados Specs / SDD diseño antes de código Agent teams trabajo paralelo Worktrees aislamiento

La 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.

02

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.

Activar 
# 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

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.

03

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.

Setup inicialUna sola vez
  1. Abrir la sesióncd ~/mi-proyecto && claude
  2. Activar Plan ModeShift+Tab × 2. Antes de cualquier prompt.
  3. Explorar«¿Qué hace este proyecto? Describe estructura, stack, entry points y cómo correr los tests.»
  4. Generar contexto/init escanea el repo y genera el CLAUDE.md
  5. Editar CLAUDE.mdAgrega lo que el código no dice: convenciones del equipo, gotchas, decisiones tomadas.
Ciclo de trabajoSe repite por cada feature
  1. Pedir el cambio«Implementa [feature] según el CLAUDE.md»
  2. Revisar el planVerifica archivos tocados, dependencias, que respete tus gotchas.
  3. Aprobar y ejecutar«yes» — Claude sale de Plan Mode e implementa.
  4. Commitear«commit my changes with a descriptive message»
↺ Volver al paso 1 con el siguiente feature
OptimizaciónSolo cuando aparezca la señal — ver sección 08
  1. SkillsRepites el mismo prompt tres o más veces.
  2. SubagentsUna tarea necesita contexto aislado y reglas propias.
  3. Specs (SDD)Un feature toca tres o más archivos.
  4. Hooks, MCP, agent teamsAutomatización, datos externos o trabajo paralelo.
04

El archivo que ancla todo

Claude Code lee el CLAUDE.md al inicio de cada sesión. Sobrevive a /clear, se recarga desde disco, y es lo único que persiste sin que hagas nada.

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.
Esqueleto mínimo 
# 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.

05

Prompts que funcionan

Copiables tal cual. Todos asumen Plan Mode activo y CLAUDE.md en la raíz.

Explorar un repo desconocido 
¿Qué hace este proyecto? Describe la estructura, lenguaje,
framework, entry points y cómo correr los tests.
No modifiques nada.
Entrevista para un proyecto nuevo 
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.
Scaffolding 
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.
Implementar un módulo 
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.
Feature grande — plan escrito primero 
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.

06

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ó.

/compact

Resume y continúa la misma sesión
  • 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

Borra todo, sesión nueva
  • 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.

Variantes útiles 
# 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.

07

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.

Dónde va 
.claude/skills/mi-skill/SKILL.md    # solo este proyecto
~/.claude/skills/mi-skill/SKILL.md  # todos tus proyectos
Anatomía completa 
---
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".
user-invocable: true
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. Se activa solo o con slash si pones user-invocable: true.
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.

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.

08

Cuándo agregar cada pieza

No por calendario. Por síntoma.

HerramientaLa señal que te dice que ya toca
SkillEscribiste el mismo prompt por tercera vez. Guárdalo como workflow en lugar de re-explicarlo.
HookQuieres que algo pase automáticamente después de cada edición — lint, format, tests.
SubagenteUna tarea recurrente necesita reglas propias y contexto aislado, o genera tanto ruido que ensucia tu sesión.
Spec / SDDUn feature toca tres o más archivos. Escribe el documento de diseño antes de implementar.
MCP serverNecesitas datos que viven fuera del repo — tickets, documentos, calendario, CRM.
Agent teamEl proyecto es grande y hay partes genuinamente independientes que pueden avanzar en paralelo.
WorktreeNecesitas que varias sesiones trabajen sin pisarse en el mismo repositorio.

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