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:

• Project Setup and Dependencies
• Flask Application Structure
• PokeAPI Service Layer
• Data Transformation Layer
• Base Templates and Static Files
• Main Routes - Index and List
• Pokemon Detail View
• Search Functionality with HTMX
• Error Handling and 404 Page
• Docker Configuration
• Documentation and README
• 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:

• Red: Escribir tests primero
• Green: Implementar código para pasar tests
• Refactor: Mejorar código
• 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)

• Conectar GitHub repo
• Configurar:
  • Build: pip install -r requirements.txt
  • Start: python run.py
• 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á:

• Caching con Redis

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

• Database local

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

• Features adicionales

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

• 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:

• ✅ El código estaba 95% completo
• ✅ La arquitectura era correcta
• ✅ Los tests unitarios pasaban
• ❌ 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í