Claude Code · IA Generativa

Desarrollo con
IA Generativa

Protocolo de trabajo colaborativo con Claude Code
para migración de aplicaciones legadas

📄 CLAUDE.md 🧠 Memoria estructurada ⚡ Comandos personalizados 🔄 Flujo iterativo 🛑 Gates de calidad

Manuel Torres · Universidad de Almería · IA aplicada a productividad IT hospitalaria

El punto de partida

El reto: migrar una aplicación legada

⚠️ Sistema actual

  • Microsoft Access 2007 + VBA
  • Reglas de validación CMBD hospitalarias
  • Ficheros de texto delimitados por |
  • Lógica de negocio embebida en macros
  • Sin API, sin tests, sin CI/CD

✅ Arquitectura objetivo

  • Backend REST API con FastAPI
  • Base de datos MySQL
  • Frontend React
  • Contenedores con Docker Compose
  • Desarrollo asistido por Claude Code
💡 El objetivo no es mantener la aplicación Access. El objetivo es ingeniería inversa + migración a una plataforma web moderna.
Paradigma de colaboración

Claude no es solo un generador de código

🏛️

Arquitecto

Diseña la arquitectura, evalúa riesgos, propone patrones y toma decisiones técnicas fundadas.

👨‍💻

Desarrollador Senior

Implementa con calidad, revisa su propio trabajo, identifica deuda técnica y aprende de errores.

📚

Documentalista

Genera y mantiene documentación estructurada, registra decisiones y lecciones aprendidas.

Interactuar con una IA va más allá de crear prompts iniciales. Es necesario establecer un protocolo de trabajo que permita mantener contexto, seguir instrucciones y mejorar continuamente.
Paso 1 · Inicialización

Configuración de CLAUDE.md

El archivo CLAUDE.md es el contexto persistente del repositorio. Claude Code lo lee en cada sesión. Se genera con /init.

  • Descripción del proyecto y arquitectura actual
  • Objetivos de migración
  • Prioridades de trabajo de Claude
  • Protocolo de inicio de sesión
  • Reglas de estilo y convenciones
⚙️ En proyectos existentes: /init genera el CLAUDE.md inicial analizando el código fuente automáticamente.
📄 CLAUDE.md — sección Project Goal
## Project Goal The goal is NOT to maintain Access. The goal is to reverse engineer the Access database and VBA logic and migrate to a modern web platform.
Migration strategy:
1. Discover Access structures.
2. Document business rules.
3. Extract validation logic.
4. Design REST APIs.
5. Build equivalent backend services.
6. Build web frontend.
7. Decommission Access.
Claude must always prioritize:
- Documentation first - Architecture before coding - Incremental delivery - Testability
CLAUDE.md · Protocolo

Working Protocol en CLAUDE.md

Se añade al final de CLAUDE.md. Claude lo sigue al iniciar cada nueva sesión. Garantiza que siempre trabaja con contexto actualizado.

  • Lee los documentos clave antes de empezar
  • Produce un resumen del estado actual
  • Espera aprobación explícita antes de actuar
  • No genera código sin validación previa

¿Por qué es importante?

Convierte cada nueva sesión en un check-in estructurado. Claude no empieza desde cero — empieza desde el estado real del proyecto.

📄 CLAUDE.md — Working Protocol
## Working Protocol At the start of every new task session: 1. Read * docs/decisions.md * docs/lessons-learned.md * docs/architecture-v1.md * docs/roadmap.md 2. Produce a concise summary: * architecture blocks * key decisions * assumptions * risks & open questions 3. Wait for explicit user approval before starting any implementation. 4. Do not generate code or documents until context summary is validated.
Paso 2 · Memoria

Memoria estructurada del proyecto

Claude funciona mejor con documentación estructurada que persiste entre sesiones. Se organiza en /docs.

/docs/ ├── project-context.md # Contexto general ├── architecture-v1.md # Arquitectura provisional ├── business-rules.md # Reglas de negocio ├── database-analysis.md # Análisis BD Access ├── decisions.md # Decisiones tomadas ├── lessons-learned.md # Lecciones aprendidas ├── migration-readiness.md# Evaluación riesgos ├── roadmap.md # Plan de migración ├── mvp-backlog.md # Backlog del MVP └── stories/ # Un dir por US
# Crear estructura de una vez mkdir -p docs && touch docs/{project-context, architecture,business-rules, database-analysis,decisions}.md

