Archyl Harness

Coding-Agenten kennen Ihr Repository perfekt — und Ihre Architektur überhaupt nicht. Sie schreiben einen Service um, den ein anderer Agent im selben Moment refaktoriert, führen die Abhängigkeit ein, die Ihr Team vor zwei Jahren in einem ADR verboten hat, und hinterlassen eine Dokumentation, die ein System beschreibt, das es nicht mehr gibt.

Archyl Harness behebt das. Es umschließt jeden Coding-Agent — Claude Code, Codex, Cursor, Ihren CI-Bot oder Archyls eigene verwaltete Agenten — mit einer gesteuerten Schleife, die auf Ihrer dokumentierten Architektur aufsetzt:

Die Schleife, die ein Agent durchläuft:

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)

Und weil jede Session Advisory Leases auf die C4-Elemente nimmt, die sie berührt, sehen sich zwei Agenten, die am selben Service arbeiten, bevor sie kollidieren — in ihren Briefings und live in Ihrem Diagramm.

Bewusst optional

Das Harness ist opt-in: Nichts daran schaltet sich ein, nur weil Sie eine Architektur dokumentiert haben. Ein Agent betritt die Schleife erst, wenn Sie eines von drei Dingen tun — den MCP-Server mit ?profile=coding verbinden, den Skill archyl-harness installieren, der das Protokoll vermittelt, oder den Guard-Hook einrichten. Machen Sie das rückgängig, verhalten sich die Agenten in diesem Repository exakt wie zuvor.

Alles andere in Archyl funktioniert ohne das Harness. Kontextabruf, Impact-Analyse, Ownership, Conformance-Prüfungen, Drift-Erkennung und das Gedächtnissystem sind allesamt über den vollständigen Tool-Katalog erreichbar, ganz ohne Work Session. Archyl als dokumentierte Architektur zu nutzen, die Ihre Agenten lesen können — und diesen Leitfaden komplett zu überspringen — ist ein vorgesehener Weg.

Die beiden Hälften werden getrennt eingeführt, weil sie Unterschiedliches dürfen. Ein Verzeichnis bezieht seine Autorität aus menschlicher Kuratierung: Ein ADR, eine Conformance-Regel, ein genehmigter Änderungsantrag tragen jeweils einen Status, weil ein Mensch sie dort abgelegt hat — und ein falscher Eintrag liegt still, bis jemand ihn liest und korrigiert. Ein Protokoll dagegen erteilt Anweisungen, nach denen Agenten handeln. Das ist ein Risiko anderer Art und verdient eine bewusste Entscheidung statt einer Voreinstellung.

Diese Linie verläuft auch im Produkt selbst, nicht nur darum herum. Agenten dürfen das Verzeichnis lesen und hineinschreiben, aber was sie schreiben, erreicht künftige Agenten als datierter, namentlich zugeordneter Kontext — nie als Regel. Verbindlich ausgeliefert werden nur ADRs und Conformance-Regeln, und der einzige Weg von einer Agenten-Aufzeichnung zu diesem Status führt über einen Menschen: ein ADR oder ein genehmigter Architektur-Änderungsantrag.

Einrichtung in fünf Minuten

Sie brauchen ein Archyl-Projekt mit dokumentierter Architektur (führen Sie zuerst die KI-gestützte Entdeckung aus, falls Ihres leer ist) und einen API-Schlüssel mit write-Scope aus Profil → API-Schlüssel.

Option A — ein einziger Befehl

Im Wurzelverzeichnis Ihres Repositorys:

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

Das Skript fragt nach Ihrem API-Schlüssel und Ihrem Projekt und richtet dann alles Weitere ein. Fertig — springen Sie direkt zu Ihre erste Session.

Option B — Schritt für Schritt

1. Verbinden Sie den MCP-Server mit dem Coding-Profil. Legen Sie in Ihrem Repository .mcp.json an oder ergänzen Sie die Datei:

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

?profile=coding ist entscheidend: Es verkleinert die Oberfläche von 189 Tools auf die 16, die ein Coding-Agent braucht. Das hält seinen Kontext klein und seine Auswahl eindeutig.

2. Installieren Sie das Plugin (Claude Code):

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

Damit werden die Skills installiert (darunter archyl-harness, das Ihrem Agent das Session-Protokoll beibringt) sowie der Guard-Hook.

3. Aktivieren Sie den Guard. Exportieren Sie zwei Variablen dort, wo Ihr Agent läuft:

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

Mehr braucht der Guard nicht. Er arbeitet fail-open: Ohne diese Variablen (oder ohne Netzwerk) tut er nichts und kann Ihren Workflow damit nie blockieren.

Ihre erste Session

Bitten Sie Ihren Agent um eine beliebige Änderung — etwa „füge der öffentlichen API ein Rate-Limiting hinzu“. Mit installiertem Harness passiert Folgendes:

Vor dem Codieren meldet der Agent die Arbeit an:

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

Der Agent weiß jetzt, wo er arbeiten soll, welche Entscheidungen ihn einschränken und was der letzte Agent dort getan hat — ohne Ihr gesamtes Repository zu lesen.

