Archyl Harness

Los agentes de codificación conocen tu repositorio a la perfección — y tu arquitectura nada en absoluto. Reescriben un servicio que otro agente está refactorizando en ese mismo momento, introducen la dependencia que tu equipo prohibió en un ADR hace dos años y dejan tu documentación describiendo un sistema que ya no existe.

Archyl Harness resuelve esto. Envuelve a cualquier agente de codificación — Claude Code, Codex, Cursor, tu bot de CI o los propios agentes gestionados de Archyl — en un ciclo controlado que se apoya en tu arquitectura documentada:

El ciclo que ejecuta un agente:

plan_work ──▶ start_work_session ──▶ code (Guard watches every write)
                                          │
finish_work_session ◀─── heartbeat ◀──────┘
      │
      ├─▶ leases released
      ├─▶ outcome pinned to the touched elements (memory)
      └─▶ draft Architecture Change Request (optional)

Y como cada sesión toma reservas consultivas (leases) sobre los elementos C4 que toca, dos agentes que trabajan en el mismo servicio se ven entre sí antes de chocar — en sus briefings y en directo sobre tu diagrama.

Opcional por diseño

El harness se activa solo si tú quieres: nada se enciende por el hecho de haber documentado una arquitectura. Un agente entra en el ciclo únicamente si haces una de estas tres cosas: conectar el servidor MCP con ?profile=coding, instalar la skill archyl-harness que enseña el protocolo, o añadir el hook Guard. Deshazlas y los agentes de ese repositorio se comportarán exactamente como antes.

Todo lo demás en Archyl funciona sin él. La recuperación de contexto, el análisis de impacto, la propiedad de los elementos, las comprobaciones de conformidad, la detección de deriva y el sistema de memoria son accesibles desde el catálogo completo, sin ninguna sesión de trabajo. Usar Archyl como una arquitectura documentada que tus agentes pueden leer — y saltarte esta guía por completo — es una forma perfectamente prevista de usarlo.

Las dos mitades se adoptan por separado porque no tienen los mismos permisos. Un registro obtiene su autoridad de la curación humana: un ADR, una regla de conformidad o una solicitud de cambio aprobada llevan un estado porque una persona los puso ahí, y una entrada equivocada se queda ahí en silencio hasta que alguien la lee y la corrige. Un protocolo, en cambio, emite instrucciones sobre las que los agentes actúan: es un riesgo de otra naturaleza, que merece una decisión deliberada y no un valor por defecto.

Esa línea también está trazada dentro del producto, no solo a su alrededor. Los agentes pueden leer el registro y escribir en él, pero lo que escriben vuelve a los siguientes agentes como contexto fechado y atribuido, nunca como una regla. Solo los ADR y las reglas de conformidad se presentan como vinculantes, y el único camino desde algo que un agente registró hasta ese estatus pasa por una persona: un ADR, o una solicitud de cambio de arquitectura que alguien haya aprobado.

Configuración en cinco minutos

Necesitas un proyecto de Archyl con la arquitectura documentada (ejecuta primero el descubrimiento con IA si el tuyo está vacío) y una clave API con el alcance write, creada desde Perfil → Claves API.

Opción A — un solo comando

Desde la raíz de tu repositorio:

curl -fsSL https://raw.githubusercontent.com/archyl-com/agent-skills/main/templates/setup.sh | bash

El script te pide tu clave API y tu proyecto, y después configura todo lo que sigue. Listo — salta directamente a Tu primera sesión.

Opción B — paso a paso

1. Conecta el servidor MCP con el perfil coding. En tu repositorio, crea o amplía .mcp.json:

{
  "mcpServers": {
    "archyl": {
      "type": "http",
      "url": "https://api.archyl.com/mcp?profile=coding",
      "headers": { "X-API-Key": "${ARCHYL_API_KEY}" }
    }
  }
}

?profile=coding importa: reduce la superficie de 189 herramientas a las 16 que necesita un agente de codificación, lo que mantiene su contexto pequeño y sus decisiones evidentes.

2. Instala el plugin (Claude Code):

/plugin marketplace add archyl-com/agent-skills
/plugin install archyl-developer@archyl-marketplace

Esto instala las skills (incluida archyl-harness, que enseña el protocolo de sesión a tu agente) y el hook Guard.

3. Activa el Guard. Exporta dos variables allí donde se ejecute tu agente:

export ARCHYL_API_KEY=arch_...
export ARCHYL_PROJECT_ID=<your project uuid>

Eso es todo lo que necesita el Guard. Es fail-open: sin estas variables (o sin red) no hace nada, así que nunca puede romper tu flujo de trabajo.

Tu primera sesión

