Superlite: delegar un spec sin aprobar cada paso

Claude Code se detiene a pedir aprobación cada pocos minutos, el costo habitual de los agentes de IA autónomos cuando el flujo de trabajo prioriza la supervisión sobre la velocidad. Lo resume bien el post "Superlite: hand an agent a spec, come back to tested work", publicado en contextfirst.blog: su autor pidió un spec, se hizo un sándwich y volvió a encontrar al agente detenido en la sección 1, esperando un "sí" que llevaba veinte minutos ahí.

Este artículo explica por qué pasa eso, qué mecanismos (permisos, hooks y revisión automática de tareas) permiten delegar un spec completo sin supervisión constante, y cómo Superlite, el plugin de Claude Code que nació de esa frustración, los combina en la práctica.

TL;DR

• Los agentes se frenan porque cada herramienta sensible pide confirmación sin una regla de permisos previa.- Los hooks PreToolUse y PostToolUse interceptan cada acción y la aprueban o bloquean con código, sin preguntarte.- Superlite cambia 8 a 12 aprobaciones por feature por una sola, y mueve el resto de las reglas al código.- Un plan dividido en tareas sin archivos compartidos deja correr varios agentes a la vez en lugar de uno por uno.- La revisión automática por código reemplaza la aprobación humana, salvo en cambios destructivos o de seguridad.

¿Qué son los agentes de IA autónomos?

Los agentes de IA autónomos son programas que ejecutan tareas de desarrollo (planificar, escribir código, correr pruebas, corregir errores) encadenando llamadas a un modelo de lenguaje y herramientas del sistema, sin que un humano confirme cada paso intermedio: solo intervienen las decisiones destructivas, irreversibles o de seguridad.

Herramientas como Claude Code, Cursor o el modo agente de GitHub Copilot funcionan así por defecto. Reciben una instrucción, la descomponen en pasos y ejecutan cada herramienta (leer un archivo, correr un comando, editar código) a través de un bucle de planificar, actuar y observar el resultado.

Por diseño, la mayoría de esos agentes es conservadora. Antes de correr algo irreversible (borrar un archivo, hacer push, instalar una dependencia), se detienen y piden confirmación humana. Esa cautela evita desastres, pero también multiplica las pausas cuando el usuario ya sabe qué quiere construir.

Por qué los agentes de IA autónomos se detienen a cada paso

El post de contextfirst.blog profiló su propio flujo de trabajo (basado en el plugin "superpowers" para Claude Code) y encontró cinco cuellos de botella. El primero: entre 8 y 12 gates de aprobación humana por feature, uno por cada sección del diseño, más revisiones separadas del spec, del plan y del método de ejecución.

El segundo es la ejecución estrictamente secuencial: un implementador, después un revisor, después la siguiente tarea. En el primer benchmark del autor eso se tradujo en una cola de 21 despachos en un solo archivo, como un banco con una sola ventanilla y un almuerzo muy largo.

El tercero es la revisión después de cada tarea, con reintentos cuando la revisión encuentra algo: en un build de 34 minutos, 12 minutos se fueron solo en esas revisiones. El cuarto es correr la batería completa de tests varias veces, una por cada skill que quiere asegurarse de que nada cambió. El quinto es usar el modelo más potente (Opus) en el camino crítico: según el post, escribe código a la mitad de velocidad que Sonnet.

Ninguno de estos frenos es un error de diseño. Cada uno es una red de seguridad razonable cuando el objetivo es que un humano revise cada decisión. El problema aparece cuando el usuario ya sabe exactamente qué quiere construir: ahí la misma red de seguridad se convierte en una reunión de cuatro horas que se programó sola.
Un build de 34 minutos perdió 12 en revisiones repetidas, según contextfirst.blog.

Cómo funciona el modelo de permisos en Claude Code

Claude Code resuelve la primera capa de control con un sistema de permisos declarado en settings.json. Cada acción (correr un comando de shell, editar un archivo, llamar una herramienta MCP) se evalúa contra tres listas: allow (corre sin preguntar), ask (pide confirmación interactiva) y deny (nunca corre, ni siquiera se pregunta).

Las reglas usan patrones por herramienta y argumento, no solo por nombre de comando. Bash(git commit:*) autoriza cualquier commit, pero no un push; Bash(rm -rf:*) se puede poner directamente en deny para que ningún agente, por más que lo pida con buenos modales, borre un directorio completo.

