Módulo 8: Proyecto integrador: Tu primer proyecto con Claude Code

Explorar y Planificar: Diseñar Antes de Construir

Objetivo del proyecto

Construir una herramienta CLI funcional usando el workflow completo de Claude Code. En esta cápsula completas la Fase 2: Explore + Plan — usarás Claude Code para analizar tu setup y diseñar la implementación antes de escribir código.

Qué construiste en módulos anteriores

Cápsula 02 (este módulo): Creaste el proyecto con CLAUDE.md, 2 skills, 2 hooks, y el entry point base
Módulo 04: Aprendiste el ciclo Explore → Plan → Code y cuándo usar cada modo

Qué agregarás en este módulo

Al terminar esta cápsula tendrás:

Análisis completo del estado de tu proyecto (Explore)
Plan de implementación detallado para tu CLI (Plan)
Plan revisado e iterado con feedback (multi-turn)
Plan aprobado listo para implementar en la siguiente cápsula

No escribirás código funcional todavía. Esta cápsula es 100% análisis y diseño.

Paso a paso guiado

Paso 1: Abrir Claude Code en el proyecto

Navega al directorio de tu proyecto y abre Claude Code:

cd my-cli-project
claude

Claude lee tu CLAUDE.md automáticamente al iniciar la sesión. No necesitas mencionarlo — ya tiene el contexto de tu proyecto.

Deberías ver algo como:

╭──────────────────────────────────────────────────────╮
│ Claude Code                                          │
│                                                      │
│ /help for help                                       │
│                                                      │
│ Loaded CLAUDE.md (project context)                   │
╰──────────────────────────────────────────────────────╯

El mensaje "Loaded CLAUDE.md" confirma que Claude tiene tu contexto. Si no lo ves, verifica que CLAUDE.md está en la raíz del proyecto.

Paso 2: Explore — Analizar el estado del proyecto

La fase Explore es análisis read-only. Le pides a Claude que investigue el estado actual del proyecto sin hacer cambios.

Prompt de Explore

Escribe esto en Claude Code:

Explora este proyecto y dame un reporte del estado actual. Quiero saber:
1. ¿Qué archivos existen y cuál es la estructura?
2. ¿El CLAUDE.md está completo y es consistente?
3. ¿Los skills están correctamente creados?
4. ¿Los hooks están bien configurados?
5. ¿El entry point de la CLI funciona?
6. ¿Las dependencias están instaladas?

No hagas cambios, solo analiza.

Qué esperar de Claude

Claude va a:

Leer la estructura de directorios — verificar que los archivos existen donde deben estar
Leer CLAUDE.md — confirmar que tiene las 6 secciones y es consistente
Leer los skills — verificar que .claude/skills/create-command/SKILL.md y .claude/skills/add-tests/SKILL.md existen y tienen contenido válido
Leer settings.json — confirmar que los hooks están configurados
Verificar el entry point — leer cli.py o index.ts y confirmar que la estructura es correcta
Verificar dependencias — leer pyproject.toml o package.json

Output típico de Explore

## Reporte del proyecto

### Estructura
El proyecto tiene la estructura esperada:
- CLAUDE.md ✅ (56 líneas, bien estructurado)
- .claude/skills/create-command/SKILL.md ✅
- .claude/skills/add-tests/SKILL.md ✅
- .claude/settings.json ✅ (2 hooks configurados)
- src/cli.py ✅ (entry point con Click)
- tests/ ✅ (vacío, listo para tests)

### CLAUDE.md
Las 6 secciones están presentes:
1. Descripción ✅
2. Stack ✅
3. Estructura ✅
4. Convenciones ✅
5. Comandos ✅
6. Reglas ✅

Observación: La sección de estructura menciona 3 comandos
(command_one, command_two, command_three) pero aún no existen
los archivos. Esto es correcto — se crearán en la fase de
implementación.

### Skills
- /create-command: Template completo, instrucciones claras,
  reglas de naming ✅
- /add-tests: Template con pytest/CliRunner, mínimo 3 tests ✅

### Hooks
- PostToolUse (Write → ruff/eslint): ✅
- PreToolUse (Execute → git commit → tests): ✅