⚖️ decisions.md

Registro cronológico de decisiones arquitectónicas con fecha, razón y estado. Se actualiza continuamente a lo largo del proyecto.

🎓 lessons-learned.md

Errores cometidos, correcciones aplicadas y patrones detectados para no repetirlos en futuras historias.

🗺️ roadmap.md

Plan de migración por fases con entregables, riesgos, dependencias y estimación en puntos de historia.

💡 Estos archivos son la fuente de verdad del proyecto. Claude los lee, no los «recuerda».
Paso 3 · Descubrimiento

Análisis del sistema existente

Primera tarea real: descubrir y documentar la base de datos Access y las reglas de negocio VBA. Todo queda en /docs.

💬 Prompt de descubrimiento
Analyze the Access application and create: 1. System overview 2. Table inventory 3. Query inventory 4. VBA inventory 5. Forms inventory 6. Reports inventory 7. Business rules inventory Store everything under docs/

Clasificación de errores CMBD

Código Severidad Efecto
E- Eliminatorio Registro rechazado
X- Error Campo inválido, retenido
W- Aviso Posible problema calidad

Ficheros de salida

  • (VALIDOS).log — registros correctos
  • (DETALLES).log — errores por registro
  • (RESUMEN).LOG — estadísticas
  • (RECHAZADOS).LOG — eliminados
Paso 4 · Automatización

Comandos personalizados

Los slash commands codifican el protocolo de trabajo. Se crean como archivos .md en .claude/commands/ y se invocan con /nombre.

🔁

/retrospective

  • Revisa trabajo reciente
  • Identifica errores cometidos
  • Actualiza MEMORY.md
  • Propone mejoras a CLAUDE.md

Usar al finalizar tarea completa, antes de commit, tras varias correcciones.

📍

/checkpoint

  • Resume el progreso actual
  • Lista hallazgos recientes
  • Identifica tareas pendientes
  • No modifica decisiones permanentes

Usar con frecuencia durante el desarrollo incremental.

🔄

/run-story

  • Orquesta el flujo completo
  • Ejecuta las 5 fases en secuencia
  • Hace pausa en cada Gate
  • Guarda informes de cada fase

Usar para cada historia de usuario del sprint.

.claude/commands/ retrospective.md checkpoint.md run-story.md analyze-story.md review-design.md implement-story.md validate-story.md reconstruct-story.md
Paso 5 · Arquitectura

Diseño de la nueva arquitectura

Antes de diseñar, se abre un nuevo hilo. Claude lee /docs y produce un resumen para validar que ha entendido correctamente el contexto.

💬 Inicio de sesión de arquitectura
Read and analyze all documentation under /docs. Create a concise summary: 1. Purpose of the Access application 2. Main business processes 3. Key validation rules 4. Main entities 5. Main risks for migration 6. Unknown areas Do not design architecture yet. Wait for approval.
💡 El resumen previo detecta malentendidos antes de que afecten al diseño.

📊 Migration Readiness Assessment

Si hay riesgos significativos, se genera un informe clasificando cada riesgo: Blocker / Critical / High / Medium / Low con impacto, probabilidad y acciones.

🏗️ architecture-v1.md

  • Diagrama de contexto
  • Módulos principales y límites de servicio
  • Estrategia de autenticación
  • Arquitectura de despliegue
  • Supuestos explícitos con impacto si fallan

Enfoque ágil (provisional)

Se puede diseñar una arquitectura provisional que avance la migración mientras se resuelven las incógnitas restantes.

Paso 6 · Plan

Roadmap y backlog del MVP

Nueva sesión. Claude vuelve a leer /docs y produce resumen antes de generar el roadmap.

💬 Prompt de roadmap
Create a migration roadmap. Phase 1: Discovery Phase 2: Documentation Phase 3: Database design Phase 4: API design Phase 5: Backend implementation Phase 6: Frontend implementation Phase 7: Testing Phase 8: Deployment For each phase: - Deliverables - Risks - Dependencies - Story points Store in: docs/roadmap.md

Sprint 1 — Foundation (25 SP)

Story SP Entregable
US-001 5 Docker Compose stack
US-002 2 Alembic migrations
US-004 5 Core tables DDL
US-005 3 Reference tables + seed
US-006 3 Error catalog seed
US-008 2 Extract import spec
⚡ Nunca «implementa la fase 3». Siempre una historia de usuario a la vez mediante el flujo iterativo.
Flujo de trabajo

