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?
• ¿Quién debe aprobar las decisiones?
• ¿Qué pasa si el PR no incluye el artefacto?
• ¿El schema impide cambios rápidos?
• ¿Cómo enlazo Spec ↔ Tests ↔ Decision en la PR?
• ¿Puedo automatizar aprobación para cambios triviales?

Respuesta 1

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

Respuesta 2

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.

Respuesta 3

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.

Respuesta 4

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.

Respuesta 5

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/.

Respuesta 6

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.