### Entry point
- src/cli.py existe con grupo Click y version_option ✅
- CLI ejecutable: `python -m src.cli --help` funciona ✅

### Dependencias
- click 8.1.7 instalado ✅
- pytest 8.0.0 instalado ✅
- ruff 0.4.0 instalado ✅

### Estado general: Listo para implementación
El proyecto está correctamente configurado. La siguiente
fase es planificar los 3 comandos de la CLI.

Si Claude encuentra problemas

Si el reporte muestra errores, corrígelos antes de continuar. Problemas comunes:

Problema	Solución
CLAUDE.md falta una sección	Agrégala manualmente o pide a Claude que lo haga
Skill tiene error de formato	Revisa que sea Markdown válido
Hook tiene error de JSON	Valida con `python -m json.tool`
Dependencias no instaladas	Ejecuta `pip install -e ".[dev]"` o `npm install`
Entry point no ejecuta	Verifica que `cli.py` / `index.ts` tiene la estructura correcta

Tips para Explore

Sé específico en lo que quieres analizar. "Analiza todo" es peor que "Analiza la estructura, CLAUDE.md, y skills."
Pide que NO haga cambios. La frase "No hagas cambios, solo analiza" es clave. Sin ella, Claude podría empezar a corregir cosas automáticamente.
Verifica el output. Claude puede equivocarse en el análisis. Si dice que algo existe pero no es así, corrígelo.

Paso 3: Plan — Diseñar la CLI

Ahora que sabes que el setup está correcto, diseña la implementación. Activa Plan mode para que Claude genere un plan sin ejecutar nada.

Prompt de Plan

Escribe esto en Claude Code (adapta según tu proyecto elegido):

Ejemplo para CLI de notas:

/plan Diseña la implementación de mi CLI de notas con estos 3 comandos:

1. "add" — Crear una nota con texto y tag opcional
2. "list" — Listar todas las notas, con filtro por tag opcional
3. "search" — Buscar notas por texto

Considera:
- La arquitectura definida en CLAUDE.md
- Storage: archivo JSON en ~/.notes/notes.json
- Cada nota tiene: id, texto, tag (opcional), timestamp
- El output debe ser formateado y legible

Dame un plan detallado con archivos a crear, orden de implementación,
y dependencias entre componentes.

Ejemplo para organizador de archivos:

/plan Diseña la implementación de mi CLI organizadora de archivos con
estos 3 comandos:

1. "scan" — Escanear un directorio y mostrar resumen por tipo
2. "organize" — Organizar archivos en subdirectorios por tipo
3. "undo" — Revertir la última organización

Considera:
- La arquitectura definida en CLAUDE.md
- Categorías: images, documents, code, media, others
- Guardar historial de movimientos para el undo
- Output con tabla formateada

Dame un plan detallado con archivos a crear, orden de implementación,
y dependencias.

Ejemplo para health checker:

/plan Diseña la implementación de mi CLI health checker con estos
3 comandos:

1. "add" — Agregar un endpoint con nombre y URL
2. "run" — Ejecutar health check en todos los endpoints
3. "report" — Generar reporte en formato table o JSON

Considera:
- La arquitectura definida en CLAUDE.md
- Storage: archivo JSON en ~/.healthcheck/endpoints.json
- Mostrar status code, tiempo de respuesta, y estado
- Requests async para check múltiples endpoints en paralelo

Dame un plan detallado con archivos a crear, orden de
implementación, y dependencias.

Qué esperar del plan

Claude debería producir un plan estructurado como este:

## Plan: CLI de Notas

### Archivos a crear

1. src/commands/add.py (CREAR) — Comando para agregar notas
2. src/commands/list.py (CREAR) — Comando para listar notas
3. src/commands/search.py (CREAR) — Comando para buscar notas
4. src/utils.py (CREAR) — Storage manager y formateo
5. src/cli.py (MODIFICAR) — Registrar los 3 comandos

### Arquitectura de storage

~/.notes/ └── notes.json { "notes": [ { "id": 1, "text": "...", "tag": "work", "created_at": "2026-02-28T10:30:00" } ], "next_id": 2 }


