Saltar al contenido principal

Fase 2 — Fluidez: usando Claude Code en el día a día

Duración: 4 semanas · Dedicación: 8–10h/semana · Caminos: 🟢🔵🟣 (todos los módulos esenciales) Prerrequisito: Fase 1 completada (Claude Code instalado, CLAUDE.md configurado, prompts estructurados, primer proyecto entregado). Foco principal: Claude Code · Conceptos transferibles: marcados con 🌐.

Objetivo de la fase​

Salir de "uso Claude Code de vez en cuando" hacia "Claude Code es par fijo en mi día a día". Al final de esta fase, automatización, generación de tests, debugging, code review, documentación y navegación en codebases grandes dejan de ser tareas manuales.

Al final de esta fase puedes:

  • Refactorizar y generar código multi-archivo con Claude Code
  • Trabajar en modo spec-driven (escribir la spec, dejar a Claude implementar)
  • Practicar TDD con Claude Code de forma confiable
  • Automatizar commits, PRs y code review con Claude Code + GitHub Actions
  • Debuggear bugs reales usando workflows estructurados
  • Mantener documentación sincronizada con código
  • Navegar y contribuir en codebases grandes sin ahogarte en contexto

Convenciones​

  • Tipo: 📚 Doc oficial · 📖 Artículo/Paper · 🎓 Curso · 🎬 Video/Podcast · 🛠️ Hands-on/Repositorio
  • Idioma: [PT] portugués · [EN] inglés · [ES] español
  • Costo: [Gratis] · [Pago] · [Freemium]
  • Nivel: principiante · intermedio · avanzado
  • ⭐ esencial · 🌐 concepto universal (transferible a cualquier agente)

M5 · Automatización de tareas de desarrollo con Claude Code

Por qué este módulo​

Ya sabes usar Claude Code para tareas puntuales. Aquí consolidas los patrones de automatización que aparecen todos los días: refactoring multi-archivo, generación de boilerplate, transformaciones repetitivas, migraciones pequeñas. La ganancia es dejar de "pensar cómo pedir" y empezar a tener prompts y flujos reflejos.

Tópicos​

  • Refactoring con Claude Code: mover código entre archivos, extraer funciones, renombrar consistentemente, aplicar patrones
  • Edición multi-archivo en una sesión (Claude Code es nativamente multi-file)
  • Generación de boilerplate: rutas de API, componentes, schemas, migrations
  • Transformaciones repetitivas: aplicar el mismo cambio en N lugares
  • Patrones de prompt para tareas recurrentes (templates personales)
  • Cuándo usar modo plan (Shift+Tab) vs. modo directo
  • Cuándo activar thinking modes (think, think hard, ultrathink)
  • Cuándo NO usar Claude Code (tareas triviales, tareas donde ya eres fluido)

Materiales​

Documentación oficial ⭐​

Cursos y guías​

En portugués​

Ejercicio práctico​

En un proyecto real tuyo, haz 5 tareas con Claude Code:

  1. Refactorizar una función grande en 3 funciones más pequeñas
  2. Renombrar consistentemente una variable/concepto en 5+ archivos
  3. Agregar tipado (TypeScript / Python type hints) a un módulo sin tipos
  4. Generar boilerplate para una nueva ruta de API + test correspondiente
  5. Aplicar la misma transformación (ej: cambiar console.log por logger estructurado) en N archivos

Documenta en mi-playbook-claude.md el template de prompt que funcionó para cada tipo de tarea. Este archivo va a convertirse en tu referencia para siempre.

Definition of Done​

  • Tienes 3+ templates de prompt personales para tareas recurrentes
  • Sabes cuándo usar modo plan y cuándo ir directo
  • Sabes activar thinking mode cuando el problema lo exige
  • Identificas en segundos cuándo NO usar Claude Code

M6 · Spec-driven development con Claude

Por qué este módulo​

🌐 Spec-driven development se convirtió en estándar emergente en 2025/26 — escribir la especificación primero y dejar al agente implementar. En vez de prompts sueltos, escribes un documento que explica intención, restricciones y criterios de aceptación. Resultado: menos iteración, menos retrabajo, calidad mucho más alta.

Anthropic documenta el patrón como Explore → Plan → Code → Commit. GitHub creó Spec Kit, toolkit open source para este flujo. Varias organizaciones reportaron cambio de throughput al adoptar.

