Guía de Flujo de Trabajo Git de AIOX

🌐 EN | PT | ES

Story: 2.2-git-workflow-implementation.yaml

Tabla de Contenidos

Descripción General
Arquitectura de Defensa en Profundidad
Capa 1: Validación Pre-commit
Capa 2: Validación Pre-push
Capa 3: Pipeline CI/CD
Protección de Ramas
Flujo de Trabajo Diario
Resolución de Problemas
Consejos de Rendimiento

Descripción General

Synkra AIOX implementa una estrategia de validación de Defensa en Profundidad con tres capas progresivas que detectan problemas tempranamente y aseguran la calidad del código antes del merge.

¿Por Qué Tres Capas?

Retroalimentación rápida - Detectar problemas inmediatamente durante el desarrollo
Validación local - Sin dependencia de la nube para verificaciones básicas
Validación autoritativa - Puerta final antes del merge
Consistencia de stories - Asegurar que el desarrollo se alinee con las stories

Diagrama de Arquitectura

┌─────────────────────────────────────────────────────────────┐
│                     Developer Workflow                       │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│ Layer 1: Pre-commit Hook (Local - <5s)                     │
│ ✓ ESLint (code quality)                                     │
│ ✓ TypeScript (type checking)                                │
│ ✓ Cache enabled                                              │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│ Layer 2: Pre-push Hook (Local - <2s)                       │
│ ✓ Story checkbox validation                                 │
│ ✓ Status consistency                                         │
│ ✓ Required sections                                          │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│ Layer 3: GitHub Actions CI (Cloud - 2-5min)                │
│ ✓ All lint/type checks                                      │
│ ✓ Full test suite                                           │
│ ✓ Code coverage (≥80%)                                      │
│ ✓ Story validation                                          │
│ ✓ Branch protection                                         │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
                      ┌──────────────┐
                      │ Merge Ready  │
                      └──────────────┘

Arquitectura de Defensa en Profundidad

Capa 1: Pre-commit (Local - Rápido)

Objetivo de Rendimiento: <5 segundos Disparador: git commit Ubicación: .husky/pre-commit

Qué valida:

Calidad de código ESLint
Verificación de tipos TypeScript
Errores de sintaxis
Problemas de importación

Cómo funciona:

# Se dispara automáticamente al hacer commit
git add .
git commit -m "feat: add feature"

# Ejecuta:
# 1. ESLint con caché (.eslintcache)
# 2. Compilación incremental de TypeScript (.tsbuildinfo)

Beneficios:

⚡ Retroalimentación rápida (<5s)
💾 Con caché para velocidad
🔒 Previene commits de código roto
🚫 Sin sintaxis inválida en el historial

Capa 2: Pre-push (Local - Validación de Stories)

Objetivo de Rendimiento: <2 segundos Disparador: git push Ubicación: .husky/pre-push

Qué valida:

Completitud de checkboxes de story vs estado
Secciones requeridas de story presentes
Consistencia de estado
Registros del agente Dev

Cómo funciona:

# Se dispara automáticamente al hacer push
git push origin feature/my-feature

# Valida todos los archivos de story en docs/stories/

Reglas de Validación:

Consistencia de Estado:

# ❌ Inválido: completado pero tareas incompletas
status: "completed"
tasks:
  - "[x] Task 1"
  - "[ ] Task 2"  # ¡Error!

# ✅ Válido: todas las tareas completadas
status: "completed"
tasks:
  - "[x] Task 1"
  - "[x] Task 2"

Secciones Requeridas:

id
title
description
acceptance_criteria
status

Flujo de Estados:

ready → in progress → Ready for Review → completed

Capa 3: CI/CD (Nube - Autoritativo)

Rendimiento: 2-5 minutos Disparador: Push a cualquier rama, creación de PR Plataforma: GitHub Actions Ubicación: .github/workflows/ci.yml

Jobs:

ESLint (job lint)
- Se ejecuta en entorno limpio
- Sin dependencia de caché
TypeScript (job typecheck)
- Verificación completa de tipos
- Sin compilación incremental
Tests (job test)
- Suite completa de tests
- Reporte de cobertura
- Umbral del 80% obligatorio
Validación de Stories (job story-validation)
- Todas las stories validadas
- Consistencia de estado verificada
Resumen de Validación (job validation-summary)
- Agrega todos los resultados
- Bloquea el merge si alguno falla