### Orden de implementación

1. **src/utils.py** — Storage manager (load_notes, save_notes,
   get_notes_path) y output formatter. Se implementa primero
   porque los 3 comandos dependen de él.

2. **src/commands/add.py** — Primer comando. Depende de utils
   para guardar la nota. Es el más simple: recibe texto, crea
   nota, guarda.

3. **src/commands/list.py** — Segundo comando. Depende de utils
   para cargar notas. Agrega filtro por tag con --tag.

4. **src/commands/search.py** — Tercer comando. Depende de utils
   para cargar y filtrar notas por texto.

5. **src/cli.py** — Registrar los 3 comandos. Se modifica después
   de cada comando para ir probando incrementalmente.

### Dependencias entre componentes

src/utils.py ├── load_notes() → Lee ~/.notes/notes.json ├── save_notes() → Escribe ~/.notes/notes.json ├── get_notes_path() → Retorna path al archivo └── format_note() → Formatea una nota para output

src/commands/add.py → usa utils.save_notes, utils.load_notes src/commands/list.py → usa utils.load_notes, utils.format_note src/commands/search.py → usa utils.load_notes, utils.format_note


### Consideraciones

- Crear directorio ~/.notes/ si no existe
- Manejar el caso de archivo JSON vacío o inexistente
- IDs autoincrementales
- Timestamps en ISO 8601
- Output con click.echo(), colores opcionales con click.style()

### Riesgos

- Si dos instancias escriben al mismo tiempo → corrupción de JSON
  (aceptable para scope de este proyecto)
- El archivo puede crecer mucho → no implementamos paginación
  en list (fuera de scope)

¿Procedo con la implementación?

Evaluando el plan

Antes de aprobar, revisa estos puntos:

Aspecto	Qué verificar
Completitud	¿Cubre los 3 comandos? ¿Incluye utils?
Orden	¿Las dependencias están en el orden correcto?
Consistencia	¿El plan es coherente con CLAUDE.md?
Scope	¿Es alcanzable en ~35 minutos de implementación?
Riesgos	¿Identificó limitaciones? ¿Son aceptables?

Paso 4: Iterar sobre el plan

El plan no tiene que ser perfecto en la primera versión. El poder del Plan mode es que puedes iterar antes de escribir código.

Iteración 1: Agregar detalle

Si el plan es demasiado genérico en alguna parte:

El plan se ve bien. Pero necesito más detalle en src/utils.py.
¿Qué funciones exactas va a tener? ¿Qué parámetros reciben?
¿Qué retornan? Dame la firma de cada función.

Claude actualiza el plan:

### src/utils.py — Detalle de funciones

def get_notes_path() -> Path:
    """Retorna ~/.notes/notes.json, crea directorio si no existe."""

def load_notes() -> dict:
    """Lee el archivo JSON. Retorna {"notes": [], "next_id": 1}
    si no existe."""

def save_notes(data: dict) -> None:
    """Escribe el dict al archivo JSON con indentación."""

def format_note(note: dict, detail: bool = False) -> str:
    """Formatea una nota para display.
    Formato básico: #42  Texto de la nota  [tag]  2 min ago
    Formato detail: incluye timestamp completo y metadata."""

def time_ago(timestamp: str) -> str:
    """Convierte ISO timestamp a 'X min/hours/days ago'."""

Iteración 2: Cambiar una decisión

Si no estás de acuerdo con algo del plan:

No quiero usar un archivo JSON en el home directory. Prefiero
que el storage sea un archivo .notes.json en el directorio
actual. Así cada proyecto puede tener sus propias notas.
Actualiza el plan.

Claude ajusta:

### Cambio: Storage local

En lugar de ~/.notes/notes.json, el archivo será .notes.json
en el directorio actual (cwd).

Cambios en el plan:
- get_notes_path() → retorna Path(".notes.json")
- No necesita crear directorio
- Agregar .notes.json a .gitignore
- Documentar en CLAUDE.md que el storage es local

Iteración 3: Simplificar

Si el plan es demasiado complejo para el scope:

El formato "time_ago" agrega complejidad innecesaria. Mejor
muestra el timestamp directo en formato corto (Feb 28, 10:30).
Simplifica.