El otro eje es el modo de permisos de la sesión: el modo por defecto pregunta ante cualquier acción no cubierta por una regla; acceptEdits aprueba ediciones de archivo automáticamente pero sigue preguntando por comandos de shell; plan no ejecuta nada hasta que el usuario aprueba el plan completo; y bypassPermissions corre todo salvo lo que esté explícitamente en deny. Superlite y proyectos similares dependen de este último modo combinado con reglas de deny bien pensadas, no de confiar en que el agente se porte bien.

flowchart TD
T["Agente llama una herramienta"] --> C{"Regla en permissions"}
C -->|"allow"| E["Ejecuta sin preguntar"]
C -->|"ask"| H["Hook o prompt interactivo"]
C -->|"deny"| D["Bloqueada, nunca corre"]
H --> F{"Hook decide"}
F -->|"approve"| E
F -->|"block"| D

Hooks: la otra capa de control

Los permisos deciden si una acción corre; los hooks deciden qué pasa antes y después de que corra, con código real en vez de una regla declarativa. Claude Code dispara eventos como PreToolUse (antes de ejecutar una herramienta), PostToolUse (después) y SessionStart (al abrir la sesión), y cada uno puede atarse a un script que recibe contexto en JSON por stdin y devuelve una decisión.

Un hook de PreToolUse atado al matcher Bash ve el comando exacto que el agente está a punto de correr antes de que corra. Si el comando intenta un git push a main, el hook puede devolver un bloqueo con una razón, sin que el modelo tenga que entender ni respetar una instrucción en texto plano.

#!/usr/bin/env bash
input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command // empty')
if [[ "$cmd" == *"push"* && "$cmd" == *"main"* ]]; then
  echo '{"decision":"block","reason":"push a main requiere revision humana"}'
  exit 0
fi
echo '{"decision":"approve"}'

Si el agente intenta git push origin main, el hook imprime {"decision":"block","reason":"push a main requiere revision humana"} y Claude Code cancela el comando sin ejecutarlo; para cualquier otro comando, imprime {"decision":"approve"} y la ejecución sigue normal.

sequenceDiagram
participant Agente
participant Hook as Hook PreToolUse
participant Repo as Repositorio
Agente->>Hook: intenta "git push origin main"
Hook-->>Agente: decision block, razon
Agente->>Repo: push cancelado

💭 Clave: El post original lo resume de forma directa: un agente lee una regla escrita en texto y después hace lo que quiere. Por eso las reglas que importan van en código (permisos y hooks), no en una instrucción de párrafo dentro del spec.

Superlite: un caso concreto de agente autónomo de código

Superlite es el plugin de Claude Code que contextfirst.blog construyó para resolver justamente esos cinco cuellos de botella. En vez de pedir aprobación por sección, agrupa las preguntas en un solo lote de hasta cuatro, según el tamaño del pedido: un typo se corrige directo, sin documento de diseño; un cambio a un flujo existente recibe un diseño corto en el chat; un proyecto nuevo recibe un documento único de diseño y plan que el usuario aprueba una sola vez.

Después de esa aprobación única, Superlite solo vuelve a preguntar ante algo destructivo, visible hacia afuera o sensible en seguridad: no va a hacer push a main mientras el usuario está almorzando, pero sí va a hacer todo lo demás sin interrupción.

La pieza central es el plan: en vez de una lista de pasos, Superlite genera un grafo de tareas. Cada tarea declara qué archivos posee, qué interfaces consume y produce, y qué tests tiene que pasar. Las tareas que no comparten archivos ni dependen entre sí corren al mismo tiempo; el ancho del grafo decide cuántos agentes trabajan en paralelo en un momento dado.

Cada decisión que normalmente generaría una pregunta queda registrada como una resolución (ruling): qué se decidió, por qué y qué pasa si estuvo mal. Eso es lo que permite que los agentes de IA autónomos avancen sin supervisión constante sin perder trazabilidad: el usuario vuelve al final y sabe exactamente qué decisión revisar primero, en vez de reconstruir el razonamiento desde cero.

flowchart TD
subgraph Secuencial["Un agente, un paso a la vez"]
A1["Tarea 1"] --> P1["Aprobacion humana"]
P1 --> A2["Tarea 2"]
A2 --> P2["Aprobacion humana"]
P2 --> A3["Tarea 3"]
end
subgraph Paralelo["Varios agentes a la vez"]
B1["Tarea 1"] --> R["Revision automatica"]
B2["Tarea 2"] --> R
B3["Tarea 3"] --> R
end

El grafo de tareas de Superlite decide cuántos agentes corren a la vez, según contextfirst.blog.

