Archyl Harness

Gli agenti di programmazione conoscono perfettamente il tuo repository — e per niente la tua architettura. Riscrivono un servizio che un altro agente sta rifattorizzando nello stesso momento, introducono la dipendenza che il tuo team ha vietato in un ADR due anni fa e lasciano la documentazione a descrivere un sistema che non esiste più.

Archyl Harness risolve questo problema. Avvolge qualsiasi agente di programmazione — Claude Code, Codex, Cursor, il tuo bot di CI o gli agenti gestiti di Archyl — in un ciclo governato, costruito sulla tua architettura documentata:

Il ciclo che un agente esegue:

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)

E poiché ogni sessione acquisisce lease consultivi sugli elementi C4 che tocca, due agenti che lavorano sullo stesso servizio si vedono a vicenda prima di entrare in collisione — nei loro briefing e in tempo reale sul tuo diagramma.

Opzionale per scelta

L'harness si attiva solo se lo vuoi: nulla si accende per il fatto di aver documentato un'architettura. Un agente entra nel ciclo soltanto se fai una di queste tre cose: collegare il server MCP con ?profile=coding, installare la skill archyl-harness che insegna il protocollo, o aggiungere l'hook Guard. Annullale e gli agenti di quel repository si comporteranno esattamente come prima.

Tutto il resto di Archyl funziona senza. Recupero del contesto, analisi d'impatto, ownership, controlli di conformità, rilevamento della deriva e sistema di memoria sono tutti raggiungibili dal catalogo completo, senza alcuna sessione di lavoro. Usare Archyl come un'architettura documentata che i tuoi agenti possono leggere — saltando del tutto questa guida — è un modo perfettamente previsto di usarlo.

Le due metà si adottano separatamente perché non hanno gli stessi permessi. Un registro trae la propria autorità dalla curatela umana: un ADR, una regola di conformità, una richiesta di modifica approvata portano ciascuno uno stato perché una persona ce li ha messi, e una voce sbagliata resta lì in silenzio finché qualcuno non la legge e la corregge. Un protocollo, invece, emette istruzioni su cui gli agenti agiscono: è un rischio di natura diversa, che merita una decisione deliberata anziché un valore predefinito.

Quella linea è tracciata anche dentro il prodotto, non solo attorno. Gli agenti possono leggere il registro e scriverci, ma ciò che scrivono torna agli agenti successivi come contesto datato e attribuito, mai come regola. Solo gli ADR e le regole di conformità vengono presentati come vincolanti, e l'unica strada che porta ciò che un agente ha registrato fino a quello stato passa da una persona: un ADR, o una richiesta di modifica architetturale approvata da qualcuno.

Configurazione in cinque minuti

Ti serve un progetto Archyl con un'architettura documentata (esegui prima la scoperta potenziata dall'AI se il tuo è vuoto) e una chiave API con ambito write, creata da Profilo → Chiavi API.

Opzione A — un solo comando

Dalla radice del tuo repository:

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

Lo script chiede la chiave API e il progetto, poi configura tutto quello che segue. Fatto — salta direttamente a La tua prima sessione.

Opzione B — passo dopo passo

1. Collega il server MCP con il profilo coding. Nel tuo repository, crea o estendi .mcp.json:

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

?profile=coding è importante: riduce la superficie da 189 strumenti ai 16 di cui un agente di programmazione ha bisogno, mantenendo piccolo il suo contesto e ovvie le sue scelte.

2. Installa il plugin (Claude Code):

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

Questo installa le skill (inclusa archyl-harness, che insegna al tuo agente il protocollo di sessione) e l'hook Guard.

3. Attiva il Guard. Esporta due variabili dove viene eseguito il tuo agente:

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

È tutto ciò di cui il Guard ha bisogno. È fail-open: senza queste variabili (o senza rete) non fa nulla, quindi non può mai bloccare il tuo flusso di lavoro.

La tua prima sessione

Chiedi al tuo agente una modifica qualsiasi — per esempio, "aggiungi il rate limiting all'API pubblica". Con l'harness installato, ecco cosa succede:

Prima di scrivere codice, l'agente dichiara il lavoro:

▶ 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 …