Claude ajusta:

### Simplificación

Eliminamos time_ago(). En su lugar, format_note() muestra
el timestamp como "Feb 28, 10:30" usando strftime.

Reducción: -1 función, -15 líneas estimadas.

Cuántas iteraciones hacer

Mínimo: 1 iteración (revisar y ajustar al menos algo)
Ideal: 2-3 iteraciones
Máximo: 4-5 (si pasas de 5, probablemente estás sobre-analizando)

El objetivo no es el plan perfecto — es un plan suficientemente bueno para empezar a implementar con confianza.

Paso 5: Aprobar el plan

Cuando estés satisfecho con el plan, apruébalo explícitamente:

El plan se ve bien. Tiene la estructura correcta, las
dependencias están claras, y el scope es manejable.

Vamos a implementar en la siguiente sesión siguiendo este plan.
No implementes nada todavía — solo confirma que entendiste el
plan completo.

Claude confirma:

Entendido. El plan está aprobado:

1. src/utils.py — Storage y formateo (primero)
2. src/commands/add.py — Comando add (segundo)
3. src/commands/list.py — Comando list (tercero)
4. src/commands/search.py — Comando search (cuarto)
5. src/cli.py — Registrar comandos (incremental)

Listo para implementar cuando digas. Cada paso seguirá
las convenciones de CLAUDE.md y los templates de los skills.

¿Por qué no implementar en la misma sesión?

Puedes hacerlo — nada te lo impide. Pero hay razones para separar Plan de Code:

Context window: La sesión de Plan ya consumió tokens. Una sesión nueva tiene contexto fresco.
Reflexión: Puedes pensar en el plan antes de implementar. A veces encuentras mejoras después de alejarte.
Práctica: Separar Explore → Plan → Code como fases distintas entrena el hábito del workflow profesional.

Si prefieres continuar en la misma sesión, avanza directamente a la Cápsula 04.

Conversación completa de ejemplo

Aquí una conversación completa de Explore + Plan para referencia. Este ejemplo usa la CLI de notas con Python:

Tú:
Explora este proyecto y dame un reporte del estado actual.
¿Qué archivos existen? ¿El CLAUDE.md está completo?
¿Los skills y hooks están configurados? No hagas cambios.

Claude:
[Lee directorios, CLAUDE.md, skills, settings.json]

## Reporte del proyecto: notes-cli

### Estructura ✅
- CLAUDE.md (52 líneas)
- .claude/skills/create-command/SKILL.md ✅
- .claude/skills/add-tests/SKILL.md ✅
- .claude/settings.json (2 hooks) ✅
- src/cli.py (entry point Click) ✅
- pyproject.toml ✅

### CLAUDE.md ✅
6 secciones completas, < 200 líneas, convenciones claras.
Nota: los nombres de comandos en la estructura
(command_one, etc.) deberían actualizarse a add, list, search
después de la planificación.

### Skills ✅
Ambos skills tienen templates, instrucciones, y reglas.

### Hooks ✅
PostToolUse → ruff, PreToolUse → pytest antes de commit.

### Estado: Listo para planificación.

───────────────────────────────────────────

Tú:
Buena observación sobre los nombres en CLAUDE.md. Los
actualizaremos después de planificar.

/plan Diseña la implementación de mi CLI de notas con 3 comandos:
1. "add" — Crear nota con texto y tag opcional
2. "list" — Listar notas con filtro por tag
3. "search" — Buscar notas por texto
Storage: .notes.json en el directorio actual.

Claude:
[Genera plan detallado]

## Plan: notes-cli

### Archivos a crear/modificar
1. src/utils.py (CREAR) — Storage y formateo
2. src/commands/__init__.py (CREAR) — Package
3. src/commands/add.py (CREAR) — Comando add
4. src/commands/list_notes.py (CREAR) — Comando list
5. src/commands/search.py (CREAR) — Comando search
6. src/cli.py (MODIFICAR) — Registrar comandos

### Nota sobre naming
El archivo para "list" se llama list_notes.py para evitar
conflicto con el built-in list de Python.