El pipeline por historia de usuario

Cada historia de usuario pasa por 5 fases antes de considerarse completada. Cada fase tiene su comando y genera un informe persistente.

Fase 1 /analyze-story Análisis
🛑Gate
Fase 2 /review-design Revisión
🛑Gate
Fase 3 /implement-story Implementación
🛑Gate
Fase 4 /validate-story Validación
🛑Gate
Fase 5 /retrospective Retrospectiva
⚡ /run-story US-XXX orquesta automáticamente las 5 fases, haciendo pausa en cada Gate para esperar aprobación explícita del equipo.
Fase 1

/analyze-story

⚙️ .claude/commands/analyze-story.md
Analyze user story: $ARGUMENTS Read: * docs/architecture-v1.md * docs/decisions.md * docs/mvp-backlog.md Focus only on: $ARGUMENTS Analyze: 1. Goal of the user story 2. Acceptance criteria 3. Technical approach 4. Required files and folders 5. Dependencies 6. Risks 7. Open questions ## Output files docs/stories/$ARGUMENTS/analysis.md docs/stories/$ARGUMENTS/design.md Do not generate code yet. Wait for explicit user approval.

📝 analysis.md

  • Objetivo de la historia
  • Criterios de aceptación
  • Dependencias
  • Riesgos identificados
  • Definición de Done

🏗️ design.md

  • Enfoque de implementación propuesto
  • Componentes involucrados
  • Ficheros a crear o modificar
  • Trade-offs y alternativas descartadas
🛑 Al final: Gate. El equipo revisa el análisis antes de continuar.
Fase 2

/review-design

⚙️ .claude/commands/review-design.md
Review implementation approach for: $ARGUMENTS Act as a senior architect. Read docs/stories/$ARGUMENTS/design.md Verify: * Acceptance criteria coverage * Simplicity — simpler path? * Maintainability — easy in 6 months? * Security — secrets, unvalidated inputs? * Docker best practices * Development experience Identify: * Overengineering * Missing components * Unnecessary complexity * Delivery risks ## Output file docs/stories/$ARGUMENTS/design-review.md Do not redesign. Only review. Wait for explicit user approval.

🔍 design-review.md

# Problemas detectados 1. <issue encontrado> # Recomendaciones 1. <recomendación concreta> # Aprobación [ ] Approved [ ] Approved with conditions [ ] Rejected
🏛️ Claude actúa como arquitecto senior que revisa el trabajo de otro desarrollador — de forma objetiva e imparcial.
Fase 3

/implement-story

⚙️ .claude/commands/implement-story.md
Implement user story: $ARGUMENTS Read: * docs/stories/$ARGUMENTS/analysis.md * docs/stories/$ARGUMENTS/design.md * docs/stories/$ARGUMENTS/design-review.md Requirements: * Satisfy all acceptance criteria. * Follow the approved approach exactly. * Apply conditions from design review. * Create only files for this story. * Do NOT implement future stories. * Keep the solution simple. ## Output file docs/stories/$ARGUMENTS/implementation.md Provide manual verification steps in the chat for the team to test.

⚡ implementation.md

# Ficheros creados | Path | Purpose | | backend/main.py | FastAPI entry | # Ficheros modificados | Path | Summary | | docker-compose.yml | Added svc | # Cambios realizados <narrativa de lo construido>
💡 Los pasos de verificación manual se entregan en el chat para que el equipo compruebe antes de continuar al Gate.
Fase 4

/validate-story

⚙️ .claude/commands/validate-story.md
Validate user story: $ARGUMENTS Read docs/stories/$ARGUMENTS/analysis.md to extract acceptance criteria. Start the application: docker compose up -d For each criterion, verify by: * calling the relevant API endpoint * observing UI behavior * inspecting database state Check for regressions in prior stories. ## Output file docs/stories/$ARGUMENTS/validation.md Do not fix issues inline. Validation and implementation are separate.

✅ validation.md

# Acceptance Criteria | # | Criterion | Result | |---|-----------|--------| | 1 | /health → 200 | PASS | | 2 | DB auto-migrate | PASS | | 3 | Port 3306 exposed | PASS | # Regressions None detected. # Verdict DONE — all criteria pass
🎯 Si algún criterio falla, se lista el fallo con detalle suficiente para abrir una tarea de fix. No se repara en la misma sesión.
Fase 5