Ora l'agente sa dove lavorare, quali decisioni lo vincolano e cosa ha fatto lì l'ultimo agente — senza leggere l'intero repository.

Durante la scrittura del codice, il Guard verifica ogni file che l'agente sta per scrivere rispetto alle tue regole di conformità. Una violazione critica blocca la scrittura mostrando la regola e il suo suggerimento; l'agente si adegua e prosegue.

Al termine, l'agente chiude il ciclo:

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

I lease vengono rilasciati, il riepilogo viene fissato come memoria su ApiGateway per l'agente successivo e una bozza di richiesta di modifica architetturale arriva in Archyl perché una persona valuti come aggiornare il modello C4.

Ogni decisione viene registrata come memoria a sé: una sessione successiva può sostituirla, riconfermarla o lasciarla decadere senza toccare il resto di ciò che la tua sessione ha lasciato. Le decisioni tornano agli agenti futuri come contesto datato e attribuito, mai come regole. A un agente vengono presentati come vincolanti solo gli ADR e le regole di conformità, ed è tramite la richiesta di modifica che una decisione ottiene quello status.

Tenere d'occhio i tuoi agenti: la console Fleet

Apri Agent Hub → Fleet per vedere il lavoro in corso: quanti agenti sono all'opera, quali elementi C4 sono attualmente sotto lease, e una scheda per ogni sessione attiva con il suo task, gli elementi che detiene, il suo gate e la freschezza del suo heartbeat. Le sessioni concluse finiscono in Sessioni recenti con il riepilogo che ciascuna ha riportato.

Una sessione il cui heartbeat si ferma viene segnalata, e scade da sola 30 minuti dopo. Puoi anche annullarla da qui, liberando immediatamente i suoi lease.

La stessa informazione ti raggiunge dove guardi davvero — sul diagramma. Ogni elemento che un agente detiene porta un badge con il suo nome, e cliccarlo equivale a chiedergli cosa sta facendo: il task dichiarato, tutto ciò che detiene inoltre, e da quanto tempo si è fatto vivo.

Per gli agenti gestiti di Archyl puoi anche guidare un agente in esecuzione: scrivi un messaggio nella pagina di esecuzione e viene iniettato nel suo prossimo passo di ragionamento.

Il gate

Ogni sessione inizia con un verdetto di preflight:

Usa exclusive: true per le modifiche che non devono competere con nessuno: migrazioni di schema, modifiche ai contratti.

Configurazione del Guard

In alternativa alle variabili d'ambiente, un file .archyl.json versionabile nella radice del repository può contenere la metà non segreta: { "apiUrl": "…", "projectId": "…" }. Tieni la chiave API nell'ambiente.

Memoria

I risultati delle sessioni sono solo la metà automatica della memoria. Agenti e colleghi possono anche scrivere in memoria deliberatamente:

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