### Orden de implementación
[plan detallado...]

### Riesgos
[limitaciones identificadas...]

¿Procedo?

───────────────────────────────────────────

Tú:
Bien pensado lo de list_notes.py. Dos ajustes:
1. Agrega un flag --json a list para output en JSON
2. En search, que sea case-insensitive

Actualiza el plan.

Claude:
[Actualiza el plan con los ajustes]

### Cambios al plan

1. list_notes.py: Agregado --json/-j flag
   - Cuando --json: output con json.dumps(notes, indent=2)
   - Cuando no: output formateado (default)

2. search.py: Búsqueda case-insensitive
   - Convertir tanto el query como el texto a lowercase
     antes de comparar

El resto del plan se mantiene igual.

¿Listo para implementar?

───────────────────────────────────────────

Tú:
El plan está aprobado. No implementes todavía. Confirma
que tienes claro el plan completo.

Claude:
Plan confirmado. Implementaré en este orden:

1. src/utils.py — 5 funciones (load, save, path, format, etc.)
2. src/commands/add.py — @click.command con text arg y --tag
3. src/commands/list_notes.py — @click.command con --tag y --json
4. src/commands/search.py — @click.command con query arg, case-insensitive
5. src/cli.py — Registrar los 3 comandos

Storage en .notes.json local. Convenciones de CLAUDE.md.
Listo cuando tú digas.

Errores comunes en esta fase

Error 1: Saltar Explore

El problema: Ir directo a Plan sin verificar que el setup está correcto.

Consecuencia: Claude planifica sobre una base incorrecta. Si CLAUDE.md tiene un error o falta un skill, el plan lo hereda.

Solución: Siempre haz Explore primero. Son 2 minutos que te ahorran 20.

Error 2: Plan demasiado vago

El problema: Aceptar un plan como "crea los 3 comandos con la estructura del proyecto."

Consecuencia: Claude interpreta libremente y el resultado puede no ser lo que esperabas.

Solución: El plan debe incluir:

Archivos específicos a crear/modificar
Orden de implementación
Dependencias entre componentes
Funciones o métodos principales

Error 3: Plan demasiado detallado

El problema: Pedir que el plan incluya cada línea de código.

Consecuencia: El plan se convierte en implementación, consumiendo contexto innecesariamente.

Solución: El plan es un diseño de alto nivel, no pseudocódigo. Los detalles de implementación son para la fase Code.

Error 4: No iterar

El problema: Aceptar el primer plan sin revisarlo.

Consecuencia: Pierdes la oportunidad de influir en la solución antes de que se escriba código.

Solución: Lee el plan completo. Haz al menos 1 iteración. Cuestiona decisiones que no entiendas.

Error 5: Demasiadas iteraciones

El problema: 10 rondas de feedback sin aprobar nunca.

Consecuencia: Parálisis por análisis. El plan nunca es perfecto — en algún punto, es mejor implementar y ajustar sobre la marcha.

Solución: Máximo 4-5 iteraciones. Si después de 5 rondas no estás satisfecho, el problema puede ser el scope (demasiado grande) o la ambigüedad (redefine el objetivo).

Checklist: ¿Tu plan está listo?

Antes de pasar a la Cápsula 04, verifica:

Ejecutaste Explore y el setup está correcto
El plan lista todos los archivos a crear/modificar
El orden de implementación respeta las dependencias
Cada comando tiene su archivo y funcionalidad definida
El plan es coherente con CLAUDE.md
Iteraste al menos 1 vez con feedback
El plan es realizable en ~35 minutos
Aprobaste el plan explícitamente

Si todo está marcado, estás listo para la Fase 3: Build.

Tips para dar buen feedback durante planificación

Sé específico, no vago

❌ "No me gusta el plan, cámbialo"
✅ "El comando list debería tener un flag --json. Agrégalo al plan."

Explica el por qué

❌ "No uses archivo en el home directory"
✅ "Prefiero storage local (.notes.json en cwd) porque quiero
    que cada proyecto tenga sus propias notas"

Acepta trade-offs

✅ "Entiendo que no implementamos paginación. Es aceptable
    para este scope."

Cuestiona lo que no entiendas