Monitoreo de Rendimiento:

Job de rendimiento opcional
Mide tiempos de validación
Solo informativo

Capa 1: Validación Pre-commit

Referencia Rápida

# Validación manual
npm run lint
npm run typecheck

# Auto-corrección de problemas de lint
npm run lint -- --fix

# Saltar hook (NO recomendado)
git commit --no-verify

Configuración de ESLint

Archivo: .eslintrc.json

{
  "extends": ["eslint:recommended", "plugin:@typescript-eslint/recommended"],
  "parser": "@typescript-eslint/parser",
  "plugins": ["@typescript-eslint"],
  "cache": true,
  "cacheLocation": ".eslintcache"
}

Características clave:

Soporte para TypeScript
Caché habilitado
Advierte sobre console.log
Ignora variables no usadas con prefijo _

Configuración de TypeScript

Archivo: tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "strict": true,
    "incremental": true,
    "tsBuildInfoFile": ".tsbuildinfo"
  }
}

Características clave:

Target ES2022
Modo estricto
Compilación incremental
Módulos CommonJS

Optimización de Rendimiento

Archivos de Caché:

.eslintcache - Resultados de ESLint
.tsbuildinfo - Datos incrementales de TypeScript

Primera ejecución: ~10-15s (sin caché) Ejecuciones subsiguientes: <5s (con caché)

Invalidación de caché:

Cambios de configuración
Actualizaciones de dependencias
Eliminación de archivos

Capa 2: Validación Pre-push

Referencia Rápida

# Validación manual
node .aiox-core/utils/aiox-validator.js pre-push
node .aiox-core/utils/aiox-validator.js stories

# Validar una sola story
node .aiox-core/utils/aiox-validator.js story docs/stories/1.1-story.yaml

# Saltar hook (NO recomendado)
git push --no-verify

Validador de Stories

Ubicación: .aiox-core/utils/aiox-validator.js

Características:

Salida de terminal coloreada
Indicadores de progreso
Mensajes de error claros
Advertencias para problemas potenciales

Ejemplo de Salida:

══════════════════════════════════════════════════════════
  Story Validation: 2.2-git-workflow-implementation.yaml
══════════════════════════════════════════════════════════

Story: 2.2 - Git Workflow with Multi-Layer Validation
Status: in progress

Progress: 12/15 tasks (80.0%)

✓ Story validation passed with warnings

Warning:
  • Consider updating status to 'Ready for Review'

Reglas de Validación

1. Formato de Checkbox

Formatos soportados:

[x] - Completado (minúscula)
[X] - Completado (mayúscula)
[ ] - Incompleto

No reconocidos:

[o], [*], [-] - No cuentan como completos

2. Consistencia de Estado

Estado	Regla
`ready`	Ninguna tarea debería estar marcada
`in progress`	Algunas tareas marcadas
`Ready for Review`	Todas las tareas marcadas
`completed`	Todas las tareas marcadas

3. Secciones Requeridas

Todas las stories deben tener:

id: "X.X"
title: "Story Title"
description: "Story description"
status: "ready" | "in progress" | "Ready for Review" | "completed"
acceptance_criteria:
  - name: "Criterion"
    tasks:
      - "[ ] Task"

4. Registro del Agente Dev

Recomendado pero no requerido:

dev_agent_record:
  agent_model: 'claude-sonnet-4-5'
  implementation_date: '2025-01-23'

Advertencia si falta.

Mensajes de Error

Secciones Requeridas Faltantes:

✗ Missing required sections: description, acceptance_criteria

Inconsistencia de Estado:

✗ Story marked as completed but only 12/15 tasks are checked

Archivo No Existente:

✗ Story file not found: docs/stories/missing.yaml

Capa 3: Pipeline CI/CD

Estructura del Workflow

Archivo: .github/workflows/ci.yml

Jobs:

lint - Validación ESLint
typecheck - Verificación TypeScript
test - Tests Jest con cobertura
story-validation - Consistencia de stories
validation-summary - Agregar resultados
performance (opcional) - Métricas de rendimiento