Tópicos​

Universales 🌐​

  • Qué es spec-driven development y por qué funciona
  • Estructura de una buena spec: contexto, objetivos, requisitos, restricciones, criterios de aceptación, edge cases
  • Flujo Explore → Plan → Code → Commit
  • Spec vs. PRD vs. design doc — cuándo usar cada formato

Específico Claude Code​

  • Modo plan (Shift+Tab) como herramienta primaria para spec interactiva
  • CLAUDE.md como spec persistente del proyecto entero
  • .claude/rules/ para reglas escopadas
  • Subagentes recibiendo specs como input

Herramientas​

  • GitHub Spec Kit — toolkit oficial, soporta Claude Code (constitution → specify → plan → tasks → implement)
  • claude-code-spec-workflow (Pimzino) — workflows automatizados para spec-driven dev y bug fix
  • cc-sdd (gotalab) — minimal spec-driven harness con Skills

Materiales​

Conceptual ⭐​

Herramientas (hands-on) ⭐​

  • ⭐ 🛠️ GitHub Spec Kit · [EN] [Gratis] Toolkit oficial open source. Soporta Claude Code, Copilot, Gemini CLI. Usa durante el ejercicio.

  • 🛠️ claude-code-spec-workflow (Pimzino) · [EN] [Gratis] Workflow automatizado para Claude Code: Requirements → Design → Tasks → Implementation, más un workflow de bug fix.

  • 🛠️ cc-sdd (gotalab) · [EN] [Gratis] Más minimalista, foca en autonomía de larga ejecución con Skills. Compatible con varios agentes.

Tutorial guiado​

Documentación Anthropic​

Ejercicio práctico​

Elige una feature pequeña de un proyecto tuyo (o inicia un proyecto nuevo) y construye vía spec-driven:

  1. Instala GitHub Spec Kit (uv tool install spec-kit-cli o equivalente)
  2. Inicializa el flujo: constitution → specify → plan → tasks → implement
  3. Usa Claude Code como agente en todas las etapas
  4. Compara el resultado con lo que harías con prompts sueltos
  5. Documenta en learnings-spec-driven.md:
    • Cuánto tomó cada etapa
    • Cuánto retrabajo hubo vs. tu flujo anterior
    • Dónde la spec fue insuficiente y tuviste que iterar

Definition of Done​

  • Completaste al menos 1 feature vía spec-driven completo
  • Tienes opinión informada sobre cuándo spec-driven vale el overhead vs. cuándo es exagerado
  • Sabes usar CLAUDE.md como capa de spec persistente
  • Conoces al menos 1 herramienta de spec workflow (Spec Kit, Pimzino, o cc-sdd)

M7 · Test-Driven Development con Claude Code

Por qué este módulo​

🌐 TDD con IA es particularmente poderoso porque el agente performa mucho mejor cuando tiene un objetivo verificable (tests que necesitan pasar). Es la versión moderna y justificada del TDD — el agente itera hasta verde, sin terquedad.

La trinidad Red → Green → Refactor gana un cuarto paso: Validate (revisas que el agente no hizo trampa, no escribió tests para el código que ya escribió, no ignoró edge cases).

Tópicos​

Universales 🌐​

  • Red → Green → Refactor → Validate
  • Por qué TDD con agente es diferente del TDD humano
  • Cómo evitar anti-patrones: agente escribiendo tests vacíos, mockeando demasiado, atajos
  • Cómo dar objetivos verificables al agente (asserts específicos, edge cases explícitos)

Específico Claude Code​

  • Patrón Write tests, commit; code, iterate, commit (Anthropic best practices)
  • Usar plan mode para escribir la spec de los tests primero
  • Subagente "verificador" que revisa si el agente no hizo trampa
  • Skill de TDD customizada (existen varias en la comunidad)

Materiales​

Conceptual ⭐​

Cursos pagos​

Skills y herramientas comunitarias 🛠️​

Artículos prácticos​

Ejercicio práctico​

