Pokédex en 54 Minutos con Claude Code (y la Lección Más Valiosa)

Construir una aplicación web desde cero normalmente implica: 1 hora de planning, 3-4 horas de coding, 1 hora peleándote con tests, 30 minutos configurando Docker, y otros 30 minutos escribiendo un README que nadie leerá.

Total: 5-7 horas. Eso si todo sale bien (spoiler: nunca sale bien).

Hoy vas a ver cómo construí una Pokédex production-ready con Flask + HTMX en 53 minutos usando Claude Code. No es clickbait. No es un MVP de juguete. Es una app con:

• ✅ 96% test coverage
• ✅ Docker funcionando
• ✅ 0 linting errors
• ✅ Documentación completa
• ✅ Git history limpia

Y lo mejor: tú puedes replicar este proceso para cualquier proyecto. No solo Pokédex. Cualquier cosa.

🎯 El Objetivo

Quería construir una Pokédex web que:

• Muestre los 151 Pokémon de Gen 1
• Tenga vistas detalladas con stats, tipos y habilidades
• Sea responsive (móvil y desktop)
• Incluya tests (pytest)
• Sea desplegable con Docker

Tech Stack:

• Flask 3.0 (backend)
• HTMX 1.9 (frontend sin JavaScript manual)
• Tailwind CSS 3.x (estilos)
• PokeAPI (datos)

El reto: ¿Cuánto tiempo tomaría con Claude Code vs desarrollo manual?

🚀 El Proceso: 3 Pasos Simples

Paso 0: Setup Inicial (2 min)

Creé dos archivos simples:

PROJECT_IDEA.md - La idea del usuario:

# Idea de Proyecto: Pokédex Web

Quiero una aplicación web de Pokédex con:
- Lista de los primeros 151 Pokémon
- Vista detallada con stats, tipos, habilidades, imagen
- Navegación entre Pokémon

Stack: Flask + HTMX + Tailwind CSS + PokeAPI

BUILD_LOG.md - Para documentar el proceso:

# Build Log: Pokédex Flask + HTMX

Documentación paso a paso del proceso de construcción.

Todo comienza con un simple prompt: "Lee BUILD_LOG y PROJECT_IDEA para tener contexto"

Paso 1: Generar el Plan (5 minutos)

Comando: Invocar el skill writing-plans

Claude Code lee el PROJECT_IDEA.md y genera automáticamente un plan detallado de implementación.

Claude Code invoca el skill writing-plans para crear un plan estructurado

Resultado: Plan de 12 tareas guardado en docs/plans/2025-11-17-pokedex-flask-htmx.md

El plan incluye código completo (no pseudocódigo), comandos exactos, y enfoque TDD

Las 12 tareas generadas:

1. Project Setup and Dependencies
2. Flask Application Structure
3. PokeAPI Service Layer
4. Data Transformation Layer
5. Base Templates and Static Files
6. Main Routes - Index and List
7. Pokemon Detail View
8. Search Functionality with HTMX
9. Error Handling and 404 Page
10. Docker Configuration
11. Documentation and README
12. Final Testing and Quality Assurance

Claude Code ofrece dos modos de ejecución. Elegí "Subagent-Driven" para control task-by-task

Paso 2: Ejecución con Subagentes (53 minutos)

Enfoque elegido: Subagent-Driven

• 1 subagente fresco por tarea
• Review entre cada tarea
• Control total del proceso

Cada tarea se ejecuta con un subagente especializado. Timings: 1-4 minutos por tarea

Desglose de Ejecución

Dentro de cada subagente: múltiples tool uses (Bash, Write, Read, Git). Todo transparente y auditable.

Test-Driven Development Automático

Cada tarea siguió el ciclo TDD:

1. Red: Escribir tests primero
2. Green: Implementar código para pasar tests
3. Refactor: Mejorar código
4. Commit: Git commit con mensaje descriptivo

Resultado final de tests:

============================= test session starts =============================
17 passed in 0.71s

Coverage: 96% (152/158 statements)
- app/__init__.py: 95%
- app/routes/main.py: 100%
- app/models/pokemon.py: 100%
- app/services/pokeapi.py: 80%