/retrospective

⚙️ .claude/commands/retrospective.md
Perform a project retrospective. Review: * recent work * errors encountered * user corrections * failed assumptions * architectural deviations Update: * MEMORY.md * docs/decisions.md * docs/lessons-learned.md If needed: * propose new project rules * propose CLAUDE.md improvements ## Story artifact (si $ARGUMENTS) docs/stories/$ARGUMENTS/retrospective.md # Lecciones aprendidas # Problemas encontrados # Actualizaciones de memoria

🧠 Ciclo de aprendizaje

Cada retrospectiva alimenta lessons-learned.md y decisions.md. Con el tiempo, Claude comete menos errores recurrentes en ese proyecto.

¿Cuándo usar /retrospective?

  • Al finalizar una historia completa
  • Al terminar un sprint
  • Antes de hacer un commit importante
  • Cuando Claude se haya corregido varias veces
🔄 A diferencia de /checkpoint, la retrospectiva actualiza documentos permanentes.
Orquestador

El comando /run-story

⚙️ .claude/commands/run-story.md
Orchestrate the complete story workflow for: $ARGUMENTS Treat every $ARGUMENTS in subcommands as: $ARGUMENTS ## Phase 1 — Analysis Read .claude/commands/analyze-story.md Execute for story $ARGUMENTS. Save: analysis.md, design.md GATE — Wait for explicit approval. ## Phase 2 — Design Review Read .claude/commands/review-design.md Save: design-review.md GATE — Wait for explicit approval. ## Phase 3 — Implementation Read .claude/commands/implement-story.md Save: implementation.md GATE — Wait for explicit approval. ## Phase 4 — Validation Read .claude/commands/validate-story.md Save: validation.md GATE — Wait for explicit approval. ## Phase 5 — Retrospective Read .claude/commands/retrospective.md Save: retrospective.md

Una fuente de verdad

El orquestador lee los subcomandos; no duplica lógica. Cambiar un subcomando actualiza automáticamente el flujo completo.

Uso

# Flujo completo: /run-story US-001 # Solo análisis: /analyze-story US-002 # Solo revisión: /review-design US-002 # Solo implementación: /implement-story US-002
⚡ Los subcomandos son reutilizables independientemente para máxima flexibilidad.
Memoria del proyecto

Almacenamiento de informes por historia

Cada historia genera 6 artefactos estructurados que forman la memoria permanente del proyecto.

docs/stories/ ├── US-001/ │ ├── analysis.md # Objetivo + AC + Deps │ ├── design.md # Enfoque + Trade-offs │ ├── design-review.md # Issues + Aprobación │ ├── implementation.md # Ficheros + Cambios │ ├── validation.md # PASS/FAIL/DONE │ └── retrospective.md # Lecciones ├── US-002/ │ └── ... └── US-003/ └── ...

¿Para qué sirve?

  • Consultar decisiones pasadas sin leer el chat
  • Identificar riesgos recurrentes entre historias
  • Onboarding de nuevos miembros del equipo
  • Auditoría y trazabilidad completa del proyecto
  • Alimentar retrospectivas de sprint

🔄 /reconstruct-story

Para historias ya implementadas sin documentación estructurada, este comando reconstruye los 6 artefactos a partir de git log, commits y docs existentes.

/reconstruct-story US-001
Recuperación de memoria

/reconstruct-story

⚙️ .claude/commands/reconstruct-story.md (resumen)
Reconstruct documentation for a completed story: $ARGUMENTS ## Step 1 — Gather evidence Read for mentions of $ARGUMENTS: * docs/mvp-backlog.md * docs/sprint-tracker.md * docs/decisions.md * docs/lessons-learned.md Then run: git log --oneline --all -- . Filter commits mentioning $ARGUMENTS. For each relevant commit: git show <hash> --stat ## Step 2 — Reconstruct 6 artifacts Write under docs/stories/$ARGUMENTS/ For unknown fields → [TO VERIFY] ## Step 3 — Summary report List sources used, fields [TO VERIFY], and recommended next action: /validate-story $ARGUMENTS

Fuentes de datos usadas

  • Documentos existentes en /docs
  • Historia original en mvp-backlog.md
  • Git log y diffs de commits relacionados
  • Decisiones y lecciones registradas

Output del reporte

  • Fuentes consultadas ✓/✗
  • Campos que necesitan verificación manual
  • Acción recomendada: /validate-story