Elige una feature nueva que vas a necesitar implementar (algo real, ~2–4h de trabajo normal).

  1. Crea un branch
  2. Inicia sesión Claude Code
  3. Usa el prompt: "Vamos a hacer TDD. Para la feature X, escribe los tests primero cubriendo casos felices, casos de error y edge cases. No implementes el código todavía. Confirma que los tests fallan."
  4. Revisa los tests manualmente — ¿reflejan el comportamiento que quieres?
  5. Pide implementación: "Ahora implementa el código mínimo para hacer pasar todos los tests. No modifiques los tests."
  6. Verifica que pasó
  7. Refactor: "Refactoriza para legibilidad sin alterar comportamiento. Confirma que los tests siguen pasando."
  8. Validate manual: corre los tests, lee la implementación, asegura que no hay mock indebido

Documenta en learnings-tdd.md: qué funcionó, dónde Claude intentó hacer trampa, qué prompts impidieron trampa.

Definition of Done​

  • Hiciste al menos 1 feature entera vía TDD con Claude Code
  • Identificas en 30 segundos si Claude está "haciendo trampa" (escribiendo tests para lo que ya escribió)
  • Tienes 1 prompt template para TDD listo en tu playbook
  • Conoces al menos 1 Skill o slash command de TDD (instalado o referenciado)

M8 · Git, PR y code review con Claude Code

Por qué este módulo​

Git, PRs y code review consumen mucho tiempo cognitivo de los devs. Claude Code automatiza estos tres puntos con calidad alta — desde mensajes de commit semánticos hasta PR review estructurado en GitHub Actions.

Anthropic mantiene un plugin oficial de Code Review con pipeline de 4 fases (calificación → resumen → revisión paralela por 5 agentes especializados → verificación final). Está en research preview en planes Team/Enterprise.

Tópicos​

Workflow Git diario con Claude Code​

  • Generación de mensajes de commit semánticos
  • Generación de descripciones de PR (título + cuerpo + checklist)
  • Resolución de merge conflicts con Claude Code
  • Atribución "Co-authored-by: Claude" (convención, no obligatorio)

Code review​

  • Comando /review integrado
  • Plugin oficial Code Review de Anthropic (5 agentes especializados)
  • Comentar @claude review en PRs de GitHub para review on-demand
  • Comparativo: lo que Claude pesca bien vs. lo que pierde

Automatización con GitHub Actions​

  • anthropics/claude-code-action — Action oficial
  • Trigger en open/update de PR
  • Postear review como comentarios inline
  • Configurar vía CLAUDE.md y workflow YAML
  • Costo y seguridad (secrets, allowlists)

Materiales​

Documentación oficial ⭐​

Guías prácticas ⭐​

Reviews honestos​

Git workflow​

Skills comunitarias​

Ejercicio práctico​

  1. Configura un template de commit message en el CLAUDE.md de tu proyecto (Conventional Commits, por ejemplo)
  2. Usa Claude Code para crear 5 commits en un branch real siguiendo el template
  3. Crea un PR con descripción generada por Claude Code (título, cuerpo, checklist)
  4. Configura claude-code-action en el repositorio (usa la Action oficial de Anthropic)
  5. Abre un nuevo PR y observa el review automático corriendo
  6. Critica el review: ¿qué pescó Claude? ¿Qué perdió? Compara con el artículo de LogRocket
  7. Documenta en learnings-pr-review.md

Definition of Done​

  • Generas commit messages y descripciones de PR exclusivamente vía Claude Code
  • Tienes claude-code-action corriendo en al menos 1 repositorio tuyo
  • Sabes cuándo el review automático es confiable y cuándo no
  • Configuraste el trigger @claude review o similar para review on-demand

M9 · Debugging y resolución de errores con Claude Code

Por qué este módulo​

Debugging es la tarea donde Claude Code más brilla — porque combina tres cosas: lectura de muchos archivos (call stack), razonamiento multi-paso (del síntoma a la causa raíz) e iteración hasta verde (correr tests/scripts y validar fix). Estudios prácticos reportan ~95% de fix-rate en el primer intento con workflow estructurado vs. ~40% con prompts sueltos.

Tópicos​

Workflow estructurado de debugging con Claude Code​

  • Fase 1 — Investigación: capturar stack trace completa, adjuntar código relevante, pedir análisis (NO pidas fix todavía)
  • Fase 2 — Hipótesis y validación: pedir 2–3 hipótesis, validar con lectura adicional o logs
  • Fase 3 — Fix mínimo: aplicar corrección mínima y correr tests
  • Fase 4 — Regresión: pedir test de regresión automatizado para el bug específico

