Módulo 6: Proyecto — Pipeline CI/CD Completo con Claude Code
Diseño del Pipeline End-to-End
Diseño del Pipeline End-to-End
Descripción
Esta cápsula es donde diseñas el pipeline completo antes de implementarlo. Sin diseño claro, las cápsulas 03-06 se vuelven implementación a ciegas con retrabajo costoso. Acá tomas los componentes que aprendiste en módulos 1-5 y decides cómo encajan: orden de ejecución, dependencias, gates, paralelización, costos esperados, y trade-offs.
El output de esta cápsula no es código — es un documento de diseño que describe el pipeline en términos de stages, flujos de datos, decisiones críticas y estimaciones. Es lo que te permite entrar a las cápsulas de implementación sabiendo qué construir y por qué.
Al terminar, vas a tener: arquitectura del pipeline diagramada, decisiones documentadas con razón, estimaciones de tiempo y costo por run, y plan de validación incremental.
Por Qué Diseñar Antes de Implementar
SIN DISEÑO PREVIO:
Sesión 1: Empiezas con M1 (workflow básico)
Sesión 2: Agregas M2 (code review)
Sesión 3: "Ahora deployment... pero ¿dónde encaja?"
Sesión 4: Refactor para que deployment funcione
Sesión 5: "Falta security scan... ¿lo pongo antes o después?"
Sesión 6: Otro refactor
→ Cada decisión se toma sin contexto del todo
→ Refactors costosos para reorganizar
→ Pipeline final inconsistente
CON DISEÑO PREVIO:
Sesión 0: Diseño completo en papel/markdown
Sesión 1: Implementas stage 1 sabiendo dónde encaja
Sesión 2: Implementas stage 2 sin sorpresas
Sesión N: Pipeline coherente, mínimo refactoring
→ Decisiones contextualizadas
→ Implementación lineal
→ Resultado coherente desde el inicio
Inversión de 1-2 horas en diseño ahorra 6-10 horas de retrabajo. Y produce mejor pipeline.
Las Decisiones Clave del Diseño
1. ORDEN DE STAGES
¿Qué corre primero, qué después?
Trade-off: paralelismo (rápido) vs dependencias (correcto)
2. PARALELIZACIÓN
¿Qué stages pueden correr en paralelo?
Trade-off: velocidad vs costo de runners
3. GATES (humanas y automáticas)
¿Dónde requerimos approval humano?
Trade-off: seguridad vs velocidad
4. FAILURE BEHAVIOR
¿Qué stages bloquean si fallan? ¿Cuáles solo informan?
Trade-off: estricto (bloqueante) vs permissive (informativo)
5. COSTO POR RUN
¿Cuánto cuesta cada deploy?
Trade-off: features vs presupuesto
6. TIEMPO TOTAL
¿Cuánto tarda PR-to-prod en happy path?
Trade-off: cobertura vs velocidad
7. OBSERVABILIDAD
¿Qué métricas exporta el pipeline?
Trade-off: completitud vs complejidad
Cada decisión tiene un trade-off explícito. Documentarlas evita "por qué hicimos esto" 6 meses después.
La Arquitectura Completa
┌──────────────────────────────────────────────────────────┐
│ FASE 1: PR REVIEW │
│ (paralelo, antes del merge) │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Code Review │ │ Security │ │ Tests + │ │
│ │ (Claude) │ │ Scan │ │ Linting │ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
│ │ │ │ │
│ └────────────────┴────────────────┘ │
│ │ │
│ ▼ │
│ ¿Pasaron las gates? │
│ │ │
└──────────────────────────┼────────────────────────────────┘
│
┌────────────┴────────────┐
▼ NO ▼ SÍ
Bloquea merge ┌──────────────┐
│ Merge a main │
└──────┬────────┘
│
┌─────────────────────────────────────────┼─────────────────┐
│ FASE 2: PRE-DEPLOYMENT │ │
│ ▼ │
│ ┌──────────────────┐ │
│ │ Generate │ │
│ │ Changelog │ ← M4 │
│ └──────┬───────────┘ │
│ ▼ │
│ ┌──────────────────┐ │
│ │ Readiness │ │
│ │ Validation │ ← M4 │
│ └──────┬───────────┘ │
└───────────────────────────────────────┼────────────────────┘
│
┌───────────────────────────────────────┼────────────────────┐
│ FASE 3: DEPLOYMENT ▼ │
│ ┌──────────────────┐ │
│ │ Deploy Staging │ ← M4 │
│ │ + Smoke Tests │ │
│ └──────┬───────────┘ │
│ ▼ │
│ ┌──────────────────┐ │
│ │ Validate Staging │ │
│ │ con Claude │ ← M4 │
│ └──────┬───────────┘ │
│ ▼ │
│ ╔══════════════════╗ │
│ ║ APPROVAL GATE ║ ← M4 │
│ ║ (humano) ║ │
│ ╚══════┬═══════════╝ │
│ ▼ │
│ ┌──────────────────┐ │
│ │ Deploy Producción│ │
│ │ + Smoke Tests │ ← M4 │
│ └──────┬───────────┘ │
└───────────────────────────────────────┼────────────────────┘
│
┌───────────────────────────────────────┼────────────────────┐
│ FASE 4: POST-DEPLOY ▼ │
│ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ Monitor + │ ← M5 │ Notify Team │ │
│ │ Auto-Rollback │ │ │ │
│ └──────┬───────────┘ └──────────────────┘ │
│ ▼ (si rollback) │
│ ┌──────────────────┐ │
│ │ Diagnose + │ ← M5 │
│ │ Postmortem │ │
│ └──────────────────┘ │
└─────────────────────────────────────────────────────────────┘
Características clave del diseño:
- Fase 1 es paralela (3 jobs simultáneos)
- Fase 2 es secuencial (changelog → readiness)
- Fase 3 tiene la única gate humana (entre staging y producción)
- Fase 4 monitorea continuamente, dispara rollback si necesita
Detallando Cada Stage
Fase 1: PR Review
# Conceptual — implementación en cápsula 03
stages_phase_1:
- name: code-review
runs_on: pull_request
duration: ~3 min
cost: ~$0.02
failure_behavior: warn (no bloquea)
output: PR comment con findings
- name: security-scan
runs_on: pull_request
duration: ~2 min
cost: ~$0.03
failure_behavior: block on critical (cápsula 02 M5)
output: PR comment + check status
- name: tests-and-linting
runs_on: pull_request
duration: ~5 min
cost: ~$0.04 (runner)
failure_behavior: block (siempre)
output: check status
paralelización: los 3 corren en paralelo
total_phase_1_duration: ~5 min (max de los 3)
total_phase_1_cost: ~$0.09Fase 2: Pre-Deployment
stages_phase_2:
- name: generate-changelog
trigger: push to main
duration: ~1 min
cost: ~$0.05
failure_behavior: warn (no bloquea deploy)
- name: readiness-validation
duration: ~2 min
cost: ~$0.04
failure_behavior: block (deploy no procede)
paralelización: secuencial
total_phase_2_duration: ~3 min
total_phase_2_cost: ~$0.09Fase 3: Deployment
stages_phase_3:
- name: deploy-staging
duration: ~4 min
cost: ~$0.04 (runner) + costo de infra
failure_behavior: block (no avanza a prod)
- name: smoke-tests-staging
duration: ~2 min
cost: ~$0.02
failure_behavior: block
- name: validate-staging-claude
duration: ~1 min
cost: ~$0.02
failure_behavior: warn
output: comment al PR con análisis
- name: approval-gate-production
duration: variable (humano)
cost: $0
failure_behavior: timeout después de 24h
- name: deploy-production
duration: ~4 min
cost: ~$0.04 + costo de infra
failure_behavior: trigger rollback automático
- name: smoke-tests-production
duration: ~2 min
cost: ~$0.02
paralelización: secuencial
total_phase_3_duration: ~13 min sin contar approval wait
total_phase_3_cost: ~$0.14Fase 4: Post-Deploy
stages_phase_4:
- name: monitor-post-deploy
duration: ~10 min (ventana de monitoring)
cost: ~$0.01 (mostly runner)
failure_behavior: trigger rollback if metrics degrade
- name: rollback (conditional)
triggered_by: monitor failure
duration: ~3 min
cost: ~$0.03
- name: diagnose (conditional)
triggered_by: rollback
duration: ~2 min
cost: ~$0.06 (Claude analysis)
- name: notify-team
duration: ~1 min
cost: ~$0.02
total_phase_4_duration: ~10-15 min (típico) o ~5 min en happy pathResumen Total
HAPPY PATH (sin rollback, sin investigación humana extensa):
- Phase 1: 5 min
- Phase 2: 3 min
- Phase 3: 13 min (sin approval wait)
- Approval wait: variable (típico 10-30 min)
- Phase 4 (monitoring): 10 min
TOTAL: ~30-50 min (mayoría es approval wait)
COSTO POR RUN:
- API costs: ~$0.20 por run completo
- Runner costs: ~$0.10
- TOTAL: ~$0.30 por deploy
ASUMIENDO 50 deploys/mes:
~$15/mes en CI/CD
Decisiones Críticas a Tomar Antes de Implementar
1. Modelo: Haiku, Sonnet, o Opus
DECISIÓN: ¿Qué modelo usar en cada stage?
Code review (Phase 1): Haiku → económico, suficiente para review
Security scan: Sonnet → más calidad para detectar vulns reales
Changelog generation: Sonnet → razonamiento de categorización
Readiness validation: Sonnet → análisis profundo
Validate staging: Sonnet → razonamiento sobre métricas + changelog
Diagnosis post-roll: Sonnet → root cause analysis
NUNCA Opus en CI normal — overkill y caro.
2. Trigger: PR vs Push vs Tag
PHASE 1 (review): pull_request: [opened, synchronize]
PHASE 2-3 (deploy): push: [main]
PHASE 4 (monitoring): chained from deploy
Edge case: hotfix urgente
- Permitir push a main directo (skip PR review)
- Pero mantener Phase 2-4 obligatorias
- Configurar branch protection para limitar quién puede skip PR
3. Concurrency: Cuándo Cancelar Runs
# Para PR reviews (Phase 1):
concurrency:
group: pr-${{ github.event.pull_request.number }}
cancel-in-progress: true # ← cancelar runs viejos del mismo PR
# Para deploys (Phase 2-3-4):
concurrency:
group: deploy-production
cancel-in-progress: false # ← NUNCA cancelar deploys4. Permissions Mínimas
# Phase 1 (review):
permissions:
contents: read
pull-requests: write # para postear comments
# Phase 2-3 (deploy):
permissions:
contents: write # para push de tags si aplica
deployments: write # para registrar deployments
packages: write # si publica artifacts
# Phase 4 (post-deploy):
permissions:
contents: read
issues: write # para crear postmortem issue
pull-requests: write # para commentsPrincipio: mínimas permissions necesarias. Cada stage solo con lo que requiere.
5. Secrets Management
SHARED SECRETS (todos los stages):
- ANTHROPIC_API_KEY (con límite de uso configurado)
- GITHUB_TOKEN (auto-generado)
PHASE 3 SECRETS (solo deploy):
- PROD_DATABASE_URL (en environment "production")
- PROD_API_TOKENS (en environment "production")
- STAGING_DATABASE_URL (en environment "staging")
PHASE 4 SECRETS:
- METRICS_API_TOKEN (Datadog/Prometheus)
- SLACK_WEBHOOK
- PAGERDUTY_TOKEN (opcional)
ROTACIÓN:
- ANTHROPIC_API_KEY: rotar trimestralmente
- DATABASE_URLs: rotar cuando rotas credenciales de DB
- GITHUB_TOKEN: auto-rotado por GitHub
6. Branch Protection Rules
BRANCH: main
Rules:
- Require pull request before merging
- Require approvals: 1
- Require status checks to pass:
☑ tests-and-linting (Phase 1)
☑ security-scan (Phase 1)
☑ code-review (Phase 1) — opcional
- Require branches to be up to date
- Restrict who can push: solo merge desde PR (no direct push)
BRANCH: hotfix/*
Rules:
- Allow direct push (para emergencias)
- Pero requiere PR para merge a main
Validación Incremental: Plan de Implementación
No vas a implementar todo el pipeline de una. Plan de iteraciones:
ITERACIÓN 1: Phase 1 funcional
- Code review básico (M2)
- Tests + linting
- Verificar end-to-end en un PR de prueba
- Tiempo estimado: 2 hrs
- Valor: feedback automático en PRs
ITERACIÓN 2: Phase 2 + Phase 3 (sin rollback)
- Changelog automático
- Readiness validation
- Deploy a staging automático
- Approval gate + deploy a producción
- Tiempo estimado: 3 hrs
- Valor: deploy con disciplina
ITERACIÓN 3: Phase 4 (rollback + monitoring)
- Monitor post-deploy
- Auto-rollback con triggers
- Diagnostic post-rollback
- Tiempo estimado: 3 hrs
- Valor: resiliencia
ITERACIÓN 4: Optimization + observability
- Métricas del pipeline
- Cost tracking
- Documentation completa
- Tiempo estimado: 2 hrs
- Valor: pipeline production-ready
Total: ~10 horas de trabajo enfocado distribuidas en 4 iteraciones que cada una entrega valor visible.
El Documento de Diseño
Antes de implementar, escribe un PIPELINE_DESIGN.md:
# Pipeline Design
## Goal
Pipeline CI/CD end-to-end que demuestra capacidades de Claude Code integrado.
## Architecture
[Diagrama del pipeline — usar el de arriba]
## Stages
### Phase 1: PR Review
- code-review (paralelo)
- security-scan (paralelo)
- tests-and-linting (paralelo)
### Phase 2: Pre-Deployment
- generate-changelog
- readiness-validation
### Phase 3: Deployment
- deploy-staging
- smoke-tests-staging
- validate-staging-claude
- approval-gate-production (HUMAN GATE)
- deploy-production
- smoke-tests-production
### Phase 4: Post-Deploy
- monitor-post-deploy
- rollback (conditional)
- diagnose (conditional)
- notify-team
## Decisiones Críticas
### Modelo
- Haiku para code review
- Sonnet para security/changelog/diagnosis
### Costo estimado
- Por run: ~$0.30
- Mensual (50 deploys): ~$15
### Tiempo estimado (happy path)
- Phase 1: 5 min
- Phase 2: 3 min
- Phase 3: 13 min + approval wait
- Phase 4: 10 min monitoring
### Branch Protection
- main: PR required, status checks required
- Hotfix path: documentado pero requiere comunicación al equipo
## Plan de Implementación
Iteración 1: Phase 1 (~2 hrs)
Iteración 2: Phase 2-3 (~3 hrs)
Iteración 3: Phase 4 (~3 hrs)
Iteración 4: Optimization (~2 hrs)
Total: ~10 hrs
## Risks y Mitigaciones
### Risk: Costos crecen más de lo esperado
Mitigation: spending limit en Anthropic console + GitHub Billing
### Risk: Approval gate se convierte en bottleneck
Mitigation: notification + delegation explícita en docs
### Risk: Rollback con falsos positives
Mitigation: empezar con thresholds conservadores, calibrar con datos reales
## Success Criteria
- Pipeline corre end-to-end sin manual intervention en happy path
- PR-to-staging: <15 min
- PR-to-production (incluye approval): <1 hour típico
- Rollback automático en <5 min cuando dispara
- Equipo puede operar sin documentación adicional al runbookEste documento es el primer entregable del proyecto. Sin esto, las cápsulas siguientes son ejecución sin dirección.
Trampas Comunes en el Diseño
1. Sobre-paralelizar
Síntoma: "Voy a poner todos los stages en paralelo para máxima velocidad."
Por qué falla: Stages tienen dependencias (no puedes deploy a producción sin staging exitoso). Sobre-paralelizar = pipeline incoherente.
Cómo corregir: Identificar dependencias reales antes de paralelizar. Solo paralelizar entre stages independientes.
2. Sub-paralelizar
Síntoma: "Voy a poner todo secuencial para simplicidad."
Por qué falla: Pipeline 2-3x más lento de lo necesario. Code review + security + tests pueden correr en paralelo.
Cómo corregir: Identificar stages independientes y paralelizarlos. La velocidad importa para el flow del equipo.
3. Aproval gate en lugar incorrecto
Síntoma: Aproval requerido antes de staging — el equipo se queja porque "para qué necesitan aprobar staging".
Por qué falla: Staging es ambiente de prueba. El gate humano va antes de producción.
Cómo corregir: Solo gates humanas en transiciones de alto riesgo (staging → prod, deploy de hotfix sin tests, etc.).
4. No documentar trade-offs
Síntoma: 6 meses después, alguien pregunta "¿por qué esto está secuencial?" y nadie sabe.
Por qué falla: Decisiones quedan en cabezas, no en docs.
Cómo corregir: Cada decisión no obvia → documentar en PIPELINE_DESIGN.md con razón. Especialmente trade-offs (no "porque sí").
5. Diseño perfecto vs implementación incremental
Síntoma: Pasas 2 semanas diseñando el pipeline ideal, nunca empiezas a implementar.
Por qué falla: Sin feedback de la realidad, el diseño tiene supuestos incorrectos.
Cómo corregir: Diseño "good enough" en 1-2 horas. Implementar Iteración 1. Aprender. Ajustar diseño. Iterar.
Diagnóstico
Pregunta 1: ¿Tu diseño identifica explícitamente qué stages son paralelos vs secuenciales?
Si no, vas a tomar decisiones ad-hoc en cada stage. Diagrama explícito = mejor.
Pregunta 2: ¿Documentaste el costo estimado por run y por mes?
Sin esto, te sorprende la factura. Cálculo simple resuelve el 80%.
Pregunta 3: ¿Sabes cuál es el tiempo total esperado del pipeline en happy path?
Si dijiste "no estoy seguro", la mayoría de la gente que llega al deploy no sabe cuánto esperar. Eso afecta el flow del equipo.
Pregunta 4: ¿Tu approval gate está donde tiene sentido (antes de prod) o donde "se siente seguro" (todos los stages)?
Demasiados gates = pipeline frustrante. Pocas gates en lugares específicos = balance correcto.
Pregunta 5: ¿Tienes plan de iteración o vas a implementar todo de una?
Implementar todo de una = retrabajo. Iteraciones con valor visible cada una = aprendes y ajustas.
Ejercicios
Ejercicio 1: Documento de diseño (Medio)
Escribe PIPELINE_DESIGN.md para tu proyecto siguiendo el template arriba. Específicamente:
- Diagrama de las 4 fases
- Decisiones críticas con razón
- Costos estimados
- Plan de iteración
Ejercicio 2: Identificar paralelización (Fácil)
Toma tu diagrama y marca explícitamente:
- 🟢 Stages que pueden correr en paralelo
- 🔴 Stages que requieren ejecución secuencial
- 🟡 Stages que dependen de outputs de otros
Ejercicio 3: Calcular costo y tiempo (Medio)
Para tu pipeline diseñado:
- Estimar tokens por stage que usa Claude
- Calcular costo de API por run
- Calcular costo de runner (tiempo × $0.008)
- Estimar tiempo total en happy path
- Multiplicar por deploys/mes esperados
Si la estimación es >$50/mes, identificar qué optimizar.
Resumen
- Diseño antes de implementar ahorra 6-10 hrs de retrabajo
- 4 fases del pipeline: PR Review (paralelo), Pre-Deploy, Deployment (con approval), Post-Deploy
- Solo gates humanas en transiciones críticas (no en cada stage)
- Decisiones documentadas con razón evitan "por qué hicimos esto" futuro
- Modelo apropiado por stage: Haiku para review, Sonnet para análisis profundo
- Iteración incremental > diseño perfecto + implementación monolítica
- Costos y tiempos estimados evitan sorpresas
Próxima cápsula: 03 — Implementación: Stages 1-3 (PR Review). Tomas el diseño y empiezas a implementar la Fase 1: code review + security scan + tests, todo corriendo en paralelo en cada PR.
Recursos Adicionales
- Continuous Delivery — Jez Humble — Referencia clásica
- The DORA State of DevOps Report — Métricas que importan en CI/CD
- GitHub Actions: jobs in parallel — Sintaxis de paralelización
- Site Reliability Engineering: Release Engineering — Cómo Google diseña deploys
- Mermaid — Para diagramas de pipelines en docs
- DORA Four Key Metrics — Para medir el pipeline