Paso 3: El Resultado

Homepage

Homepage responsive con Tailwind CSS mostrando Pokémon destacados

Features:

• Hero section con título
• 9 Pokémon featured en grid responsive
• CTA para ver todos los Pokémon
• Footer con créditos a PokeAPI

Vista Detallada de Pokémon

Cada Pokémon tiene su propia página con información completa:

Vista básica con nombre, número e imagen oficial de PokeAPI

Features completas:

• Nombre y número del Pokémon
• Imagen oficial de PokeAPI
• Stats completos (HP, Attack, Defense, Speed, etc.)
• Tipos con colores característicos
• Habilidades del Pokémon
• Navegación Previous/Next para explorar fácilmente

Vista detallada de Charmeleon mostrando stats, tipos, habilidades y navegación

📊 Métricas del Proyecto

Las métricas hablan por sí solas:

Comparación: Manual vs Claude Code

Calidad del Código

Git History Limpia

15 commits bien estructurados, uno por tarea. Historia que cuenta el desarrollo.

Commits generados:

64a16d0 docs: update BUILD_LOG with final metrics
9d1319b docs: add comprehensive QA report
0d09b99 test: add integration tests and QA checklist
67a4d6c docs: add comprehensive README and deployment guide
e831eec feat: add Docker configuration for deployment
ce9ad53 feat: add custom 404 and 500 error pages
3950b42 feat: add search backend endpoint (UI pending)
465ade2 feat: add pokemon detail view with stats
c502f64 feat: add index and pokemon list routes
1ae731b feat: add base templates with HTMX and Tailwind
1aeaf3a feat: add Pokemon data models
8c509a7 feat: add PokeAPI service layer with tests
4fcd123 feat: create Flask app factory
2760261 chore: initial project setup
3a2dede docs: reset project with PROJECT_IDEA.md

Mensajes siguiendo Conventional Commits, código con Claude Code attribution.

🎓 Aprendizajes Clave

✅ Lo que funcionó excepcionalmente bien

1. El skill writing-plans es oro

• Genera plan detallado con código completo
• No hay ambigüedad en la implementación
• Tests definidos antes de escribir código
• 5 minutos de planning ahorran horas de refactoring

2. Enfoque Subagent-Driven da control total

• Subagente fresco por tarea = contexto limpio
• Sin "context drift"
• Review entre tareas = calidad continua
• Más rápido que batches grandes

3. TDD automático sin esfuerzo

• Red-Green-Refactor en cada task
• 96% coverage sin pensar en ello
• Bugs detectados temprano
• Confianza para deployar

4. Commits frecuentes = historia clara

• 1 commit por task
• Git log como documentación
• Fácil rollback si es necesario

🎯 Decisiones Técnicas Acertadas

HTMX en lugar de React/Vue:

• Zero JavaScript escrito manualmente
• Interactividad completa con HTML attributes
• Curva de aprendizaje casi nula
• Bundle size mínimo

Tailwind CSS vía CDN:

• No build step necesario
• Responsive inmediato
• Desarrollo más rápido
• Prototyping rápido

Docker desde el inicio:

• Production-ready desde task 10
• Build y run testeados
• Deploy a cualquier cloud en minutos

🐳 Deploy en Producción (Bonus)

El proyecto está listo para deployar:

Opción 1: Railway (1 click)

# Install Railway CLI
npm install -g @railway/cli

# Deploy
railway init
railway up

Opción 2: Render (git push)

1. Conectar GitHub repo
2. Configurar:
   • Build: pip install -r requirements.txt
   • Start: python run.py
3. Deploy automático en cada push

Opción 3: Docker Compose (anywhere)

docker-compose build
docker-compose up -d

# App running on http://localhost:5000

📁 Estructura Final del Proyecto

