Archyl Harness

Les agents de développement connaissent parfaitement votre dépôt — et pas du tout votre architecture. Ils réécrivent un service qu'un autre agent est en train de refactorer au même moment, introduisent la dépendance que votre équipe a bannie dans un ADR il y a deux ans, et laissent votre documentation décrire un système qui n'existe plus.

Archyl Harness corrige cela. Il encapsule n'importe quel agent de développement — Claude Code, Codex, Cursor, votre bot de CI ou les agents gérés d'Archyl — dans une boucle encadrée, construite sur votre architecture documentée :

La boucle qu'exécute un agent :

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)

Et comme chaque session pose des réservations consultatives (leases) sur les éléments C4 qu'elle touche, deux agents qui travaillent sur le même service se voient avant d'entrer en collision — dans leurs briefings comme en direct sur votre diagramme.

Optionnel par conception

Le harness s'active à la demande : rien ne se déclenche parce que vous avez documenté une architecture. Un agent n'entre dans la boucle que si vous faites l'une de ces trois choses : connecter le serveur MCP avec ?profile=coding, installer la skill archyl-harness qui enseigne le protocole, ou ajouter le hook Guard. Défaites-les et les agents de ce dépôt se comportent exactement comme avant.

Tout le reste d'Archyl fonctionne sans lui. La récupération de contexte, l'analyse d'impact, la propriété des éléments, les vérifications de conformité, la détection de dérive et le système de mémoire sont tous accessibles depuis le catalogue complet, sans la moindre session de travail. Utiliser Archyl comme une architecture documentée que vos agents peuvent lire — et ignorer complètement ce guide — est une façon parfaitement prévue de s'en servir.

Les deux moitiés s'adoptent séparément parce qu'elles n'ont pas les mêmes droits. Un registre tire son autorité de la curation humaine : un ADR, une règle de conformité, une demande de changement approuvée portent chacun un statut parce qu'une personne les y a mis, et une entrée fausse y dort tranquillement jusqu'à ce que quelqu'un la lise et la corrige. Un protocole, lui, émet des instructions que les agents exécutent : c'est un risque d'une autre nature, qui mérite une décision délibérée plutôt qu'un défaut.

Cette ligne est tracée à l'intérieur du produit, pas seulement autour. Les agents peuvent lire le registre et y écrire, mais ce qu'ils écrivent revient aux agents suivants comme un contexte daté et attribué — jamais comme une règle. Seuls les ADR et les règles de conformité sont servis comme contraignants, et le seul chemin qui mène ce qu'un agent a enregistré jusqu'à ce statut passe par un humain : un ADR, ou une demande de changement d'architecture que quelqu'un a approuvée.

Installation en cinq minutes

