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

Proyecto Integrador: Tu Primer Proyecto con Claude Code

Descripción

Este es el módulo final. Todo lo que aprendiste en los módulos 1 al 7 converge aquí en un proyecto real: construirás una herramienta CLI funcional usando Claude Code de principio a fin, aplicando el workflow profesional completo.

El proyecto no se trata de la complejidad de la CLI que construyas. Se trata de demostrar que dominas el workflow completo de Claude Code: CLAUDE.md profesional, skills personalizados, hooks de validación, ciclo Explore → Plan → Code, tests generados por el agente, y commits semánticos. La CLI es el vehículo — el workflow es el destino.

Objetivo del proyecto

Construir una herramienta CLI funcional (Python o TypeScript) usando el workflow completo de Claude Code:

CLAUDE.md → Skills → Hooks → Explore → Plan → Code → Tests → Commit

Al terminar, tendrás:

Un proyecto con CLAUDE.md profesional
Al menos 2 skills personalizados creados y funcionales
Al menos 2 hooks configurados y activos
Una CLI con 3 o más comandos funcionales
Tests generados por Claude Code
Todo commiteado con un mensaje descriptivo

Este proyecto es tu carta de presentación. Demuestra que sabes trabajar con un agente de IA de forma profesional — no como quien escribe prompts casuales, sino como quien configura, planifica, y ejecuta con un sistema.

Por qué una CLI

Elegimos CLI como formato del proyecto por razones concretas:

Razón	Explicación
Terminal-first	Claude Code vive en la terminal. Una CLI es su territorio natural
Framework-agnostic	No necesitas React, Django, ni ningún framework pesado
Resultado tangible	Al terminar, tienes una herramienta que puedes ejecutar y usar
Scope controlado	Una CLI con 3 comandos es alcanzable en 1.5 horas
Demuestra el workflow	Cada fase del ciclo E→P→C se aplica naturalmente

No necesitas experiencia previa construyendo CLIs. Claude Code te guiará en la implementación — tu trabajo es dirigir el proceso usando las herramientas que aprendiste.

Qué construiste en módulos anteriores

Cada módulo te dio una pieza del rompecabezas. Aquí las unes todas:

┌─────────────────────────────────────────────────────────────┐
│                    MÓDULOS ANTERIORES                        │
│                                                             │
│  M01: Qué es Claude Code              → Fundamentos         │
│  M02: Instalación y setup             → Herramienta lista   │
│  M03: CLAUDE.md y memoria             → Contexto persistente│
│  M04: Workflow agéntico (E→P→C)       → Metodología         │
│  M05: Skills y hooks                  → Automatización      │
│  M06: Subagents                       → Delegación          │
│  M07: Integraciones                   → Ecosistema          │
│                                                             │
│  ─────────────────────────────────────────────────────────  │
│                                                             │
│  M08: PROYECTO INTEGRADOR             → TODO junto          │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Lo que ya sabes hacer

CLAUDE.md: Crear un archivo de contexto profesional con las 6 secciones (Módulo 03)
Skills: Crear slash commands personalizados en .claude/skills/ (Módulo 05)
Hooks: Configurar scripts automáticos en settings.json para PreToolUse y PostToolUse (Módulo 05)
Explore: Analizar un proyecto en modo read-only antes de actuar (Módulo 04)
Plan: Diseñar un plan de implementación antes de escribir código (Módulo 04)
Code: Implementar paso a paso con el agente, guiando con multi-turn (Módulo 04)
Tests: Pedirle a Claude que genere y ejecute tests (Módulos 04–05)
Subagents: Delegar tareas de exploración y verificación (Módulo 06)

Si alguno de estos puntos no te suena claro, revisa el módulo correspondiente antes de empezar el proyecto.

Criterios de evaluación

El proyecto se evalúa en 6 dimensiones. Cada una refleja una competencia de los módulos anteriores:

#	Criterio	Peso	Módulo de referencia	Qué se evalúa
1	CLAUDE.md bien estructurado	20%	Módulo 03	Las 6 secciones, < 200 líneas, específico
2	2+ skills creados y funcionales	15%	Módulo 05	Archivos en `.claude/skills/`, invocables
3	2+ hooks configurados	15%	Módulo 05	En `settings.json`, se disparan correctamente
4	Workflow Explore → Plan → Code	20%	Módulo 04	Evidencia de haber seguido el ciclo
5	CLI funcional con 3+ comandos	20%	Práctica	Ejecutable, comandos operativos
6	Tests generados por Claude Code	10%	Módulos 04–05	Al menos 3 tests que pasen

Rúbrica detallada

CLAUDE.md (20%)

Nivel	Descripción
Excelente	6 secciones completas, < 150 líneas, convenciones específicas, comandos ejecutables, reglas accionables
Bueno	5-6 secciones, < 200 líneas, convenciones claras
Suficiente	Al menos 4 secciones, información básica del proyecto
Insuficiente	Genérico, vago, o más de 300 líneas

