CubeLabs

1. El problema que resuelve Paperclip

Un agente aislado puede completar una tarea; una operación con varios agentes necesita saber qué objetivo persigue cada tarea, quién puede delegar, cuánto puede gastar y qué evidencia debe producir. Paperclip no es otro framework para escribir prompts: es el plano de control que se sitúa por encima de Claude Code, Codex, OpenClaw, agentes CLI o endpoints HTTP.

Su unidad de trabajo es la incidencia trazable. La tarea conserva enlaces a compañía, proyecto, objetivo y padre; así un agente no recibe solo «escribe un artículo», sino el motivo y las restricciones de esa petición.

2. Las cuatro capas de una organización

El README organiza el producto en cuatro pilares: un gestor de tareas agéntico, un organigrama, entrenamiento/evaluación del empleado-agente y un sistema operativo que aporta runtime, MCP, aislamiento, identidad y costes. Esta separación evita confundir la estrategia con el mecanismo que ejecuta un comando.

• Trabajo: tickets, bloqueos, comentarios, adjuntos y productos.
• Organización: roles, líneas de reporte, responsabilidades y fronteras.
• Aprendizaje: skills compartidas, evaluaciones y resultados guardados.
• Infraestructura: workspaces, colas, secretos, plugins y telemetría.

Objetivo: «Publicar un informe semanal fiable»
  └─ Proyecto: Investigación de mercado
      ├─ Incidencia: recopilar fuentes
      ├─ Incidencia: contrastar cifras
      └─ Incidencia: editar y aprobar el informe

3. Instalación segura y primer entorno

Paperclip requiere Node.js 24.11 o superior y pnpm 9.15 o superior. El instalador oficial puede descargar y configurar el servicio, pero en un servidor real conviene revisar el script y usar una versión fijada cuando la política de seguridad lo requiera. Para explorar sin instalar un servicio persistente, el propio proyecto ofrece test-drive.

node --version
npm config get registry
npx --registry https://registry.npmjs.org paperclipai test-drive --no-browser
# Alternativa para desarrollo desde fuente
git clone https://github.com/paperclipai/paperclip.git
cd paperclip && pnpm install && pnpm dev

4. Objetivos, proyectos e incidencias

La regla de diseño más valiosa es que toda acción debe poder remontarse a un objetivo. Formula objetivos verificables («reducir el tiempo de respuesta a 24 h») y no órdenes ambiguas («mejorar soporte»). Después crea proyectos para los ámbitos estables e incidencias pequeñas que terminen en una evidencia: un diff, una URL, un test o una decisión.

Paperclip incluye checkout atómico y bloqueos de ejecución para que dos agentes no tomen el mismo trabajo. Modela explícitamente dependencias: la edición no empieza hasta que investigación entregue fuentes, y la publicación espera la aprobación.

5. Diseñar el organigrama de agentes

Un agente en Paperclip tiene título, rol, línea de reporte, permisos y presupuesto. El organigrama no pretende imitar burocracia humana: es una forma de limitar autoridad y hacer visible quién puede delegar. Empieza con pocos roles especializados y responsabilidades no solapadas.

Dirección editorial (humano: aprueba publicación)
├─ Investigador IA (agente: fuentes y notas)
├─ Analista (agente: cálculos y contraste)
└─ Editor (agente: borrador; no publica)

Los adaptadores permiten usar el runtime de cada empleado: Claude Code y Codex para repositorios, una CLI para tareas locales o HTTP/webhooks para bots externos. «Trae tu propio agente» significa que Paperclip coordina su trabajo; no sustituye el modelo ni el prompt especializado que ya uses.

6. Heartbeats, adaptadores y ejecución

Los heartbeats despiertan agentes programadamente o ante eventos como asignaciones y menciones. Antes de invocar al adaptador, Paperclip resuelve workspace, carga skills, inyecta solo los secretos autorizados y comprueba presupuesto. La cola respaldada por base de datos puede coalescer eventos y recuperar ejecuciones huérfanas.

El resultado de una ejecución debe incluir logs estructurados, eventos de coste, estado de sesión y evidencia de trabajo. Esa persistencia permite retomar contexto tras un reinicio en vez de iniciar cada turno desde cero.

# Ejemplo conceptual de política de heartbeat
trigger: cron "0 8 * * 1-5"
agent: investigador-ia
input: "Revisa fuentes nuevas y actualiza las incidencias abiertas"
expected_work_product: "notas con URL, fecha y nivel de confianza"

7. Presupuestos y control de costes