Il vous faut un projet Archyl avec une architecture documentée (lancez d'abord la découverte IA si le vôtre est vide) et une clé API avec la portée write, créée depuis Profil → Clés API.

Option A — une seule commande

À la racine de votre dépôt :

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

Le script vous demande votre clé API et votre projet, puis configure tout ce qui suit. C'est terminé — passez directement à Votre première session.

Option B — étape par étape

1. Connectez le serveur MCP avec le profil coding. Dans votre dépôt, créez ou complétez .mcp.json :

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

?profile=coding a son importance : il réduit la surface de 189 outils aux 16 dont un agent de développement a besoin, ce qui garde son contexte léger et ses choix évidents.

2. Installez le plugin (Claude Code) :

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

Cela installe les skills (dont archyl-harness, qui enseigne le protocole de session à votre agent) et le hook Guard.

3. Activez le Guard. Exportez deux variables là où tourne votre agent :

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

C'est tout ce dont le Guard a besoin. Il est fail-open : sans ces variables (ou sans réseau), il ne fait rien, et ne peut donc jamais casser votre workflow.

Votre première session

Demandez n'importe quelle modification à votre agent — par exemple, « ajoute une limitation de débit à l'API publique ». Avec le harness installé, voici ce qui se passe :

Avant de coder, l'agent déclare le travail :

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

L'agent sait désormais où travailler, quelles décisions le contraignent et ce que le dernier agent y a fait — sans avoir lu tout votre dépôt.

Pendant qu'il code, le Guard vérifie chaque fichier que l'agent s'apprête à écrire par rapport à vos règles de conformité. Une violation critique bloque l'écriture en affichant la règle et sa suggestion ; l'agent s'adapte et poursuit.

Une fois terminé, l'agent boucle la boucle :

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

Les réservations sont libérées, le résumé est épinglé comme mémoire sur ApiGateway pour le prochain agent, et une demande de changement d'architecture en brouillon arrive dans Archyl pour qu'un humain décide comment le modèle C4 doit être mis à jour.

Chaque décision est enregistrée comme une mémoire à part entière : une session ultérieure peut la remplacer, la reconfirmer ou la laisser vieillir sans toucher au reste de ce que votre session a laissé. Les décisions reviennent aux agents suivants comme un contexte daté et attribué — jamais comme des règles. Seuls les ADR et les règles de conformité sont présentés à un agent comme contraignants, et c'est par la demande de changement qu'une décision accède à ce statut.

Surveiller vos agents : la console Fleet

Ouvrez Agent Hub → Fleet pour voir le travail en cours : combien d'agents sont à l'œuvre, quels éléments C4 sont actuellement réservés, et une carte par session active avec sa tâche, les éléments qu'elle détient, son gate et la fraîcheur de son heartbeat. Les sessions terminées basculent dans Sessions récentes avec le résumé que chacune a rapporté.

Une session dont le heartbeat s'arrête est signalée, et expire d'elle-même 30 minutes plus tard. Vous pouvez aussi l'annuler depuis ici, ce qui libère ses réservations immédiatement.

La même information vous parvient là où vous regardez vraiment — sur le diagramme. Tout élément détenu par un agent porte un badge à son nom, et cliquer dessus revient à lui demander ce qu'il fait : la tâche déclarée, tout ce qu'il détient par ailleurs, et depuis combien de temps il a donné signe de vie.

Pour les agents gérés d'Archyl, vous pouvez aussi piloter un agent en cours d'exécution — écrivez un message sur la page d'exécution et il est injecté dans son prochain cycle de raisonnement.

Le gate

Chaque session démarre par un verdict de contrôle préalable :

Utilisez exclusive: true pour les modifications qui ne doivent entrer en concurrence avec personne : migrations de schéma, changements de contrat.

Configuration du Guard

À la place des variables d'environnement, un fichier .archyl.json versionnable à la racine du dépôt peut porter la moitié non secrète : { "apiUrl": "…", "projectId": "…" }. Gardez la clé API dans l'environnement.

Mémoire

Les résultats de session ne sont que la moitié automatique de la mémoire. Les agents comme vos collègues peuvent aussi écrire de la mémoire délibérément :

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

• remember épingle un fait sur un élément (ou sur le projet entier), typé note, convention ou pitfall. Utilisez-le pour ce qui n'est visible ni dans le code ni dans le modèle : particularités de déploiement, raisons historiques, points fragiles.
• recall fouille toute la mémoire — résultats, notes, conventions, pièges — par termes, par élément ou par type. Le classement mêle le sens aux mots : un agent qui interroge sur le « rate limiting » retrouve donc la note qu'un autre avait écrite sur le « throttling ». Passez votre sessionId pour que les mémoires qui vous ont été servies puissent être créditées ensuite.
• find_relevant_context et start_work_session servent automatiquement les mémoires les plus récentes des éléments concernés : l'agent suivant démarre donc avec ce que les précédents ont appris.

Écrire une mémoire est dédupliqué : réaffirmer un fait qui existe déjà ne stocke pas une seconde copie, cela confirme celle qui existe (la réponse indique deduplicated: true) — parce qu'un agent qui réaffirme ce qu'il a appris apporte une preuve, pas du bruit. Une mémoire proche mais non identique, elle, est bien enregistrée et signalée en retour dans similarTo : son auteur remplace ainsi l'ancienne délibérément, au lieu de la contredire en silence.

La mémoire apprend aussi de l'usage. À la fin d'une session, usedMemories nomme les mémoires sur lesquelles elle s'est réellement appuyée. Cette citation est le signal fort : les mémoires citées gardent leur rang, tandis qu'une mémoire servie à cinq sessions et jamais nommée par aucune d'elles est rétrogradée comme du bruit. Rien n'est supprimé automatiquement — les mémoires ignorées remontent dans une file de revue, pour qu'un humain tranche.

La mémoire a un cycle de vie, pour rester juste au lieu de s'empiler. Quand une mémoire servie par recall s'avère exacte, réattestez-la avec confirm_memory : son horloge de fraîcheur repart à zéro et elle continue de passer devant les informations plus anciennes. Quand un fait a changé, ne laissez pas les deux versions vivantes : remember(supersedes: "Old title") remplace l'ancienne mémoire, qui quitte la recherche mais reste dans l'historique et dans le graphe. Tout ce qui n'est pas confirmé décline doucement dans le classement (demi-vie de 45 jours), et pour un agent sur le point de modifier du code, les pièges passent toujours devant les simples notes.

Les mémoires forment un graphe de connaissances, à la manière d'Obsidian. Donnez un title à une mémoire et elle devient adressable : n'importe quelle autre mémoire peut y faire référence avec [[Title]] dans son contenu. Les liens résolvent aussi les éléments C4 par leur nom ([[ApiGateway]]) et les décisions ([[ADR-17]]) — et un lien vers un titre qui n'existe pas encore reste en attente, puis s'attache dès que cette mémoire est créée. Chaque mémoire expose ses backlinks : la connaissance se parcourt donc dans les deux sens — et recall suit les liens, les meilleurs résultats entraînant avec eux leurs voisins reliés par wiki-liens, signalés par via.

La mémoire remarque aussi quand l'architecture bouge sous elle. Lorsqu'un élément auquel une mémoire est épinglée change, cette mémoire est signalée pour révision : recall la sert toujours, mais marquée [VERIFY — the element drifted since this was written], et elle recule dans le classement plutôt que de disparaître. Un fait écrit sur un service depuis scindé n'est pas automatiquement faux — il cesse simplement d'être fiable sans un regard humain.

La mémoire est chiffrée au repos comme toute colonne de contenu sensible, et se gère depuis l'interface : le panneau Mémoire dans l'Agent Hub, plus une section par élément dans le panneau de détails du diagramme. Le panneau est fait pour le tri — la colonne de gauche compte ce qui doit être revu, ce qui est ignoré et ce qui a vieilli, puis répartit le reste par nature, et chaque ligne porte une arête colorée indiquant d'un coup d'œil la confiance à lui accorder.

Basculez sur la carte des connaissances pour l'autre question : non pas que sait-on mais où. Une cellule par élément C4, montrant ce que le projet en sait et la fraîcheur de ce savoir — y compris les éléments sur lesquels personne n'a rien écrit, ce qui est souvent la moitié la plus utile du tableau.

En CI

Les mêmes briques tournent dans votre pipeline avec les GitHub Actions : generate-context committe un briefing archyl.txt pour les agents sans accès MCP, conformance-check conditionne les pull requests au respect de vos règles, et auto-cr dépose des demandes de changement d'architecture à partir des modifications mergées.

Dépannage

Aucune session n'apparaît dans la console Fleet. L'agent est connecté sans le protocole du harness. Vérifiez que le plugin est installé (la skill archyl-harness enseigne le protocole) et que l'URL MCP contient bien ?profile=coding — avec le catalogue complet de 189 outils, les agents explorent souvent au lieu de suivre la boucle.

Le Guard ne bloque jamais rien. C'est voulu : il est fail-open. Vérifiez que ARCHYL_API_KEY et ARCHYL_PROJECT_ID sont exportées dans l'environnement où tourne l'agent, et que votre projet possède des règles de conformité de sévérité critical.

Une session reste bloquée en actif. Les sessions expirent 30 minutes après leur dernier heartbeat et libèrent automatiquement leurs réservations. Pour les libérer immédiatement, annulez la session depuis la console Fleet.

Quels agents sont pris en charge ? Tout ce qui parle MCP bénéficie de Context, Plan et du protocole de session. Le hook Guard et les skills visent aujourd'hui Claude Code ; les autres agents peuvent appliquer les mêmes règles via run_conformance_check ou les actions de CI.