Während des Codierens prüft der Guard jede Datei, die der Agent schreiben will, gegen Ihre Konformitätsregeln. Ein kritischer Verstoß blockiert den Schreibvorgang und nennt Regel und Lösungsvorschlag; der Agent passt sich an und macht weiter.

Zum Abschluss schließt der Agent die Schleife:

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

Die Leases werden freigegeben, die Zusammenfassung wird als Gedächtnis an ApiGateway geheftet — für den nächsten Agent — und ein Architektur-Änderungsantrag im Entwurf landet in Archyl, damit ein Mensch prüft, wie das C4-Modell aktualisiert werden soll.

Jede Entscheidung wird als eigenes Gedächtnis gespeichert: Eine spätere Sitzung kann sie ersetzen, erneut bestätigen oder verfallen lassen, ohne alles andere anzutasten, was Ihre Sitzung hinterlassen hat. Entscheidungen erreichen künftige Agents als datierter, namentlich zugeordneter Kontext — nie als Regeln. Verbindlich ausgeliefert werden einem Agent nur ADRs und Conformance-Regeln, und über den Änderungsantrag erlangt eine Entscheidung diesen Status.

Ihre Agenten beobachten: die Fleet-Konsole

Öffnen Sie Agent Hub → Fleet, um die laufende Arbeit zu sehen: wie viele Agenten arbeiten, welche C4-Elemente aktuell geleast sind, und eine Karte pro aktiver Sitzung mit ihrer Aufgabe, den gehaltenen Elementen, ihrem Gate und der Aktualität ihres Heartbeats. Beendete Sitzungen wandern in Letzte Sitzungen mit der jeweils gemeldeten Zusammenfassung.

Eine Sitzung, deren Heartbeat ausbleibt, wird markiert und läuft 30 Minuten später von selbst ab. Sie können sie hier auch abbrechen, was ihre Leases sofort freigibt.

Dieselbe Information erreicht Sie dort, wo Sie tatsächlich hinschauen — im Diagramm. Jedes Element, das ein Agent hält, trägt ein Abzeichen mit seinem Namen, und ein Klick darauf fragt den Agenten, was er tut: die deklarierte Aufgabe, alles Weitere, das er hält, und wann er sich zuletzt gemeldet hat.

Für die verwalteten Agenten von Archyl können Sie außerdem einen laufenden Agenten steuern — schreiben Sie eine Nachricht auf der Run-Seite, und sie fließt in seinen nächsten Denkschritt ein.

Das Gate

Jede Session beginnt mit einem Preflight-Urteil:

Nutzen Sie exclusive: true für Änderungen, die mit niemandem in Konkurrenz treten dürfen: Schema-Migrationen, Vertragsänderungen.

Guard-Konfiguration

Statt Umgebungsvariablen kann eine eincheckbare .archyl.json im Wurzelverzeichnis des Repositorys die nicht geheime Hälfte tragen: { "apiUrl": "…", "projectId": "…" }. Den API-Schlüssel behalten Sie in der Umgebung.

Gedächtnis

Session-Ergebnisse sind nur die automatische Hälfte des Gedächtnisses. Agenten und Teammitglieder können auch gezielt ins Gedächtnis schreiben:

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

• remember heftet eine Tatsache an ein Element (oder an das gesamte Projekt), typisiert als note, convention oder pitfall. Nutzen Sie es für Wissen, das weder im Code noch im Modell sichtbar ist: Eigenheiten des Deployments, historische Gründe, fragile Stellen.
• recall durchsucht das gesamte Gedächtnis — Ergebnisse, Notizen, Konventionen, Fallstricke — nach Begriffen, Element oder Typ. Das Ranking verbindet Bedeutung mit Wörtern: Ein Agent, der nach „rate limiting“ fragt, findet so die Notiz, die jemand anderes über „throttling“ geschrieben hat. Geben Sie Ihre sessionId mit, damit die Ihnen gelieferten Einträge später angerechnet werden können.
• find_relevant_context und start_work_session liefern automatisch die neuesten Gedächtniseinträge der passenden Elemente mit, sodass der nächste Agent mit dem startet, was die vorherigen gelernt haben.

Das Schreiben ins Gedächtnis ist dedupliziert: Eine bereits vorhandene Tatsache erneut festzuhalten legt keine zweite Kopie an, sondern bestätigt den bestehenden Eintrag (die Antwort meldet deduplicated: true) — denn ein Agent, der bekräftigt, was er gelernt hat, liefert Evidenz, kein Rauschen. Ein Eintrag, der nah dran, aber nicht identisch ist, wird gespeichert und in similarTo zurückgemeldet, damit Sie bewusst ersetzen, statt stillschweigend zu widersprechen.

