API-first y CLI-first para agentes IA
Cuando un agente puede ejecutar SQL, invocar scripts arbitrarios o mutar archivos de configuración sin contrato, la automatización escala más rápido que la comprensión. La arquitectura que aplico en este archivo invierte ese orden: Human UI / Agent / Skill / CLI → API → Domain → PostgreSQL. No la presento como única solución universal, sino como regla operativa que ha demostrado reducir sorpresas.
La regla central
El CLI consume la API; no accede directamente a la base de datos.
Esa restricción no es purismo. Concentra la semántica de negocio en un lugar auditable, permite validación uniforme, simplifica permisos y hace legible el alcance de una operación antes de ejecutarla.
Si un agente necesita listar tareas, crear una o ejecutar un runbook, lo hace a través de endpoints o comandos que encapsulan esa intención —no mediante consultas ad hoc ni conexiones PostgreSQL embebidas en skills.
Cuatro capas de invocación
| Capa | Rol |
|---|---|
| API | Capacidades y semántica de dominio; contrato estable. |
| CLI | Invocación determinista de esas capacidades; salida parseable. |
| Skill | Razonamiento del agente alrededor de capacidades; no reimplementa la API. |
| Runbook | Procedimiento operacional completo que encadena pasos con gates. |
La cadena conceptual es API → CLI → Skill → Runbook, de abstracción estable hacia arriba. Un runbook puede invocar skills; un skill invoca CLI o API; el CLI siempre termina en la API para mutaciones de negocio.
Qué gana cada actor
Human UI comparte el mismo backend que los agentes. No hay «modo admin oculto» con acceso directo a tablas salvo operaciones de emergencia documentadas y fuera del camino normal.
Agentes obtienen un vocabulario acotado. En lugar de inferir esquemas SQL, seleccionan operaciones con nombres, parámetros y respuestas tipadas. Eso encaja con el Director–Implementer Loop: el implementador propone invocaciones concretas; el Director evalúa alcance y autorización.
Skills documentan cómo razonar alrededor de capacidades —cuándo usar tasks list frente a tasks create, qué evidencia recopilar antes de un --apply— sin duplicar la lógica de negocio.
Runbooks describen procedimientos completos: incident-response, onboarding, backfill. Encadenan CLI, validaciones y puntos de aprobación humana.
Core Service: el único gatekeeper
El diagrama de este artículo muestra un Core Service entre interfaces y datos. Sus responsabilidades típicas:
- autenticación y autorización;
- validación de entrada;
- lógica de negocio y orquestación;
- auditoría y observabilidad;
- rate limiting.
La base de datos queda detrás de ese servicio, no al alcance de agentes ni de CLIs mal diseñados.
Relación con vertical slices
Una feature no está terminada cuando existe la API aislada o un script suelto. El artículo Vertical slices describe el recorrido completo hasta smoke de producción. API-first y CLI-first son la mitad inferior de ese recorrido: contrato limpio y operación determinista antes de UI, deploy y verificación final.
Límites
Esta arquitectura no impide por sí sola backends mal implementados, permisos excesivos ni skills que ignoren la política. Requiere disciplina en code review, tests de contrato y separación de roles —especialmente en flujos agénticos.
Tampoco prohíbe acceso directo a la base en migraciones de emergencia o herramientas de DBA; simplemente los excluye del camino normal de automatización y agentes.