💡 Útil cuando el proceso de documentación se introduce a mitad del proyecto.
Vista global

El protocolo completo de trabajo

Inicialización
/init → CLAUDE.md
↓
Project Goal
↓
Working Protocol
↓
/docs estructura
Descubrimiento
Nueva sesión
↓
Análisis Access
↓
business-rules.md
↓
/retrospective
Diseño
Nueva sesión
↓
architecture-v1.md
↓
roadmap.md
↓
mvp-backlog.md
Desarrollo
/run-story US-XXX
↓
5 fases + Gates
↓
stories/US-XXX/
↓
/retrospective
📄 CLAUDE.md 🗂️ /docs ⚙️ /commands 📁 stories/US-XXX 🛑 Gates de aprobación
Gestión de sesiones

Nuevos hilos de conversación

Claude no retiene memoria entre sesiones. El protocolo garantiza que cada nueva sesión arranca con contexto completo.

💬 Patrón de inicio de sesión
This is a new session. 1. Read the /docs folder 2. Analyze the documentation 3. Produce a concise summary: - Main architecture blocks - Key architectural decisions - Assumptions made - Main migration risks - Open questions unresolved 4. Highlight assumptions that could significantly impact the roadmap. Do not generate anything yet. Wait for approval before proceeding.

¿Cuándo abrir nueva sesión?

  • Al cambiar de fase del proyecto
  • Al iniciar una nueva historia de usuario
  • Cuando el contexto de la sesión crece demasiado
  • Al retomar trabajo días después
💡 El resumen previo tiene doble función: detectar malentendidos Y darle a Claude un contexto comprimido y estructurado para la tarea siguiente.

Ventajas

  • Contexto limpio y enfocado
  • Sin interferencias de tareas anteriores
  • El Working Protocol garantiza continuidad
MVP

De roadmap a backlog ejecutable

El backlog se genera antes de codificar. No se implementa una fase entera: se trabaja historia por historia.

Ejemplo — Sprint 1 (25 SP)

Story SP Orden
US-008 2 Día 1–2 · Bloquea US-011
US-001 5 Paralelo con US-008
US-002 2 Después de US-001
US-004 5 Después de US-010
US-005 3 Paralelo con US-004
US-006 3 Paralelo con US-004
⚡ Tras el Sprint 1, los tracks de Backend y Frontend pueden avanzar en paralelo.

Contenido de mvp-backlog.md

  • Epics del MVP
  • Features por epic
  • User Stories con ID, descripción, AC, deps, prioridad y SP
  • Línea de corte del MVP
  • Primer sprint definido

Scope del MVP

  • Subir ficheros CMBD
  • Almacenar cargas
  • Navegar registros y errores
  • Filtrar registros
  • Ver detalle de registro

Excluye: reporting avanzado, analytics histórico, multi-hospital.

Principios clave

Lo que hace funcionar el protocolo

📚

Documentación primero

Cada decisión, arquitectura y lección queda registrada en archivos. Claude trabaja con documentos, no con conversaciones pasadas.

🛑

Gates de aprobación

El equipo aprueba cada fase antes de continuar. Evita que Claude avance con supuestos erróneos.

🔄

Mejora continua

Cada retrospectiva actualiza lecciones aprendidas. Con el tiempo Claude comete menos errores en ese proyecto.

⚡

Comandos como protocolo

Los slash commands codifican el proceso. Garantizan que se sigue correctamente sin depender de la memoria del equipo.

📦

Historias pequeñas

Nunca «implementa la fase 3». Siempre una historia a la vez. Menor riesgo, mayor calidad, feedback más rápido.

🧵

Sesiones frescas

Nuevas fases = nuevos hilos. El Working Protocol garantiza que Claude recupera contexto sin ruido acumulado.

Conclusiones

La IA como socio técnico, no como generador de código

El valor real no está en generar código rápido. Está en mantener contexto, calidad y aprendizaje a lo largo de un proyecto complejo y de larga duración.

📄 CLAUDE.md

Contexto persistente + instrucciones + protocolo de sesión

🗂️ /docs

Memoria viva del proyecto, siempre actualizada

⚡ Comandos

Flujo codificado, reproducible, sin improvisación

📁 stories/

Trazabilidad completa de cada decisión tomada

Manuel Torres · Universidad de Almería · Curso IA Generativa · 2026