ADR-016 — Developer Experience — Makefile Facade

Architecture decision record — status: Accepted.

Source: docs/adr/ADR-016-developer-experience-makefile.md

ADR-016: Developer Experience — Makefile Facade

Estado

Accepted

Fecha

2026-07-17

Aceptación

Gate humano 2026-07-17 — Accepted en sesión makefile-dx-facade.

Contexto

La semilla AI-SDLC no fija stack de aplicación (constitution, DOC-010). Aun así, humanos y agentes IA necesitan una interfaz DX estable para onboarding, calidad y ship.

En proyectos de referencia (p. ej. IVPrior ADR-041) un Makefile raíz delgado actúa como fachada: make help, make doctor, make check, make ship, delegando a scripts/package manager/Docker. Sin esa fachada, los agentes inventan comandos ad hoc (pnpm test, npm run …) antes de que el stack exista.

Decisión

1. Makefile como interfaz DX canónica

Se adopta un Makefile en la raíz del repositorio como contrato para:

TargetPropósito
helpListar comandos (default goal)
doctorDiagnóstico de entorno (scripts/doctor.sh)
checkGate de calidad local (= contrato CI cuando exista)
shipInvocar scripts/sd-ship.sh

Targets adicionales (install, lint, test, local-up, …) pueden existir como stubs hasta el ADR de stack; MUST documentarse y MUST NOT invocar herramientas inventadas.

2. Delegación, no fuente de verdad de build

El Makefile delega a scripts y al tooling del stack elegido. No duplica lógica de build ni gestión de dependencias. Cuando exista package manager / Turborepo / Compose, esos artefactos serán la fuente de verdad; make solo orquesta.

3. Fase seed (sin stack)

  • make check MAY salir 0 con mensaje explícito SKIP (sin apps que verificar).
  • Tras ADR de tecnología, make check MUST fallar si lint/typecheck/test/build fallan (paridad CI).
  • make doctor MUST NOT exigir Node/pnpm/Docker u otras herramientas hasta que un ADR las fije; solo verifica prerrequisitos de la semilla (p. ej. make, git, OpenSpec opcional).

4. Agentes IA

Documentación y reglas (AGENTS.md, seed-core, rol devops, skills de sesión/PR) MUST indicar que la interfaz preferida es make <target>. Los agentes MUST NOT inventar wrappers de calidad/onboarding cuando exista un target equivalente.

5. Plataforma

Requiere make (macOS/Linux por defecto; Windows: WSL o Git Bash).

Alternativas consideradas

Solo scripts en package.json / sin Makefile

Rechazado como única interfaz: aún no hay package manager; make help da onboarding uniforme a agentes entrenados en el patrón IVPrior/migration-factory.

Makefile como fuente de verdad (reemplazar scripts del stack)

Rechazado: contradice tooling moderno (Turborepo, etc.) cuando se elija stack.

Documentar “usar make” sin archivo

Rechazado: sin targets reales los agentes no tienen contrato verificable.

Consecuencias

Positivas

  • Contrato DX estable antes del stack.
  • Alineación con flujos de cierre (make ship) y PR (make check).
  • Fácil cablear targets al aceptar ADRs de tecnología.

Negativas

  • Requiere make instalado.
  • Hay que mantener stubs sincronizados al cablear el stack (coste bajo).

Referencias

  • Change OpenSpec: openspec/changes/makefile-dx-facade/
  • IVPrior: docs/adr/ADR-041-developer-experience-makefile-eslint.md (referencia; no copia stack)
  • docs/development/DOC-011-local-development-guide.md
  • docs/architecture/DOC-010-architecture-coding-principles.md