✅ "¿Por qué el archivo se llama list_notes.py y no list.py?"

Da feedback constructivo

✅ "Me gusta la separación en utils.py. Agrega también una
    función para validar que el texto no está vacío."

Comparación: Con Plan vs Sin Plan

Sin Plan (directo a Code)

Tú: "Implementa una CLI de notas con 3 comandos"

Claude: [Empieza a crear archivos inmediatamente]
→ Elige una estructura que tal vez no te gusta
→ Usa storage en home directory (tú querías local)
→ No incluye --json en list (no sabía que lo querías)
→ Search es case-sensitive (tú querías insensitive)

Resultado: 3-4 rondas de correcciones después de implementar

Con Plan (Explore → Plan → Code)

Tú: "Explora el proyecto. Después, planifica la CLI."

Claude: [Analiza, diseña, presenta plan]
Tú: "Cambia storage a local, agrega --json, search insensitive"
Claude: [Actualiza plan]
Tú: "Aprobado. Implementa."

Claude: [Implementa exactamente lo acordado]

Resultado: 0-1 correcciones. El código encaja a la primera.

Impacto medible

Métrica	Sin Plan	Con Plan
Correcciones post-implementación	3-5	0-1
Tiempo total	Más (por rehacer)	Menos
Consumo de context window	Alto (iteraciones de código)	Bajo (iteraciones de texto)
Satisfacción con el resultado	Variable	Alta

La iteración más barata es la que ocurre en texto (Plan), no en código (Code). Cambiar una línea en el plan cuesta 0 tokens de implementación. Cambiar una línea en código implementado puede requerir ajustes en 3-4 archivos.

Troubleshooting

"Claude no entra en Plan mode"

Si escribes /plan y Claude empieza a implementar directamente:

Detente. No implementes nada. Solo quiero el plan.
Dame un diseño con archivos a crear, orden de implementación,
y dependencias. No escribas código todavía.

La frase clave es "no implementes nada" o "no escribas código todavía".

"El plan es demasiado corto"

Si Claude da un plan de 3 líneas:

El plan es demasiado superficial. Necesito más detalle:
- Lista exacta de archivos a crear
- Funciones principales de cada archivo
- Dependencias entre módulos
- Qué se implementa primero y por qué

"El plan incluye tecnologías que no quiero"

No quiero usar SQLite para storage. Quiero un archivo JSON
simple. Actualiza el plan.

Claude debería ajustar sin resistencia. Si insiste, sé firme: "Usa JSON. No SQLite."

"No sé qué feedback dar"

Pregúntate:

¿Los archivos están donde yo los pondría?
¿El orden de implementación tiene sentido?
¿Hay algo que falta en el plan?
¿El scope es realista para 35 minutos?
¿Las decisiones técnicas son las que yo tomaría?

Si la respuesta a todas es sí, aprueba el plan.

Resumen

Lo que hiciste en esta cápsula:

Abriste Claude Code en tu proyecto y verificaste que lee CLAUDE.md
Ejecutaste Explore para analizar el estado del setup
Generaste un plan con /plan para diseñar los 3 comandos de tu CLI
Iteraste sobre el plan con al menos 1 ronda de feedback
Aprobaste el plan listo para implementar

La fase Explore → Plan te da confianza de que:

Tu setup es correcto (no vas a descubrir errores a mitad de implementación)
Tu diseño está pensado (no vas a improvisar la arquitectura)
Claude tiene un plan claro (las instrucciones son explícitas, no ambiguas)

Conexión con el workflow profesional:

La secuencia Explore → Plan no es un capricho académico. Es la misma secuencia que usan los mejores engineers:

Entiende el terreno (Explore)
Diseña la solución (Plan)
Ejecuta con confianza (Code)

La diferencia es que con Claude Code, cada fase tiene un mecanismo concreto. No es un concepto abstracto — es una herramienta que usas con prompts específicos.

Siguiente cápsula: 04 - Construir con Claude Code — donde implementarás los 3 comandos usando Agent mode, skills, y hooks.

← AnteriorSetup: CLAUDE.md, Skills y Hooks Siguiente →Construir con Claude Code: Implementación