Guía práctica para implementar CI con artefactos de decisión

Opción 2 — Guía técnica práctica + Artefacto de decisión + CI (GitHub Actions)

Tiempo estimado de lectura: 5 min

Ideas clave:

• Entregar un flujo operativo ligero que obligue a decisiones humanas explicadas y verificables.
• Usar un artefacto de decisión en JSONL y una validación en CI para impedir atajos de IA.
• Combinar hooks pre-commit y GitHub Actions para bloquear merges sin aprobación humana.
• Checklist operativo y plantillas mínimas para integrarlo sin fricción.

Introducción

¿Quieres que esto se quede bonito en una carpeta o que obligue a alguien a cambiar la forma en que trabaja?

Tu texto ya tiene filo. Falta convertirlo en algo que haga tambalear decisiones: un artículo que los jefes lean; una guía que el equipo implemente; o herramientas listas para pegar en CI y que no dejen pasar atajos de la IA.

Elige una de estas cuatro y me pongo a darle dientes:

1) Versión larga (1.500–2.000 palabras) — Artículo profundo, con gancho potente, ejemplos técnicos, riesgos, y cierre que deja la puerta abierta. Ideal para blog/Medium.
2) Guía técnica práctica (800–1.200 palabras) — Comandos, flujo de trabajo, plantilla de artefacto de decisión, ejemplos de interceptación y checklist de gobernanza. Para equipos que lo quieren ejecutar ya.
3) Paquete GitHub-ready — Código: workflow de Actions que valida specs, template de artefacto de decisión (JSONL), hook pre-commit que bloquea merges si no hay aprobación humana. Incluye README y snippets.
4) LinkedIn/Twitter thread + TL;DR — Versión viral y condensada para provocar debate y atraer tráfico al artículo largo.

Extras opcionales (marcalos si los quieres):
– CI (GitHub Actions)
– Artefacto de decisión (JSON schema + ejemplos)
– Plantilla de PR que obliga a linkear Spec ↔ Tests ↔ Decision

Mi recomendación sincera: opción 2 + artefacto de decisión + workflow CI. Rápido impacto, baja fricción y protege al equipo sin romper su ritmo.

Respóndeme “Opción 1/2/3/4” y añade cualquiera de los extras. Empiezo en cuanto me digas.

Resumen rápido (lectores con prisa)

Qué: plantilla mínima para registrar decisiones humanas y bloquear merges sin aprobación.
Cuándo: siempre que una tarea involucre diseño, datos o salida generada por IA que afecte comportamiento del producto.
Por qué: convierte juicios blandos en artefactos verificables y auditables.
Cómo: JSONL + pre-commit hook + GitHub Actions que valida presencia y firma humana.

Qué vamos a entregar

• Plantilla de artefacto de decisión (JSON schema y ejemplo JSONL).
• Snippet de GitHub Actions que valida el artefacto antes de merge.
• Hook pre-commit y plantilla de PR que exige link Spec ↔ Tests ↔ Decision.
• Checklist operativo para Tech Leads y revisores.

Flujo operativo

Hook pre-commit y PR

1) Antes de abrir PR, el autor añade un artefacto de decisión en la carpeta /decisions/ como un archivo .jsonl que documenta el problema, alternativas, riesgo y aprobación humana.

2) Un hook pre-commit valida que el PR incluya al menos un archivo nuevo o modificado en /decisions/ cuando el cambio toca áreas sensibles (config, ML models, infra, reglas de negocio).

Ejemplo mínimo de uso del hook: verificar que exista referencia en la plantilla de PR y en los archivos cambiados. Si falta, bloquear commit y mostrar checklist.

Validación en CI

En GitHub Actions: ejecutar un job que valide el JSON schema del artefacto, compruebe firma o usuario aprobador y verifique que el PR linkea Spec ↔ Tests ↔ Decision. Si falla, marcar el check como requerido para merge.

Artefacto de decisión (JSON schema + ejemplos)

Estructura mínima del artefacto: un registro por decisión en formato JSONL. Debe incluir campos obligatorios para trazabilidad y para que la CI valide su completa.