• remember fissa un fatto su un elemento (o sull'intero progetto), tipizzato come note, convention o pitfall. Usalo per la conoscenza che non è visibile né nel codice né nel modello: stranezze del deployment, ragioni storiche, punti fragili.
• recall cerca in tutta la memoria — risultati, note, convenzioni, trappole — per termini, per elemento o per tipo. Il ranking unisce il significato alle parole: un agente che chiede del "rate limiting" trova così la nota che qualcun altro aveva scritto sul "throttling". Passa il tuo sessionId, così le memorie che ti sono state servite potranno essere accreditate in seguito.
• find_relevant_context e start_work_session servono automaticamente le memorie più recenti degli elementi coinvolti, così l'agente successivo parte da ciò che hanno imparato i precedenti.

Scrivere una memoria è deduplicato: ribadire un fatto che esiste già non ne salva una seconda copia, ma conferma quella esistente (la risposta riporta deduplicated: true) — perché un agente che riafferma ciò che ha imparato porta una prova, non rumore. Una memoria simile ma non identica viene invece salvata e segnalata in similarTo, così chi la scrive sostituisce deliberatamente invece di contraddire in silenzio.

La memoria impara anche dall'uso. Quando una sessione si chiude, usedMemories nomina le memorie su cui si è davvero appoggiata. Quella citazione è il segnale forte: le memorie citate mantengono il loro peso, mentre una memoria servita a cinque sessioni e mai nominata da nessuna di esse viene retrocessa come rumore. Niente viene cancellato automaticamente — le memorie ignorate finiscono in una coda di revisione, dove è una persona a giudicare.

La memoria ha un ciclo di vita, così resta vera invece di accumularsi. Quando una memoria servita da recall si rivela accurata, riconfermala con confirm_memory: il suo orologio di freschezza riparte e continua a pesare più delle informazioni più vecchie. Quando un fatto cambia, non lasciare vive entrambe le versioni: remember(supersedes: "Old title") sostituisce la vecchia memoria, che esce dal recupero ma resta nella cronologia e nel grafo. Tutto ciò che non viene confermato decade dolcemente nel ranking (emivita di 45 giorni), e per un agente che sta per toccare il codice le trappole pesano sempre più delle semplici note.

Le memorie formano un grafo di conoscenza, in stile Obsidian. Dai un title a una memoria e diventa indirizzabile: qualsiasi altra memoria può richiamarla con [[Title]] nel proprio contenuto. I link risolvono anche gli elementi C4 per nome ([[ApiGateway]]) e le decisioni ([[ADR-17]]) — e un link a un titolo che ancora non esiste resta in sospeso e si aggancia nel momento in cui quella memoria viene creata. Ogni memoria espone i suoi backlink, così la conoscenza è navigabile in entrambe le direzioni — e recall segue i link: i risultati migliori si portano dietro i vicini collegati dai wiki-link, contrassegnati con via.

La memoria si accorge anche quando l'architettura si muove sotto di lei. Quando un elemento a cui una memoria è appuntata cambia, quella memoria viene segnalata per revisione: recall continua a servirla, ma marcata [VERIFY — the element drifted since this was written], e scende in classifica invece di sparire. Un fatto scritto su un servizio da allora suddiviso non è automaticamente falso — smette solo di essere affidabile senza uno sguardo umano.

La memoria è cifrata a riposo come ogni colonna di contenuto sensibile, e si gestisce dall'interfaccia: il pannello Memoria nell'Agent Hub, più una sezione per elemento nel pannello dei dettagli del diagramma. Il pannello è fatto per il triage — la colonna di sinistra conta ciò che va rivisto, ciò che viene ignorato e ciò che è invecchiato, poi divide il resto per tipo, e ogni riga porta un bordo colorato che dice a colpo d'occhio quanto fidarsi.

Passa alla mappa della conoscenza per l'altra domanda: non cosa sappiamo ma dove. Una cella per elemento C4, che mostra cosa il progetto ne sa e quanto è fresco quel sapere — inclusi gli elementi su cui nessuno ha scritto nulla, che di solito è la metà più utile del quadro.

In CI

Gli stessi blocchi girano nella tua pipeline con le GitHub Actions: generate-context committa un briefing archyl.txt per gli agenti senza accesso MCP, conformance-check subordina le pull request alle tue regole e auto-cr apre richieste di modifica architetturale a partire dalle modifiche mergiate.

Risoluzione dei problemi

Nella console Fleet non compare nessuna sessione. L'agente è connesso senza il protocollo dell'harness. Verifica che il plugin sia installato (la skill archyl-harness insegna il protocollo) e che l'URL MCP includa ?profile=coding — con il catalogo completo di 189 strumenti, gli agenti tendono a esplorare invece di seguire il ciclo.

Il Guard non blocca mai nulla. È voluto: è fail-open. Verifica che ARCHYL_API_KEY e ARCHYL_PROJECT_ID siano esportate nell'ambiente in cui gira l'agente e che il tuo progetto abbia regole di conformità con severità critical.

Una sessione resta bloccata su attiva. Le sessioni scadono 30 minuti dopo l'ultimo heartbeat e rilasciano automaticamente i loro lease. Per liberarli subito, annulla la sessione dalla console Fleet.

Quali agenti sono supportati? Tutto ciò che parla MCP ottiene Context, Plan e il protocollo di sessione. L'hook Guard e le skill al momento riguardano Claude Code; altri agenti possono applicare le stesse regole tramite run_conformance_check o le action di CI.