Flujo Git y Versionado

🚫 Antes — caos actual

dev-alvaro-final-v3        ← activa hace 3 semanas
develop-merge-test         ← nadie sabe quien la creo
main-backup                ← "por si acaso"
git log --oneline main
a3f9 arreglado todo
b1c2 fix 2
cc44 wtf esto no funciona
dd90 subido .env por error ← CRITICO
ee12 cambios varios

✓ Despues — flujo estructurado

main          ← siempre deployable a Vercel
feature/...  ← viven max 3 dias
agent/...    ← worktree de Claude Code
git log --oneline main
7a2b3c feat: modulo de pagos con Stripe
8d4e5f refactor: extraer validacion a lib/
9f6a7b feat: dashboard de matriculados
c8d9e0 fix: race condition en inscripcion
d1e2f3 chore: añadir lint-staged + husky

📋

git log --oneline --graph — semana del 9 al 13 de junio

f3a9d2e feat: add course enrollment email confirmation (SendGrid) 2026-06-13 17:42

e7c1b8f test: add integration tests for enrollment API endpoint 2026-06-13 15:10

d4b0a7c feat: add POST /api/enroll with Zod validation and Prisma write 2026-06-13 11:30

c9e5f2d refactor: extract auth session helper to lib/session.ts 2026-06-12 16:55

b2a8e1c fix: resolve race condition in concurrent enrollment requests 2026-06-12 14:20

a7f4d9b feat: add EnrollButton component with optimistic UI state 2026-06-11 18:05

9e3c6a8 refactor: move CourseCard to shared components, no behavior change 2026-06-11 11:00

8d1b4f7 chore: configure lint-staged, husky pre-commit hook, commitlint 2026-06-09 09:15

7c0a3e6 chore: add .gitignore with .env, .next/, dist/, node_modules/ 2026-06-09 09:00

🌿

Nomenclatura de ramas activa

# Feature (dev humano — max 3 dias)
feature/stripe-payments
feature/course-dashboard
feature/enrollment-api

# Agent worktree (Claude Code)
agent/fix-enrollment-race
agent/add-zod-schemas

# Bugs urgentes
fix/email-duplicate-send

# Infra / tooling
chore/upgrade-prisma-5
    

Ramas que duran >3 dias = riesgo de divergencia. Usar feature flags en su lugar.

🤖

Worktrees para Claude Code en paralelo

main

~/cultivashop/

Dev humano (Alvaro) — trabajo principal

feature branch

~/cultivashop-payments/

Dev humano (Maria) — feature/stripe-payments

agent worktree

~/cultivashop-agent/

Claude Code — agent/add-zod-schemas sin interferir

# Setup worktree para Claude Code
git worktree add ../cultivashop-agent agent/add-zod-schemas

# Claude trabaja en ../cultivashop-agent/
# Alvaro trabaja en ../cultivashop/ sin conflictos

# Al terminar Claude, hacer PR y limpiar
git worktree remove ../cultivashop-agent
    

.gitignore

# Dependencias
node_modules/

# Build
.next/
dist/
out/

# Entorno — NUNCA commitear
.env
.env.local
.env.*.local

# Prisma dev
prisma/dev.db
prisma/dev.db-journal

# IDE
.vscode/settings.json
.idea/

# OS
.DS_Store
Thumbs.db

# Vercel
.vercel
    

package.json (fragmento)

{
  "scripts": {
    "prepare": "husky"
  },
  "lint-staged": {
    "*.{ts,tsx}": [
      "eslint --fix --max-warnings 0",
      "prettier --write"
    ],
    "*.{json,md,css}": [
      "prettier --write"
    ],
    "*.prisma": [
      "prisma format"
    ]
  },
  "devDependencies": {
    "husky": "^9.0.0",
    "lint-staged": "^15.0.0",
    "@commitlint/cli": "^19.0.0",
    "@commitlint/config-conventional":
      "^19.0.0"
  }
}
    

.commitlintrc.json

{
  "extends": [
    "@commitlint/config-conventional"
  ],
  "rules": {
    "type-enum": [2, "always", [
      "feat",
      "fix",
      "refactor",
      "test",
      "docs",
      "chore",
      "perf"
    ]],
    "subject-max-length": [
      2, "always", 72
    ],
    "subject-case": [
      2, "always", "lower-case"
    ]
  }
}
    

✔

Checklist pre-commit (Next.js + TypeScript)

✓

git diff --staged — revisar exactamente lo que va a commitear
✓

Cero secretos: grep por API_KEY|SECRET|password|token en el diff
✓

npm run build — Next.js compila sin errores
✓

npx tsc --noEmit — TypeScript limpio (0 errores)
✓

npm run lint — ESLint 0 warnings (--max-warnings 0)
✓

npx prisma validate — esquema Prisma consistente
✓

npm test -- --passWithNoTests — test suite verde
✓

Commit hace una sola cosa logica (max ~300 lineas)
✓

Mensaje sigue formato tipo: descripcion breve en minusculas
✓

No hay .next/, .env ni node_modules/ en el staged

📝

Change Summary — ejemplo de entrega de Claude Code

CHANGES MADE: + src/app/api/enroll/route.ts ← nuevo endpoint POST + src/lib/validation/enroll.ts ← EnrollSchema (Zod) + src/lib/session.ts ← helper extraido ~ src/app/api/auth/route.ts ← usa nuevo helper ~ prisma/schema.prisma ← add Enrollment model THINGS I DIDN'T TOUCH (intentionally): src/app/api/payments/route.ts ← validacion pendiente, fuera de scope src/components/CourseCard.tsx ← tiene dead code, tarea separada POTENTIAL CONCERNS: ! EnrollSchema rechaza campos extra (strict mode). Confirmar si frontends externos envian metadata extra. ! Migration autogenerada: 20260613_add_enrollment. Ejecutar en staging antes de produccion.

⚠

Problemas identificados y acciones correctivas

.env comiteado dos veces — Accion: rotar TODAS las API keys (Stripe, SendGrid, DB). Anadir .env* al .gitignore ahora. Usar git filter-branch o BFG para expurgar el historial si el repo es publico.

Rama dev-alvaro-final-v3 activa hace 3 semanas — Accion: hacer merge o eliminar esta semana. Cualquier feature incompleta va detras de un feature flag en main.

Mensajes "arreglado todo", "fix 2", "wtf" — Accion: commitlint en el hook pre-commit rechaza mensajes que no sigan el formato tipo: descripcion. Reeducar al equipo con esta guia.

Claude Code y devs en la misma rama — conflictos continuos — Accion: worktrees separados. Claude opera siempre en agent/* con su propio directorio, nunca en main directamente.

Sin CI/CD — Accion: conectar Vercel a GitHub. Preview deployments automaticos en cada PR. Bloquear merge a main si build falla.

Flujo Git para CultivaShop