Principios universales 🌐​

  • Siempre rastrear hasta la causa raíz, nunca corregir solo el síntoma
  • Stack trace completa, no solo la última línea
  • Reproducir el bug primero, fixar después
  • Test de regresión antes de cerrar

Específico Claude Code​

  • think hard o ultrathink para bugs realmente difíciles
  • Subagente especializado en debugging (definición en .claude/agents/)
  • Hooks PostToolUse para correr tests automáticamente después de edición

Materiales​

Documentación y blog oficiales ⭐​

Guías prácticas ⭐​

Skills y patterns comunitarias​

Ejercicio práctico​

Toma 2 bugs reales (de tu trabajo o del backlog de tu proyecto personal):

Bug A — medio: stack trace clara, hipótesis rápida.

  1. Pega stack trace completa en Claude Code
  2. Pide análisis sin fix
  3. Valida hipótesis
  4. Aplica fix y corre tests
  5. Crea test de regresión

Bug B — difícil: intermitente, multi-archivo, o de comportamiento.

  1. Usa ultrathink o think hard
  2. Usa modo plan para planear la investigación primero
  3. Considera subagente "investigador" (defines en .claude/agents/)
  4. Documenta el camino hasta la causa raíz

Anota en learnings-debugging.md:

  • Tiempo para cada bug con Claude Code
  • Tiempo estimado si lo hicieras solo
  • Donde Claude fue esencial vs. donde estorbó

Definition of Done​

  • Usas Claude Code como herramienta de debug primaria para bugs no triviales
  • Tienes 1 prompt template de debug en tu playbook
  • Creas test de regresión para todo bug no trivial que fixas
  • Sabes cuándo activar ultrathink

M10 · Documentación técnica automatizada

Por qué este módulo​

Documentación es el lugar más obvio donde IA agrega valor — y aún así la mayoría de los equipos generan documentación mala porque la tratan como "tarea de una sola vez". Claude Code permite mantener documentación sincronizada con código vía hooks, slash commands y workflows recurrentes.

Tópicos​

Tipos de documentación automatizable​

  • Inline: JSDoc, docstrings (Python), TSDoc (TypeScript)
  • README: estructura, badges, ejemplos, troubleshooting
  • API docs: OpenAPI/Swagger generados de tipos/schemas
  • Diagramas: Mermaid y PlantUML generados a partir de código (sequence, ER, architecture)
  • Changelogs: generados a partir de commits y PRs
  • ADRs (Architecture Decision Records) asistidos por Claude

Mantener documentación sincronizada​

  • Slash command /update-docs customizado
  • Hook PostToolUse que pide sync de docs después de cambio grande
  • Subagente "documentation reviewer" que corre en PRs

Materiales​

Documentación oficial ⭐​

Guías y ejemplos​

Hands-on​

  • 🛠️ Toma cualquier proyecto tuyo sin README y haz que Claude genere un README completo a partir del código
  • 🛠️ Toma cualquier función sin docstring y pide documentación inline con ejemplos

Ejercicio práctico​

  1. En un proyecto tuyo sin README decente, pídele a Claude un README completo (estructura: Qué es, instalación, uso, arquitectura, contributing, license)
  2. Agrega diagrama Mermaid de arquitectura al README, generado por Claude a partir del código
  3. Crea un slash command customizado /update-docs en .claude/commands/update-docs.md que estandariza la tarea
  4. Crea un changelog generado a partir de commits con Claude
  5. Agrega docstrings ricas en al menos 1 módulo crítico

Definition of Done​

  • Tiene README de calidad generado en al menos 1 proyecto tuyo
  • Al menos 1 diagrama Mermaid en un README
  • Tiene slash command /update-docs o equivalente en tu setup
  • Sabe generar changelog desde cero en segundos

M11 · Codebases grandes con Claude Code

Por qué este módulo​

En proyectos pequeños, Claude Code "simplemente funciona". En monorepos y codebases grandes, sin estrategia, se ahoga: lee demasiados archivos, pierde contexto, repite trabajo, ignora convenciones escopadas.

La solución tiene 3 pilares: CLAUDE.md jerárquico, subagentes para exploración, y orchestrator pattern con paralelización. Equipos reportan ~4x reducción en overhead de contexto con escope correcto.