pokedex-flask-htmx/
├── app/
│   ├── __init__.py          # App factory + error handlers
│   ├── config.py            # Dev/Test/Prod configs
│   ├── models/
│   │   └── pokemon.py       # Pokemon dataclasses
│   ├── routes/
│   │   └── main.py          # 5 routes
│   ├── services/
│   │   └── pokeapi.py       # PokeAPI integration
│   ├── static/css/
│   │   └── styles.css       # Animations
│   └── templates/
│       ├── base.html
│       ├── index.html
│       ├── pokemon_list.html
│       ├── pokemon_detail.html
│       ├── components/      # Reusable components
│       └── errors/          # 404, 500 pages
├── tests/
│   ├── test_app.py          # 2 tests
│   ├── test_pokeapi_service.py  # 3 tests
│   ├── test_pokemon_model.py    # 3 tests
│   ├── test_routes.py           # 7 tests
│   └── test_integration.py      # 2 tests
├── docs/
│   ├── plans/               # Implementation plan
│   ├── BUILD_LOG.md         # Process documentation
│   ├── QA_REPORT.md         # Quality assurance
│   └── SCREENSHOTS_GUIDE.md # Screenshots guide
├── Dockerfile
├── docker-compose.yml
├── README.md
├── DEPLOYMENT.md
└── requirements.txt

Total: ~1,500 LOC (production + tests + templates)

💡 ¿Cuándo usar Claude Code así?

✅ Ideal para:

• MVPs rápidos: De idea a producción en horas
• Learning projects: Aprende best practices viendo el código generado
• Prototypes: Valida ideas rápidamente
• Side projects: Maximiza tiempo limitado
• Refactoring: Genera plan detallado antes de tocar código legacy

⚠️ Consideraciones:

• Review siempre: Aunque la calidad es alta, siempre revisa el código
• Tests son críticos: El 96% coverage te da confianza, úsalo
• Adapta el plan: El plan es un punto de partida, ajusta según necesites
• Git commits: Historia limpia facilita debugging futuro

🚀 Próximos Pasos

Para llevar este proyecto más allá:

1. Caching con Redis

   • Cachear respuestas de PokeAPI
   • Reducir latencia
   • Manejar rate limits

2. Database local

   • PostgreSQL o SQLite
   • Seed data de PokeAPI
   • Offline-first

3. Features adicionales

   • Sistema de favoritos (localStorage)
   • Comparar 2 Pokémon lado a lado
   • Filtros por tipo, stats, generación

4. CI/CD

   • GitHub Actions para tests
   • Deploy automático
   • Quality gates (coverage, linting)

🤔 Plot Twist: Cuando Probé la App

Antes de publicar este post, hice lo que deberías hacer siempre: probar la aplicación.

Homepage: ✅ Funcionando Lista de Pokémon: ✅ Funcionando Click en un Pokémon para ver detalle: ❌ No hacía nada

Momento de pánico. 😱

Revisé el código y encontré dos problemas:

Problema 1: Faltaba el link en las tarjetas

• ✅ Ruta /pokemon/<name> implementada
• ✅ Template pokemon_detail.html completo
• ✅ Tests pasando (17/17)
• ❌ Faltaba el <a> en las tarjetas de Pokémon

El componente pokemon_card.html tenía literalmente un comentario: <!-- Pokemon detail route will be added in Task 7 -->. Claude Code implementó Task 7... pero nunca actualizó el componente de Task 5. 🤦‍♂️

Problema 2: Búsqueda implementada pero invisible

• ✅ Ruta /search implementada con HTMX
• ✅ Backend filtra por nombre y número
• ✅ Tests pasando (15/15)
• ❌ Faltaba el <input> en el template

El template pokemon_list.html solo mostraba el grid. El search bar nunca fue añadido al HTML.

La Lección Más Importante

96% test coverage no garantiza que la UX funcione. Los tests validaban:

• ✅ Que la ruta existe
• ✅ Que retorna HTML
• ✅ Que los templates renderizan

Pero ningún test verificaba que puedes hacer click en un Pokémon desde la homepage.

El Fix (1 minuto)

Arreglé el link en pokemon_card.html envolviendo el <div> con un <a>:

<a href="{{ url_for('main.pokemon_detail', name=pokemon.name) }}"
   class="pokemon-card block bg-white rounded-lg shadow-md p-4 hover:shadow-xl">
    <!-- contenido de la tarjeta -->
</a>

Probé de nuevo: El click funciona. Commit aquí.

Para la búsqueda, decidí no arreglarla ahora. ¿Por qué?