Paperclip atribuye tokens y costes por compañía, agente, proyecto, objetivo, incidencia, proveedor y modelo. Las políticas pueden avisar en un umbral y detener el trabajo al alcanzar el límite. Esto transforma «¿por qué subió la factura?» en una consulta trazable por actividad.

Empieza conservador: un límite mensual bajo por agente, un umbral de aviso y un trabajo de bajo riesgo. El objetivo no es gastar cero, sino detener el gasto sin resultado y preservar capacidad para las tareas valiosas.

8. Gobierno, permisos y secretos

La gobernanza define qué decisiones requieren aprobación, qué etapas de revisión hay y quién puede pausar o terminar agentes. Las configuraciones se versionan y pueden revertirse. En paralelo, los secretos se acotan por compañía y ejecución: un valor sensible solo debe aparecer cuando una tarea autorizada realmente lo necesita.

Una aprobación útil revisa un artefacto concreto. «¿Parece bien?» no basta; pide test, diff, captura, enlaces o una lista de cambios propuesta.

9. Rutinas, observabilidad y recuperación

Las rutinas admiten cron, webhook o API y crean una incidencia rastreada en cada ejecución. Las políticas de concurrencia y catch-up evitan que una rutina atrasada lance una avalancha de trabajos. La bitácora guarda mutaciones, cambios de heartbeat, decisiones, costes y productos.

Para observabilidad técnica, Paperclip ofrece instrumentación OpenTelemetry opcional al definir OTEL_EXPORTER_OTLP_ENDPOINT. También puede activar Sentry mediante sus variables dedicadas. Configura estos servicios sin incluir contenido de prompts o secretos en los datos externos de observación.

# Variables de observabilidad: establece solo en el entorno seguro
export OTEL_EXPORTER_OTLP_ENDPOINT="https://telemetria.interna/v1/traces"
# Evalúa primero qué atributos y datos salen del servidor

10. Proyecto final: un equipo editorial

Construye una organización pequeña que prepare un informe semanal sin publicar autónomamente. El resultado combina las piezas del curso sin conceder permisos irreversibles antes de medir calidad.

Evalúa tres ciclos: calidad de fuentes, coste por informe y número de intervenciones humanas. Ajusta primero roles y productos esperados; cambiar de modelo sin corregir el proceso rara vez resuelve una mala coordinación.

Preguntas frecuentes

Recursos y lista de comprobación

Antes de conectar una organización a herramientas reales, documenta el inventario de adaptadores, workspaces y secretos. La portabilidad de compañías que ofrece Paperclip no reemplaza un proceso de revisión: exporta configuraciones sin secretos, revisa colisiones de nombres y prueba la importación en un entorno aislado.

Consulta el README de Paperclip para los comandos y compatibilidades vigentes, y sus documentos de instalación, CLI y observabilidad antes de mover una prueba a producción. La licencia del repositorio es MIT; eso facilita estudiarlo y adaptarlo, pero no elimina la responsabilidad de operar con seguridad.

Guía operativa: de piloto a operación

Una implementación útil progresa por fases. En el piloto, ejecuta una única tarea con datos no sensibles y conserva el resultado. En validación, mide repetibilidad, coste y necesidad de intervención. Solo en operación conectas rutinas, adaptadores y cuentas con permisos más amplios. Cada fase tiene un criterio de salida, no una fecha arbitraria.

Contrato de una tarea bien escrita

Especifica el resultado, el contexto mínimo, las restricciones, la evidencia esperada y la condición de parada. Por ejemplo, «resume cinco fuentes publicadas desde el último informe, cita URL y fecha, marca incertidumbres y no envíes el texto a ningún canal» da al agente más dirección que «investiga novedades». El contrato reduce llamadas innecesarias y hace la aprobación más rápida.

resultado: borrador de informe en Markdown
fuentes: 5 como máximo, cada una con URL y fecha
restricciones: no publicar; no usar datos privados
evidencia: tabla de afirmaciones y fuente de respaldo
parada: si no hay dos fuentes independientes, marcar bloqueado

Revisión posterior a la ejecución

Cuando una tarea falla, no atribuyas el problema de inmediato al modelo. Comprueba primero si el objetivo era ambiguo, si el agente tenía las herramientas adecuadas, si faltaba contexto, si la evidencia era imposible de producir o si la política de aprobación llegó demasiado tarde. Ese diagnóstico permite mejorar la organización y no solo cambiar el prompt.

• Calidad: ¿la evidencia respalda cada conclusión?
• Economía: ¿el coste quedó dentro del límite y produjo un resultado reutilizable?
• Seguridad: ¿el adaptador recibió únicamente los permisos previstos?
• Continuidad: ¿otro operador podría entender y retomar la incidencia?