Cómo empezar: configurar permisos y hooks en Claude Code

Dependencias antes de empezar: Claude Code instalado, un proyecto con carpeta .claude/ en la raíz, y jq disponible para parsear el JSON dentro del hook (en Linux y macOS casi siempre ya está o se instala con el gestor de paquetes del sistema; en Windows, sin WSL, el mismo hook se escribe en PowerShell con ConvertFrom-Json en una línea).

Primero, crear o editar .claude/settings.json en la raíz del proyecto con reglas de permisos:

{
  "permissions": {
    "allow": ["Bash(npm test:*)", "Bash(git commit:*)"],
    "ask": ["Bash(git push:*)"],
    "deny": ["Bash(rm -rf:*)"]
  }
}

Con esto, Claude Code corre tests y commits sin preguntar, pide confirmación antes de cualquier push y nunca va a ejecutar un rm -rf, sin importar cómo se lo pidan.

Segundo, crear el hook en .claude/hooks/guard-push.sh con el script mostrado en la sección anterior, y darle permiso de ejecución con chmod +x .claude/hooks/guard-push.sh.

Tercero, registrar el hook en el mismo settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{"type": "command", "command": ".claude/hooks/guard-push.sh"}]
      }
    ]
  }
}

Para confirmar que la regla de permisos está activa, corré /permissions dentro de una sesión de Claude Code: lista cada patrón (allow, ask o deny) junto con la herramienta a la que aplica. Para el hook, el chequeo real es pedirle al agente que intente git push origin main: si la configuración está bien, el comando se cancela y aparece la razón push a main requiere revision humana en la salida, en vez de ejecutarse.

Casos de uso reales

Una feature nueva y acotada (un endpoint, un formulario, una migración de datos) es el caso de uso más directo: el usuario aprueba un plan una sola vez y vuelve horas después a código probado, en vez de haber aprobado veinte decisiones chicas una por una.

Un refactor grande que toca muchos archivos se beneficia del grafo de tareas: si el refactor se puede partir en módulos que no se pisan entre sí (por ejemplo, migrar cada ruta de una API de un framework a otro), varios agentes trabajan en paralelo en vez de uno detrás del otro.

Una corrección de bug puntual sigue el camino corto: Superlite detecta que es un cambio chico y lo corrige directo, sin generar un documento de diseño para un typo. El tamaño de la respuesta se ajusta al tamaño del pedido, no al revés.

El caso donde este enfoque no conviene es el opuesto: cuando el usuario todavía no sabe bien qué quiere construir y necesita iterar el diseño en vivo, sección por sección. Ahí el flujo colaborativo (el de Superpowers, con un humano cerca de cada paso) sigue siendo la herramienta correcta.

Comparativa con alternativas

Ninguno de los tres enfoques siguientes es universalmente mejor: la decisión depende de si el usuario ya tiene el diseño resuelto en la cabeza o todavía lo está construyendo junto con el agente.
OpciónCuándo usarlaVentajaLimitaciónAprobación manual en cada pasoDiseño todavía incierto, se decide sobre la marchaControl total, cero sorpresas8 a 12 pausas por feature, no escala a tareas grandesSuperpowers (flujo colaborativo)El usuario quiere revisar spec, plan y ejecución por separadoMáxima trazabilidad y seguridadEjecución secuencial, lenta para specs ya cerradosSuperlite (spec a ejecución autónoma)El spec ya está definido y solo falta construirloUna aprobación, tareas en paralelo, registro de decisionesExige reglas de permisos y hooks bien escritas de antemano

Errores comunes y buenas prácticas

El error más frecuente es activar bypassPermissions sin escribir reglas de deny. El modo asume que todo lo que no está prohibido está permitido, así que un agente con ese modo y una lista de deny vacía puede ejecutar cualquier comando, incluido uno destructivo.

El segundo es confundir una instrucción en el spec ("nunca borres archivos de producción") con una regla real. Esa frase vive en el contexto que el modelo lee. Un cambio de contexto, una instrucción contradictoria más adelante o simplemente una mala interpretación puede hacer que el agente la pase por alto. La regla necesita vivir en código: en settings.json o en un hook, donde se evalúa siempre, sin depender de que el modelo la recuerde.

El tercero, documentado en el propio post de Superlite, es correr Superpowers y Superlite en la misma sesión: ambos inyectan contexto al iniciar la sesión y comparten nombres de skill, así que terminan contradiciéndose. Se elige uno por sesión, no los dos.