Pide a tu agente cualquier cambio — por ejemplo, "añade limitación de peticiones a la API pública". Con el harness instalado, esto es lo que ocurre:

Antes de programar, el agente declara el trabajo:

▶ start_work_session(task: "add rate limiting to the public API",
                     agentName: "claude-code/vincent")

# Harness Session
- Session ID: 4c2e…
- Gate: warn
  - error-level guardrail applies: no-direct-db-from-handlers
- Leased elements: container `ApiGateway`, component `RateLimiter`
- Conflicts: none

## Most relevant elements
- ApiGateway (container) — handles all public traffic …
## Related decisions (respect these)
- ADR-017: All throttling is enforced at the gateway [accepted]
## What previous sessions did here
- ApiGateway (claude-code/sarah, 3 days ago): extracted auth middleware …

Ahora el agente sabe dónde trabajar, qué decisiones lo restringen y qué hizo allí el último agente — sin leer todo tu repositorio.

Mientras programa, el Guard comprueba cada archivo que el agente está a punto de escribir contra tus reglas de conformidad. Una violación crítica bloquea la escritura mostrando la regla y su sugerencia; el agente se ajusta y continúa.

Al terminar, el agente cierra el ciclo:

▶ finish_work_session(sessionId: "4c2e…",
    summary: "Added token-bucket rate limiting in ApiGateway middleware",
    decisions: ["limits configured per-plan in Redis"],
    createChangeRequest: true)

Las reservas se liberan, el resumen queda fijado como memoria en ApiGateway para el siguiente agente, y un borrador de solicitud de cambio de arquitectura llega a Archyl para que una persona revise cómo debe actualizarse el modelo C4.

Cada decisión se guarda como una memoria propia: una sesión posterior puede reemplazarla, reconfirmarla o dejar que caduque sin tocar nada más de lo que dejó tu sesión. Las decisiones vuelven a los siguientes agentes como contexto fechado y atribuido, nunca como reglas. A un agente solo se le presentan como vinculantes los ADR y las reglas de conformidad, y la solicitud de cambio es la vía por la que una decisión alcanza ese estatus.

Vigilar a tus agentes: la consola Fleet

Abre Agent Hub → Fleet para ver el trabajo en curso: cuántos agentes están trabajando, qué elementos C4 están reservados ahora mismo, y una tarjeta por sesión activa con su tarea, los elementos que retiene, su gate y la frescura de su heartbeat. Las sesiones terminadas pasan a Sesiones recientes con el resumen que cada una reportó.

Una sesión cuyo heartbeat se detiene queda señalada, y expira sola 30 minutos después. También puedes cancelarla desde aquí, lo que libera sus reservas de inmediato.

La misma información te llega donde realmente miras — en el diagrama. Todo elemento que un agente retiene lleva una insignia con su nombre, y hacer clic en ella equivale a preguntarle qué está haciendo: la tarea declarada, todo lo demás que retiene, y hace cuánto dio señales de vida.

Para los agentes gestionados de Archyl también puedes dirigir un agente en ejecución: escribe un mensaje en la página de ejecución y se inyecta en su siguiente paso de razonamiento.

El gate

Cada sesión arranca con un veredicto de preflight:

Usa exclusive: true para cambios que no deben competir con nadie: migraciones de esquema, cambios de contrato.

Configuración del Guard

En lugar de variables de entorno, un archivo .archyl.json versionable en la raíz del repositorio puede llevar la mitad no secreta: { "apiUrl": "…", "projectId": "…" }. Guarda la clave API en el entorno.

Memoria

Los resultados de sesión son solo la mitad automática de la memoria. Los agentes y tus compañeros también pueden escribir memoria de forma deliberada:

▶ remember(projectId: …, element: "ApiGateway", kind: "pitfall",
    content: "The gateway strips custom headers longer than 8KB — payloads must go in the body.")

• remember fija un hecho en un elemento (o en todo el proyecto), tipado como note, convention o pitfall. Úsalo para el conocimiento que no se ve ni en el código ni en el modelo: rarezas del despliegue, razones históricas, puntos frágiles.
• recall busca en toda la memoria — resultados, notas, convenciones, trampas — por términos, por elemento o por tipo. El ranking mezcla el significado con las palabras, así que un agente que pregunta por "rate limiting" encuentra la nota que otra persona escribió sobre "throttling". Pasa tu sessionId para que las memorias que se te sirvieron puedan acreditarse después.
• find_relevant_context y start_work_session sirven automáticamente las memorias más recientes de los elementos afectados, así el siguiente agente arranca con lo que aprendieron los anteriores.