Detalles de Jobs

Job ESLint

- name: Run ESLint
  run: npm run lint

Se ejecuta en Ubuntu latest
Timeout: 5 minutos
Usa caché de npm
Falla con cualquier error de lint

Job TypeScript

- name: Run TypeScript type checking
  run: npm run typecheck

Se ejecuta en Ubuntu latest
Timeout: 5 minutos
Falla con errores de tipos

Job Test

- name: Run tests with coverage
  run: npm run test:coverage

Se ejecuta en Ubuntu latest
Timeout: 10 minutos
Cobertura subida a Codecov
Umbral de cobertura del 80% obligatorio

Job Validación de Stories

- name: Validate story checkboxes
  run: node .aiox-core/utils/aiox-validator.js stories

Se ejecuta en Ubuntu latest
Timeout: 5 minutos
Valida todas las stories

Job Resumen de Validación

needs: [lint, typecheck, test, story-validation]
if: always()

Se ejecuta después de todas las validaciones
Verifica estados de todos los jobs
Falla si cualquier validación falló
Proporciona resumen

Disparadores de CI

Eventos de Push:

Rama master
Rama develop
Ramas feature/**
Ramas bugfix/**

Eventos de Pull Request:

Contra master
Contra develop

Ver Resultados de CI

# Ver checks del PR
gh pr checks

# Ver ejecuciones del workflow
gh run list

# Ver ejecución específica
gh run view <run-id>

# Re-ejecutar jobs fallidos
gh run rerun <run-id>

Protección de Ramas

Configuración

# Ejecutar script de configuración
node scripts/setup-branch-protection.js

# Ver protección actual
node scripts/setup-branch-protection.js --status

Requisitos

GitHub CLI (gh) instalado
Autenticado con GitHub
Acceso de administrador al repositorio

Reglas de Protección

Protección de Rama Master:

Verificaciones de Estado Requeridas:
- ESLint
- TypeScript Type Checking
- Jest Tests
- Story Checkbox Validation
Revisiones de Pull Request:
- 1 aprobación requerida
- Descartar revisiones obsoletas en nuevos commits
Reglas Adicionales:
- Historial lineal obligatorio (solo rebase)
- Force pushes bloqueados
- Eliminación de rama bloqueada
- Reglas aplican a administradores

Configuración Manual

Via GitHub CLI:

# Establecer verificaciones de estado requeridas
gh api repos/OWNER/REPO/branches/master/protection/required_status_checks \
  -X PUT \
  -f strict=true \
  -f contexts[]="ESLint" \
  -f contexts[]="TypeScript Type Checking"

# Requerir revisiones de PR
gh api repos/OWNER/REPO/branches/master/protection/required_pull_request_reviews \
  -X PUT \
  -f required_approving_review_count=1

# Bloquear force pushes
gh api repos/OWNER/REPO/branches/master/protection/allow_force_pushes \
  -X DELETE

Flujo de Trabajo Diario

Iniciando una Nueva Funcionalidad

# 1. Actualizar master
git checkout master
git pull origin master

# 2. Crear rama de funcionalidad
git checkout -b feature/my-feature

# 3. Hacer cambios
# ... editar archivos ...

# 4. Commit (dispara pre-commit)
git add .
git commit -m "feat: add my feature [Story X.X]"

# 5. Push (dispara pre-push)
git push origin feature/my-feature

# 6. Crear PR
gh pr create --title "feat: Add my feature" --body "Description"

Actualizando una Story

# 1. Abrir archivo de story
code docs/stories/X.X-story.yaml

# 2. Marcar tareas completadas
# Cambiar: - "[ ] Task"
# A:       - "[x] Task"

# 3. Actualizar estado si es necesario
# Cambiar: status: "in progress"
# A:       status: "Ready for Review"

# 4. Commit de actualizaciones de story
git add docs/stories/X.X-story.yaml
git commit -m "docs: update story X.X progress"

# 5. Push (valida story)
git push

Corrigiendo Fallos de Validación

Errores de ESLint:

# Auto-corregir problemas
npm run lint -- --fix

# Verificar problemas restantes
npm run lint

# Commit de correcciones
git add .
git commit -m "style: fix lint issues"

Errores de TypeScript:

# Ver todos los errores
npm run typecheck

# Corregir errores en código
# ... editar archivos ...

# Verificar corrección
npm run typecheck

# Commit de correcciones
git add .
git commit -m "fix: resolve type errors"

Errores de Validación de Stories:

# Verificar stories
node .aiox-core/utils/aiox-validator.js stories

# Corregir archivo de story
code docs/stories/X.X-story.yaml

# Verificar corrección
node .aiox-core/utils/aiox-validator.js story docs/stories/X.X-story.yaml

# Commit de corrección
git add docs/stories/
git commit -m "docs: fix story validation"

Fallos de Tests:

# Ejecutar tests
npm test

# Ejecutar test específico
npm test -- path/to/test.js

# Corregir tests fallidos
# ... editar archivos de test ...

# Ejecutar con cobertura
npm run test:coverage

# Commit de correcciones
git add .
git commit -m "test: fix failing tests"

Haciendo Merge de un Pull Request

# 1. Asegurar que CI pasa
gh pr checks

# 2. Obtener aprobación
# (Esperar revisión de miembro del equipo)

# 3. Merge (squash)
gh pr merge --squash --delete-branch

# 4. Actualizar master local
git checkout master
git pull origin master

Resolución de Problemas

Hook No Se Ejecuta

Síntomas: Commit tiene éxito sin validación

Soluciones:

Verificar instalación de Husky:

npm run prepare

Verificar que existen archivos de hook:

ls -la .husky/pre-commit
ls -la .husky/pre-push

Verificar permisos de archivos (Unix):

chmod +x .husky/pre-commit
chmod +x .husky/pre-push

Hook Pre-commit Lento

Síntomas: Pre-commit toma >10 segundos

Soluciones:

Limpiar cachés:

rm .eslintcache .tsbuildinfo
git commit  # Reconstruye caché

Verificar cambios de archivos:

git status
# Commit de menos archivos a la vez

Actualizar dependencias:

npm update

Validación de Story Falla

Síntoma: Pre-push falla con errores de story

Problemas Comunes:

Desajuste de checkbox:

# Error: Estado completado pero tareas incompletas
status: 'completed'
tasks:
  - '[x] Task 1'
  - '[ ] Task 2' # ← Corregir esto


# Solución: Completar todas las tareas o cambiar estado

Secciones faltantes:

# Error: Secciones requeridas faltantes
id: '1.1'
title: 'Story'
# Faltan: description, acceptance_criteria, status

# Solución: Agregar secciones faltantes

YAML inválido:

# Error: Sintaxis YAML inválida
tasks:
  - "[ ] Task 1
  - "[ ] Task 2"  # ← Falta comilla de cierre arriba

# Solución: Corregir sintaxis YAML

CI Falla pero Local Pasa

Síntomas: CI falla pero todas las validaciones locales pasan

Causas Comunes:

Diferencias de caché:

# Limpiar cachés locales
rm -rf node_modules .eslintcache .tsbuildinfo coverage/
npm ci
npm test

Diferencias de entorno:

# Usar misma versión de Node que CI (18)
nvm use 18
npm test

Archivos sin commit:

# Verificar cambios sin commit
git status

# Stash si es necesario
git stash

Protección de Rama Bloquea Merge

Síntomas: No puede hacer merge del PR incluso con aprobaciones

Verificar:

Checks requeridos pasan:

gh pr checks
# Todos deben mostrar ✓

Aprobaciones requeridas:

gh pr view
# Verificar sección "Reviewers"

Rama está actualizada:

# Actualizar rama
git checkout feature-branch
git rebase master
git push --force-with-lease

Consejos de Rendimiento

Gestión de Caché

Mantener cachés:

.eslintcache - Resultados de ESLint
.tsbuildinfo - Info de build de TypeScript
coverage/ - Datos de cobertura de tests

Agregar a .gitignore:

.eslintcache
.tsbuildinfo
coverage/

Desarrollo Incremental

Mejores Prácticas:

Commits pequeños:
- Menos archivos = validación más rápida
- Más fácil de debuggear fallos
Probar durante el desarrollo:

# Ejecutar validación manualmente antes del commit
npm run lint
npm run typecheck
npm test

Corregir problemas inmediatamente:
- No dejar que los problemas se acumulen
- Más fácil de corregir en contexto

Optimización de CI

Optimizaciones del workflow:

Jobs paralelos - Todas las validaciones se ejecutan en paralelo
Timeouts de jobs - Fallan rápido en cuelgues
Caché - Dependencias npm cacheadas
Jobs condicionales - Job de rendimiento solo en PRs

Rendimiento de Validación de Stories

Rendimiento Actual:

Una sola story: <100ms
Todas las stories: <2s (típico)

Consejos de optimización:

Mantener stories enfocadas - Una funcionalidad por story
Limitar conteo de tareas - Dividir stories grandes en más pequeñas
YAML válido - Errores de parsing ralentizan validación

Temas Avanzados

Saltando Validaciones

Cuándo es apropiado:

Hotfixes de emergencia
Cambios solo de documentación
Cambios de configuración de CI

Cómo saltar:

# Saltar pre-commit
git commit --no-verify

# Saltar pre-push
git push --no-verify

# Saltar CI (no recomendado)
# Agregar [skip ci] al mensaje de commit
git commit -m "docs: update [skip ci]"

Advertencia: Solo saltar cuando sea absolutamente necesario. Las validaciones saltadas no detectarán problemas.

Validación Personalizada

Agregar validadores personalizados:

Crear función validadora:

// .aiox-core/utils/custom-validator.js
module.exports = async function validateCustom() {
  // Tu lógica de validación
  return { success: true, errors: [] };
};

Agregar al hook:

# .husky/pre-commit
node .aiox-core/utils/aiox-validator.js pre-commit
node .aiox-core/utils/custom-validator.js

Agregar a CI:

# .github/workflows/ci.yml
- name: Custom validation
  run: node .aiox-core/utils/custom-validator.js

Soporte para Monorepo

Para monorepos:

Validaciones con alcance:

// Solo validar paquetes cambiados
const changedFiles = execSync('git diff --name-only HEAD~1').toString();
const packages = getAffectedPackages(changedFiles);

Validación paralela de paquetes:

strategy:
  matrix:
    package: [package-a, package-b, package-c]

Referencias

AIOX Validator: .aiox-core/utils/aiox-validator.js
CI Workflow: .github/workflows/ci.yml

¿Preguntas? ¿Problemas?

FilesExpand file tree

git-workflow-guide.md

Latest commit

History

git-workflow-guide.md

File metadata and controls

Guía de Flujo de Trabajo Git de AIOX

Tabla de Contenidos

Descripción General

¿Por Qué Tres Capas?

Diagrama de Arquitectura

Arquitectura de Defensa en Profundidad

Capa 1: Pre-commit (Local - Rápido)

Capa 2: Pre-push (Local - Validación de Stories)

Capa 3: CI/CD (Nube - Autoritativo)

Capa 1: Validación Pre-commit

Referencia Rápida

Configuración de ESLint

Configuración de TypeScript

Optimización de Rendimiento

Capa 2: Validación Pre-push

Referencia Rápida

Validador de Stories

Reglas de Validación

1. Formato de Checkbox

2. Consistencia de Estado

3. Secciones Requeridas

4. Registro del Agente Dev

Mensajes de Error

Capa 3: Pipeline CI/CD

Estructura del Workflow

Detalles de Jobs

Job ESLint

Job TypeScript

Job Test

Job Validación de Stories

Job Resumen de Validación

Disparadores de CI

Ver Resultados de CI

Protección de Ramas

Configuración

Requisitos

Reglas de Protección

Configuración Manual

Flujo de Trabajo Diario

Iniciando una Nueva Funcionalidad

Actualizando una Story

Corrigiendo Fallos de Validación

Haciendo Merge de un Pull Request

Resolución de Problemas

Hook No Se Ejecuta

Hook Pre-commit Lento

Validación de Story Falla

CI Falla pero Local Pasa

Protección de Rama Bloquea Merge

Consejos de Rendimiento

Gestión de Caché

Desarrollo Incremental

Optimización de CI

Rendimiento de Validación de Stories

Temas Avanzados

Saltando Validaciones

Validación Personalizada

Soporte para Monorepo

Referencias