Skills (15%)

Nivel	Descripción
Excelente	2+ skills con instrucciones claras, ejemplos, y reglas. Se invocan correctamente
Bueno	2 skills funcionales con instrucciones básicas
Suficiente	1 skill funcional
Insuficiente	No hay skills o no funcionan

Hooks (15%)

Nivel	Descripción
Excelente	2+ hooks con matchers, scripts correctos, se disparan automáticamente
Bueno	2 hooks configurados correctamente
Suficiente	1 hook funcional
Insuficiente	No hay hooks o están mal configurados

Workflow E→P→C (20%)

Nivel	Descripción
Excelente	Evidencia clara de Explore (análisis), Plan (diseño), Code (implementación incremental)
Bueno	Se usaron los 3 modos, aunque no de forma óptima
Suficiente	Se usaron al menos 2 de los 3 modos
Insuficiente	Se fue directo a Code sin Explore ni Plan

CLI funcional (20%)

Nivel	Descripción
Excelente	3+ comandos funcionales, help text, manejo de errores, output formateado
Bueno	3 comandos funcionales básicos
Suficiente	2 comandos funcionales
Insuficiente	Menos de 2 comandos o CLI no ejecutable

Tests (10%)

Nivel	Descripción
Excelente	Tests para cada comando, edge cases cubiertos, todos pasan
Bueno	3+ tests que pasan
Suficiente	Al menos 1 test que pasa
Insuficiente	No hay tests o no pasan

Ideas de proyecto

Tú eliges qué CLI construir. Aquí tienes 5 ideas — escoge la que más te interese o inventa la tuya:

Idea 1: Organizador de archivos

$ fileorg scan ./downloads
Found 47 files: 12 images, 8 documents, 15 code files, 12 others

$ fileorg organize ./downloads --by type
Organized 47 files into 4 directories:
  images/     → 12 files
  documents/  → 8 files
  code/       → 15 files
  others/     → 12 files

$ fileorg undo
Restored 47 files to original locations

Comandos: scan, organize, undo Stack sugerido: Python + Click, o TypeScript + Commander

Idea 2: CLI de notas

$ notes add "Revisar PR de autenticación" --tag work
Note created: #42

$ notes list --tag work
#42  Revisar PR de autenticación  [work]  2 min ago
#38  Deploy staging               [work]  1 hour ago
#35  Code review pendiente        [work]  3 hours ago

$ notes search "autenticación"
#42  Revisar PR de autenticación  [work]  2 min ago

Comandos: add, list, search Stack sugerido: Python + Click + JSON storage, o TypeScript + Commander + JSON

Idea 3: Herramienta de productividad Git

$ gitprod status
Branch: feature/auth (3 commits ahead of main)
Modified: 2 files | Staged: 1 file | Untracked: 0

$ gitprod summary --days 7
Last 7 days: 12 commits, 3 branches, +450/-120 lines
Top files: auth.py (8 changes), tests.py (5 changes)

$ gitprod quick "fix login validation"
Staged all changes → Committed → Pushed to feature/auth

Comandos: status, summary, quick Stack sugerido: Python + Click + subprocess, o TypeScript + Commander + child_process

Idea 4: Health checker de APIs

$ healthcheck add https://api.example.com/health --name "Production API"
Endpoint added: Production API

$ healthcheck run
Production API    https://api.example.com/health    ✅ 200 (142ms)
Staging API       https://staging.example.com/health ✅ 200 (238ms)
Payment Service   https://pay.example.com/ping       ❌ 503 (timeout)

$ healthcheck report --format json
{ "total": 3, "healthy": 2, "unhealthy": 1, "results": [...] }

Comandos: add, run, report Stack sugerido: Python + Click + httpx, o TypeScript + Commander + fetch

Idea 5: Analizador de código

$ codestats scan ./src
Scanning ./src...

Language     Files    Lines    Blank    Comment
─────────────────────────────────────────────
Python       12       1,420    180      95
TypeScript   8        890      110      42
Markdown     3        220      30       0
─────────────────────────────────────────────
Total        23       2,530    320      137

$ codestats top --by lines
1. src/services/auth.py         342 lines
2. src/models/user.py           298 lines
3. src/routers/products.py      245 lines

$ codestats diff --since "2025-01-01"
Since Jan 1: +1,200 lines added, -400 lines removed
New files: 5 | Deleted files: 1

Comandos: scan, top, diff Stack sugerido: Python + Click + pathlib, o TypeScript + Commander + fs

Elige tu propia aventura

No estás limitado a estas ideas. Cualquier CLI con 3+ comandos funciona. Solo asegúrate de que:

Tenga al menos 3 comandos distintos
Cada comando reciba argumentos o flags
La CLI tenga help text (--help)
Sea algo que puedas completar en ~1 hora de implementación

Timeline

El proyecto está diseñado para completarse en 1.5 horas si sigues las cápsulas paso a paso:

┌──────────────────────────────────────────────────────────┐
│  TIMELINE DEL PROYECTO (1.5 horas)                       │
│                                                          │
│  Cápsula 02: Setup (25 min)                              │
│  ├── Crear proyecto y CLAUDE.md          10 min           │
│  ├── Crear 2 skills                     10 min           │
│  └── Configurar 2 hooks                  5 min           │
│                                                          │
│  Cápsula 03: Explore + Plan (15 min)                     │
│  ├── Explore: analizar el setup          5 min           │
│  └── Plan: diseñar la CLI              10 min           │
│                                                          │
│  Cápsula 04: Build (35 min)                              │
│  ├── Implementar comando 1             10 min           │
│  ├── Implementar comando 2 (con skill) 10 min           │
│  ├── Implementar comando 3             10 min           │
│  └── Verificar CLI completa             5 min           │
│                                                          │
│  Cápsula 05: Test + Commit (15 min)                      │
│  ├── Generar tests                      5 min           │
│  ├── Revisar código                     5 min           │
│  └── Commit y entrega                   5 min           │
│                                                          │
│  Total: ~90 minutos                                      │
└──────────────────────────────────────────────────────────┘

No te preocupes si te toma más tiempo. El timeline es una guía, no una restricción. Lo importante es completar todos los criterios de evaluación.

Prerequisitos

Antes de empezar, verifica que tienes todo listo:

Técnicos

Claude Code instalado y autenticado (Módulo 02)
Python 3.8+ o Node.js 18+ instalado
Git instalado y configurado
Editor de texto disponible (VS Code, Cursor, Vim, etc.)
Terminal con acceso a Claude Code

Conocimientos

Módulo 01: Qué es Claude Code — completado
Módulo 02: Instalación y setup — completado
Módulo 03: CLAUDE.md y memoria — completado
Módulo 04: Workflow agéntico — completado
Módulo 05: Skills y hooks — completado
Módulo 06: Subagents — completado
Módulo 07: Integraciones — completado

Verificación rápida

Ejecuta estos comandos para confirmar que todo funciona:

# Claude Code
claude --version

# Python (si eliges Python)
python --version
pip --version

# Node.js (si eliges TypeScript)
node --version
npm --version

# Git
git --version

Si alguno falla, revisa el Módulo 02 antes de continuar.

Estructura del proyecto

Las siguientes 4 cápsulas te guían fase por fase:

Cápsula	Fase	Qué harás
02	Setup	CLAUDE.md + 2 skills + 2 hooks
03	Explore + Plan	Analizar setup, diseñar la CLI
04	Build	Implementar 3 comandos con Claude Code
05	Test + Commit	Tests, review, commit, entrega

Cada cápsula es una sesión autocontenida. Puedes hacer una pausa entre cápsulas — tu CLAUDE.md, skills, y hooks persisten en el filesystem.

Antes de empezar

Elige tu stack

Opción	Framework CLI	Testing	Ventaja
Python	Click	pytest	Familiar para la mayoría, sintaxis simple
TypeScript	Commander	vitest	Type safety, buen para devs JS/TS

Ambos funcionan perfectamente con Claude Code. Elige el lenguaje con el que te sientas más cómodo.

Elige tu proyecto

Revisa las 5 ideas de la sección anterior (o inventa la tuya) y decide qué CLI construirás. No le des muchas vueltas — todas son equivalentes para demostrar el workflow.

Mentalidad

Este proyecto no es un examen de programación. No importa si tu CLI es simple o si el código no es perfecto. Lo que importa es que demuestres dominio del workflow de Claude Code:

¿Configuraste CLAUDE.md correctamente?
¿Creaste skills que automatizan tareas repetitivas?
¿Configuraste hooks que validan automáticamente?
¿Seguiste el ciclo Explore → Plan → Code?
¿Dejaste que Claude Code hiciera el trabajo pesado mientras tú dirigías?

Si la respuesta a estas preguntas es sí, el proyecto es un éxito.

Resumen

Proyecto: Construir una CLI funcional con Claude Code usando el workflow completo
Duración: ~1.5 horas
Evaluación: 6 criterios (CLAUDE.md, skills, hooks, workflow, CLI, tests)
Lenguaje: Python (Click) o TypeScript (Commander) — tú eliges
Requisito: 3+ comandos funcionales
Lo que importa: El workflow, no la complejidad del código

Siguiente cápsula: 02 - Setup: CLAUDE.md, skills y hooks — la configuración profesional de tu proyecto.

← AnteriorMCP y Remote Control: conexiones externas Siguiente →Setup: CLAUDE.md, Skills y Hooks