Tópicos​

Jerarquía de CLAUDE.md​

  • ~/.claude/CLAUDE.md — preferencias globales del dev
  • <proyecto>/CLAUDE.md — convenciones del proyecto
  • <proyecto>/<modulo>/CLAUDE.md — escopadas por área (frontend, backend, infra)
  • .claude/rules/ para reglas aún más granulares

Subagentes para exploración​

  • "Code search agent" — exploración en context window separada
  • "Architecture agent" — entiende estructura sin polucionar contexto principal
  • Subagentes reportan resúmenes, no dump de archivos

Orchestrator pattern (4 fases)​

  1. Clarify — agente principal entiende el pedido
  2. Plan — genera plan con tareas independientes
  3. Dispatch — dispara subagentes en paralelo
  4. Verify — agente principal consolida y valida

Patrones en monorepo​

  • 1 subagente por módulo (auth, db, api, frontend)
  • Skills específicas por área
  • Plugins de equipo compartidos
  • Convención compartida vía AGENTS.md (estándar emergente cross-tool)

Materiales​

Oficial Anthropic ⭐​

Casos prácticos ⭐​

Ejercicio práctico​

Usa un repositorio grande (tu monorepo de trabajo, o clona un open source grande tipo vercel/next.js, microsoft/vscode, kubernetes/kubernetes):

  1. Mapea la estructura: crea CLAUDE.md en la raíz con mapa del repo, módulos, convenciones globales
  2. Escope: crea CLAUDE.md en al menos 2 subcarpetas (módulos diferentes)
  3. Crea 2 subagentes especializados en .claude/agents/:
    • Un "explorer" que mapea código sin editar
    • Un "module-X-expert" para un módulo específico
  4. Haz una tarea real que toque 2+ módulos y usa el orchestrator pattern (Claude principal delega a subagentes)
  5. Compara: ¿cuántas veces Claude necesitó re-leer el mismo archivo? ¿Cuánto contexto se ahorró?
  6. Documenta en learnings-large-codebase.md

Definition of Done​

  • Tienes CLAUDE.md jerárquico en al menos 1 codebase grande tuya
  • Definiste al menos 2 subagentes en .claude/agents/
  • Ejecutaste al menos 1 tarea multi-módulo con orchestrator pattern
  • Sabes cuándo subagente vale el overhead vs. cuándo es exagerado

Capstone de la Fase 2 (entregable integrador)

Aplica los 7 módulos en un proyecto real tuyo (tu producto, side project, o contribución a open source). No necesita ser una feature gigante — elige algo de ~10–15h de trabajo real.

Requisitos​

  • Feature implementada vía spec-driven (M6)
  • Implementación siguió TDD (M7)
  • Al menos 5 commits con mensajes generados vía Claude Code (M8)
  • PR con descripción automática (M8)
  • claude-code-action activo en el repositorio (M8)
  • Al menos 1 bug real debuggeado con workflow estructurado documentado en learnings-debugging.md (M9)
  • README y diagrama Mermaid actualizados vía Claude Code (M10)
  • Si es monorepo/codebase grande: CLAUDE.md jerárquico + 1 subagente customizado (M11)
  • Archivo final LEARNINGS-FASE-2.md consolidando

Auto-evaluación al final de la Fase 2

  • Tengo 3+ templates de prompt personales para tareas recurrentes
  • Ya hice feature entera vía spec-driven con Spec Kit o equivalente
  • Ya hice feature entera vía TDD con Claude Code
  • Tengo claude-code-action corriendo en al menos 1 repo
  • Uso Claude Code como herramienta primaria de debug
  • Sé generar README + diagrama Mermaid en minutos
  • Tengo CLAUDE.md jerárquico en codebase grande (si aplicable)
  • Definí al menos 1 subagente en .claude/agents/
  • Sé cuándo subagente vale el overhead

Si marcaste 7+ items, estás listo para la Fase 3.

Próxima fase​

Fase 3 — Avanzado: extendiendo el agente (4 semanas) cubre los módulos M12 a M18: headless y CI/CD, MCP (Model Context Protocol), subagentes en profundidad, hooks y slash commands customizados, Skills y plugins, control de contexto avanzado, y seguridad/prompt injection.