• El backend está completo y testeado
• Es una feature "nice to have", no crítica
• El proyecto ya cumple su objetivo principal
• Quería mostrarte la realidad: a veces priorizas qué arreglar

¿Significa que Claude Code falló?

No. Significa que:

1. ✅ El código estaba 95% completo
2. ✅ La arquitectura era correcta
3. ✅ Los tests unitarios pasaban
4. ❌ Faltaba validación de integración end-to-end

En desarrollo tradicional (5-7 horas), probablemente habría pasado lo mismo. La diferencia: con Claude Code encontré el problema en el minuto 54, no después de 7 horas.

Tiempo total real: 54 minutos (53 de desarrollo + 1 de fix).

💬 Conclusión

Prometí una Pokédex production-ready en 1 hora. Fueron 54 minutos (53 de desarrollo + 1 arreglando el click).

Lo que normalmente tomaría 5-7 horas (y varios cafés ☕), Claude Code lo completó en menos de 1 hora con métricas sólidas:

• ✅ 96% test coverage
• ✅ 0 linting errors
• ✅ Production-ready (después de 1 fix trivial)
• ✅ Documentación completa
• ✅ Git history limpia

El secreto: Un plan detallado + ejecución disciplinada + TDD automático + SIEMPRE probar la app.

No se trata de "generar código rápido". Se trata de generar código de calidad, bien testeado, bien documentado, desplegable desde día uno... y validar que realmente funciona antes de celebrar. 🎉

🎬 ¿Qué construirás tú?

Este mismo workflow funciona para:

• Blog con Django + Alpine.js
• Dashboard con FastAPI + Vue
• API REST con Express + TypeScript
• E-commerce con Rails + Hotwire

El límite es tu imaginación.

---

⚠️ Disclaimer: La Realidad de Trabajar con AI

Si pruebas este proyecto (o cualquier otro generado con Claude Code), es muy probable que encuentres algo que:

• No funciona exactamente como esperabas
• Falta conectar (como el search bar aquí)
• Necesita un pequeño ajuste

Y eso está bien. Es parte de trabajar con LLMs y agentes.

Pero aquí está la magia 🪄

Cuando encuentres ese detalle:

• No tienes que debuggear durante horas
• No tienes que buscar en Stack Overflow
• No tienes que leer docs antiguas

Estás a 1-2 chats de distancia de arreglarlo:

Tú: "El search bar no aparece en pokemon_list.html, pero la ruta /search existe"

Claude Code:
[Revisa template]
[Añade el input con HTMX]
[Prueba que funciona]
[Hace commit]

Tiempo: 2 minutos.

Esa es la diferencia. No es que el código sea perfecto. Es que arreglarlo es trivial cuando tienes un agente que:

• Entiende el contexto completo
• Ve exactamente qué falta
• Genera el fix correcto
• Lo valida con tests

Desarrollo tradicional: Bug → 30 min debuggeando → Stack Overflow → Probar soluciones → 1 hora perdida

Con Claude Code: Bug → Describe el problema → Fix en 2 minutos → Siguiente feature

Por eso un proyecto de 5-7 horas se hace en 54 minutos. No porque sea perfecto, sino porque iterar es instantáneo.

📚 Recursos

Código del Proyecto

• Pokédex Flask + HTMX - GitHub - Código completo con tests y Docker

Documentación Oficial

• Flask Documentation - Web framework ligero para Python
• HTMX Documentation - Interactividad HTML sin JavaScript
• PokeAPI Documentation - API REST pública de Pokémon
• Tailwind CSS Documentation - Framework CSS utility-first

Artículos Relacionados

• Post 1: Setup y Fundamentos - Instala y configura Claude Code
• Post 2: Personalización con Skills - Crea skills y slash commands

Claude Code

• Claude Code - Anthropic - Herramienta oficial de Anthropic

---

¿Tienes preguntas sobre Claude Code o quieres compartir tus proyectos? Contáctame o conectemos en LinkedIn.

---

Serie Claude Code:

• Post 1: Setup y Fundamentos
• Post 2: Personalización con Skills
• Post 3: Pokédex en 1 Hora ← Estás aquí