Escribir una memoria está deduplicado: reafirmar un hecho que ya existe no guarda una segunda copia, sino que confirma la que ya está ahí (la respuesta indica deduplicated: true), porque un agente que reafirma lo que ha aprendido aporta evidencia, no ruido. Una memoria parecida pero no idéntica sí se guarda y se devuelve en similarTo, para que quien la escribe sustituya a conciencia en lugar de contradecir en silencio.

La memoria también aprende del uso. Cuando una sesión termina, usedMemories nombra las memorias en las que realmente se apoyó. Esa cita es la señal fuerte: las memorias citadas conservan su posición, mientras que una memoria servida a cinco sesiones y no nombrada por ninguna de ellas se degrada como ruido. Nada se borra automáticamente: las memorias ignoradas aparecen en una cola de revisión para que las juzgue una persona.

La memoria tiene un ciclo de vida, para que siga siendo cierta en lugar de acumularse. Cuando una memoria servida por recall resulta acertada, vuelve a darla por buena con confirm_memory: su reloj de frescura se reinicia y sigue pesando más que la información más antigua. Cuando un hecho cambia, no dejes vivas las dos versiones: remember(supersedes: "Old title") sustituye la memoria antigua, que sale de la recuperación pero permanece en el historial y en el grafo. Todo lo que no se confirma decae suavemente en el ranking (vida media de 45 días), y para un agente que está a punto de tocar código las trampas siempre pesan más que las notas simples.

Las memorias forman un grafo de conocimiento, al estilo de Obsidian. Dale un title a una memoria y pasa a ser direccionable: cualquier otra memoria puede referenciarla con [[Title]] en su contenido. Los enlaces también resuelven elementos C4 por su nombre ([[ApiGateway]]) y decisiones ([[ADR-17]]) — y un enlace a un título que aún no existe queda pendiente y se engancha en cuanto se crea esa memoria. Cada memoria expone sus backlinks, así que el conocimiento se recorre en ambos sentidos — y recall sigue los enlaces: los mejores resultados arrastran consigo a sus vecinos enlazados con wiki-enlaces, marcados con via.

La memoria también nota cuando la arquitectura se mueve debajo de ella. Cuando cambia un elemento al que una memoria está anclada, esa memoria se marca para revisión: recall la sigue sirviendo, pero señalada con [VERIFY — the element drifted since this was written], y baja en el ranking en lugar de desaparecer. Un hecho escrito sobre un servicio que desde entonces se ha dividido no es automáticamente falso — simplemente deja de ser fiable sin una mirada humana.

La memoria está cifrada en reposo como toda columna de contenido sensible, y se gestiona desde la interfaz: el panel de Memoria en el Agent Hub, más una sección por elemento en el panel de detalles del diagrama. El panel está hecho para triar — la columna izquierda cuenta lo que necesita revisión, lo que se está ignorando y lo que ha envejecido, luego reparte el resto por tipo, y cada fila lleva un borde de color que indica de un vistazo cuánto fiarse.

Cambia al mapa de conocimiento para la otra pregunta: no qué sabemos sino dónde. Una celda por elemento C4, mostrando qué sabe el proyecto sobre él y cuán fresco es ese saber — incluidos los elementos sobre los que nadie ha escrito nada, que suele ser la mitad más útil del cuadro.

En CI

Los mismos bloques se ejecutan en tu pipeline con las GitHub Actions: generate-context hace commit de un briefing archyl.txt para agentes sin acceso MCP, conformance-check condiciona las pull requests al cumplimiento de tus reglas, y auto-cr crea solicitudes de cambio de arquitectura a partir de los cambios fusionados.

Resolución de problemas

No aparece ninguna sesión en la consola Fleet. El agente está conectado sin el protocolo del harness. Comprueba que el plugin esté instalado (la skill archyl-harness enseña el protocolo) y que la URL de MCP incluya ?profile=coding — con el catálogo completo de 189 herramientas, los agentes suelen explorar en vez de seguir el ciclo.

El Guard nunca bloquea nada. Es intencionado: falla en abierto. Verifica que ARCHYL_API_KEY y ARCHYL_PROJECT_ID estén exportadas en el entorno donde se ejecuta el agente, y que tu proyecto tenga reglas de conformidad con severidad critical.

Una sesión se queda atascada como activa. Las sesiones expiran 30 minutos después de su último heartbeat y liberan sus reservas automáticamente. Para liberarlas de inmediato, cancela la sesión desde la consola Fleet.

¿Qué agentes son compatibles? Todo lo que hable MCP obtiene Context, Plan y el protocolo de sesión. El hook Guard y las skills apuntan hoy a Claude Code; otros agentes pueden aplicar las mismas reglas mediante run_conformance_check o las actions de CI.