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 ↔ DecisionMi 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.