⚠️ Ojo: un hook que siempre responde {"decision":"approve"} sin leer el comando no protege nada. Es una ilusión de control. El hook tiene que inspeccionar el tool_input real antes de decidir.

La práctica que mejor funciona es separar las reglas en dos capas: permisos para lo previsible (qué comandos son siempre seguros o siempre peligrosos) y hooks para lo que depende del contenido exacto del comando (a qué rama se hace push, qué archivo se borra). Las dos capas se prueban por separado, antes de confiar en ellas con un spec grande.

Profundizando: el grafo de tareas y el registro de decisiones

Por dentro, el planificador de Superlite no reparte tareas al azar: construye un grafo dirigido donde cada nodo es una tarea con tres propiedades explícitas: los archivos que posee, las interfaces que consume de otras tareas y los tests que tiene que pasar para considerarse terminada. Dos tareas sin superposición de archivos ni dependencias de interfaz quedan en la misma capa del grafo y se disparan juntas.

Esto es distinto de simplemente decirle a varios agentes que trabajen en paralelo sin más: sin la restricción de archivos, dos agentes que tocan el mismo módulo generan conflictos de merge que nadie revisó. El grafo evita el conflicto antes de que ocurra, no lo arregla después.

La revisión automática funciona igual para cada tarea terminada: un segundo agente (no necesariamente el mismo modelo) corre los tests declarados y compara el resultado contra la interfaz prometida. Si falla, se genera una tarea de corrección que vuelve a pasar por el mismo chequeo, sin despertar al usuario, salvo que el chequeo falle repetidamente.

Y cuando el proceso sí necesita al usuario, no lo hace con una pregunta suelta: le entrega la lista completa de resoluciones tomadas durante la ejecución, cada una con su justificación y su costo si resultó ser la decisión equivocada. Así es como los agentes de IA autónomos logran avanzar horas sin intervención y, al mismo tiempo, dejan un rastro auditable.

📖 Resumen en Telegram: Ver resumen

Tu próximo paso: cloná un repo de prueba, agregá el hook guard-push.sh de este artículo a .claude/hooks/ y pedile a Claude Code que intente un git push origin main para ver el bloqueo en acción.

Preguntas frecuentes

¿Superlite reemplaza a Superpowers?

No. Superpowers prioriza mantener a un humano cerca de cada paso y Superlite prioriza la velocidad cuando el spec ya está cerrado. Comparten base de código, pero contextfirst.blog recomienda no activar los dos en la misma sesión porque sus skills se pisan.

¿Los hooks pueden bloquear cualquier acción de un agente autónomo de código?

Sí, cualquier acción que pase por un evento con hook registrado, como PreToolUse para herramientas o SessionStart al abrir la sesión. Lo que el hook no intercepta (un evento sin matcher configurado) sigue las reglas normales de permisos.

¿Qué pasa si el agente intenta hacer push a main con la configuración del artículo?

El hook guard-push.sh detecta "push" y "main" en el comando, devuelve {"decision":"block"} con la razón, y Claude Code cancela el comando sin ejecutarlo en el repositorio.

¿Cuántas aprobaciones humanas necesita un build con Superlite?

Una, al aprobar el diseño y el plan. Después de eso, según el post original, solo vuelve a preguntar ante acciones destructivas, visibles hacia afuera o sensibles en seguridad.

¿Los permisos de Claude Code se pueden combinar con hooks?

Sí, y es la combinación recomendada: los permisos cubren reglas previsibles por patrón de comando, y los hooks cubren decisiones que dependen del contenido exacto de ese comando, como a qué rama apunta un push.

¿La IA agéntica autónoma funciona con modelos distintos a Claude?

El mecanismo (permisos declarativos más hooks en código) es específico de Claude Code. Otros entornos agénticos resuelven el mismo problema con sus propios sistemas de políticas, pero el principio de reglas en código, no en texto del prompt, aplica igual.

Referencias

• Contextfirst.blog: el post original donde se presenta Superlite, sus benchmarks y el diseño del plugin.- GitHub: anthropics/claude-code: repositorio oficial de Claude Code, con la documentación de hooks y permisos.- Claude Docs: documentación oficial de Anthropic sobre Claude Code y su configuración.- Wikipedia: Software agent: definición general del concepto de agente de software.

📱 ¿Te gusta este contenido? Únete a nuestro canal de Telegram @programacion donde publicamos a diario lo más relevante de tecnología, IA y desarrollo. Resúmenes rápidos, contenido fresco todos los días.