Das Gedächtnis lernt außerdem aus der Nutzung. Endet eine Session, benennt usedMemories die Einträge, auf die sie sich tatsächlich gestützt hat. Diese Zitation ist das starke Signal: Zitierte Einträge behalten ihre Gewichtung, während ein Eintrag, der an fünf Sessions ausgeliefert und von keiner davon genannt wurde, als Rauschen herabgestuft wird. Automatisch gelöscht wird nichts — ignorierte Einträge tauchen in einer Prüfliste auf, über die ein Mensch entscheidet.

Das Gedächtnis hat einen Lebenszyklus, damit es zutreffend bleibt, statt sich nur anzuhäufen. Wenn sich ein von recall gelieferter Eintrag als korrekt erweist, bestätigen Sie ihn mit confirm_memory erneut — seine Frischeuhr wird zurückgesetzt und er bleibt höher gewichtet als ältere Informationen. Hat sich eine Tatsache geändert, lassen Sie nicht beide Versionen aktiv: remember(supersedes: "Old title") ersetzt den alten Eintrag, der damit aus dem Abruf verschwindet, aber in der Historie und im Graphen erhalten bleibt. Alles Unbestätigte verfällt sanft in der Gewichtung (Halbwertszeit 45 Tage), und für einen Agenten, der gleich Code ändert, werden Fallstricke immer höher gewichtet als einfache Notizen.

Gedächtniseinträge bilden einen Wissensgraphen, im Stil von Obsidian. Geben Sie einem Eintrag einen title, und er wird adressierbar: Jeder andere Eintrag kann ihn in seinem Inhalt mit [[Title]] referenzieren. Links lösen außerdem C4-Elemente über ihren Namen ([[ApiGateway]]) und Entscheidungen ([[ADR-17]]) auf — und ein Link auf einen noch nicht existierenden Titel bleibt offen und hängt sich in dem Moment an, in dem dieser Eintrag angelegt wird. Jeder Eintrag zeigt seine Backlinks, sodass Wissen in beide Richtungen navigierbar ist — und recall folgt den Links: Die besten Treffer bringen ihre per Wiki-Link verbundenen Nachbarn mit, gekennzeichnet mit via.

Der Speicher merkt auch, wenn sich die Architektur unter ihm bewegt. Ändert sich ein Element, an das eine Erinnerung geheftet ist, wird sie zur Überprüfung markiert: recall liefert sie weiterhin, aber gekennzeichnet mit [VERIFY — the element drifted since this was written], und sie fällt im Ranking zurück, statt zu verschwinden. Ein Fakt über einen inzwischen aufgeteilten Service ist nicht automatisch falsch — er hört nur auf, ohne menschlichen Blick vertrauenswürdig zu sein.

Der Speicher ist im Ruhezustand verschlüsselt wie jede sensible Inhaltsspalte und über die Oberfläche verwaltbar: das Memory-Panel im Agent Hub sowie ein Abschnitt pro Element im Detailbereich des Diagramms. Das Panel ist auf Triage ausgelegt — die linke Leiste zählt, was zu prüfen ist, was ignoriert wird und was veraltet ist, teilt den Rest nach Art auf, und jede Zeile trägt eine farbige Kante dafür, wie sehr man ihr trauen sollte.

Wechseln Sie zur Wissenskarte für die andere Frage: nicht was wissen wir, sondern wo. Eine Zelle pro C4-Element, die zeigt, was das Projekt darüber weiß und wie frisch dieses Wissen ist — einschließlich der Elemente, zu denen niemand etwas geschrieben hat, was meist die nützlichere Hälfte des Bildes ist.

In der CI

Dieselben Bausteine laufen mit den GitHub Actions in Ihrer Pipeline: generate-context committet ein archyl.txt-Briefing für Agenten ohne MCP-Zugang, conformance-check macht Pull Requests von Ihren Regeln abhängig, und auto-cr legt aus gemergten Änderungen Architektur-Änderungsanträge an.

Fehlerbehebung

In der Fleet-Konsole erscheinen keine Sessions. Der Agent ist ohne das Harness-Protokoll verbunden. Prüfen Sie, ob das Plugin installiert ist (der Skill archyl-harness vermittelt das Protokoll) und ob die MCP-URL ?profile=coding enthält — mit dem vollen Katalog aus 189 Tools erkunden Agenten oft, statt der Schleife zu folgen.

Der Guard blockiert nie etwas. Das ist beabsichtigt: Er arbeitet fail-open. Prüfen Sie, ob ARCHYL_API_KEY und ARCHYL_PROJECT_ID in der Umgebung exportiert sind, in der der Agent läuft, und ob Ihr Projekt Konformitätsregeln mit der Schwere critical besitzt.

Eine Session bleibt auf aktiv hängen. Sessions laufen 30 Minuten nach ihrem letzten Heartbeat ab und geben ihre Leases automatisch frei. Um die Leases sofort freizugeben, brechen Sie die Session in der Fleet-Konsole ab.

Welche Agenten werden unterstützt? Alles, was MCP spricht, erhält Context, Plan und das Session-Protokoll. Der Guard-Hook und die Skills zielen derzeit auf Claude Code; andere Agenten können dieselben Regeln über run_conformance_check oder die CI-Actions durchsetzen.