{
  "id": "decision-2026-03-27-01",
  "title": "Cambiar inferencia a ruta A",
  "author": "nombre.apellido",
  "date": "2026-03-27T12:00:00Z",
  "scope": ["infra", "models"],
  "alternatives": ["mantener ruta B", "ajustar umbral"],
  "decision": "usar ruta A por mayor rendimiento en escenario X",
  "risks": ["sesgo en datos X", "mayor coste de inferencia"],
  "approver": "tech_lead.nombre",
  "tests_link": "PR#123 - tests integracion",
  "notes": "Se aplicará rollback si métricas Y bajan 5% en 24h"
}

JSON Schema (mínimo) — validar que todos los campos obligatorios existan y que “approver” sea distinto al “author”.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["id","title","author","date","scope","decision","risks","approver","tests_link"],
  "properties": {
    "id": {"type":"string"},
    "title": {"type":"string"},
    "author": {"type":"string"},
    "date": {"type":"string","format":"date-time"},
    "scope": {"type":"array","items":{"type":"string"}},
    "decision": {"type":"string"},
    "risks": {"type":"array","items":{"type":"string"}},
    "approver": {"type":"string"},
    "tests_link": {"type":"string"}
  }
}

Ejemplos prácticos

Ejemplo: interceptar un cambio impulsado por IA

Si un PR introduce un script que genera prompts o modifica reglas de scoring, la validación detecta la presencia de cambios en /models, /rules o /prompts y exige un nuevo archivo en /decisions/ explicando por qué el cambio es seguro y quién aprobó.

Snippet GitHub Actions (validación básica)

name: Validate Decision Artifact
on: [pull_request]
jobs:
  validate-decision:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Validate JSON schema
        run: |
          pip install jsonschema
          python -c "import json,sys; import jsonschema,glob
files=glob.glob('decisions/*.jsonl')
if not files: sys.exit(1)
# validate each line
schema=json.load(open('decisions/schema.json'))
for f in files:
  for l in open(f):
    jsonschema.validate(json.loads(l), schema)
" 

Marcar este job como requerido en la rama protegida evita merges hasta que el artefacto sea correcto y aprobado.

Checklist de gobernanza

• ¿Existe archivo en /decisions/ para este cambio?
• ¿El approver es una persona distinta al autor?
• ¿Se han enlazado tests y especificación en la plantilla de PR?
• ¿Se añadieron notas de rollback y métricas de éxito?
• ¿CI pasó validaciones de schema y pruebas automáticas?

Cierre

La combinación de un artefacto de decisión simple, hooks y CI reduce atajos sin introducir fricción excesiva. Es operativa, auditable y escalable: empieza con el schema mínimo y amplía campos (post-mortems, métricas, experiment IDs) solo cuando el equipo lo necesite.

Dominicode Labs

Si quieres prototipos y snippets adicionales para automatizar validaciones y plantillas, puedes ver recursos relacionados en Dominicode Labs. Considera esto como una continuación práctica de la guía, no como un paso obligatorio.

FAQ

¿Qué formato debe tener el artefacto de decisión?

Formato JSONL con campos mínimos: id, title, author, date, scope, decision, risks, approver, tests_link. Debe validarse contra un JSON Schema en CI.

¿Quién debe aprobar las decisiones?

Preferible que un Tech Lead o miembro independiente del equipo afectado realice la aprobación. El approver debe ser diferente al author para mantener separación de responsabilidades.

¿Qué pasa si el PR no incluye el artefacto?

El hook o la job en CI debe marcar el check como fallido y bloquear el merge hasta que se añada y valide el artefacto de decisión.

¿El schema impide cambios rápidos?

No: el schema mínimo es intencionalmente ligero. Si el cambio es urgente, el proceso permite una entrada rápida documentada y un post-mortem posterior.

¿Cómo enlazo Spec ↔ Tests ↔ Decision en la PR?

Usa la plantilla de PR que incluya campos: Link Spec, Link Tests, Link Decision. CI verifica presencia de esos enlaces y la existencia del archivo en /decisions/.

¿Puedo automatizar aprobación para cambios triviales?

Puedes configurar reglas que eximan cambios en rutas no sensibles, pero la lista de excepciones debe estar versionada y ser revisada por el equipo de liderazgo técnico.