Boucler la boucle : d'une métrique sortie de sa bande à la prochaine story
Résumé. Un système en production nourrit le prochain changement : un script déterministe
surveille une métrique contre sa ligne de base, une configuration versionnée dit ce qu'un agent
peut faire à chaque bande (consigner, diagnostiquer en lecture seule, proposer), le diagnostic
s'écrit comme une intention ou un compte rendu d'incident, une personne trie, et la correction
part avec un test de régression que l'incident ne pourra plus passer. Cette page applique ce
patron à un projet ddd-ts-kit : les métriques que le kit émet déjà et les requêtes par
lesquelles commencer, un bands.yaml sur elles, ce qu'il faut à une exécution sans état, le
compte rendu d'incident que story-scope --from accepte comme origine d'une story de
correction, et ce qui arrive d'un canal de discussion. Le patron est la dernière étape du
playbook du cycle de vie natif de l'IA d'Anthropic ;
la part du kit est ce que l'agent lit et écrit, et la détection reste celle de l'équipe.
La forme de la boucle
Section intitulée « La forme de la boucle »| Étape | Qui ou quoi | Artefact |
|---|---|---|
| détecter | un script de l'équipe : déterministe, testé unitairement, versionné, sans aucun modèle | la rupture : la métrique, la bande, la fenêtre |
| décider le palier | bands.yaml, versionné avec le script |
consigner, diagnostiquer ou proposer |
| diagnostiquer | un agent, en lecture seule, avec des outils nommés, dans une exécution sans état | les preuves : les entrées d'audit, les traces, le déploiement dans la fenêtre |
| proposer | le même agent, par une pull request ou un runbook approuvé d'avance | docs/architecture/intents/<slug>.md, ou le résultat du runbook |
| trier | le responsable du service : corriger maintenant, planifier, écarter | l'intention acceptée, planifiée ou close ; un écart ajuste la bande |
| corriger | /ddd-ts-kit:fix <code> docs/architecture/incidents/<id>.md |
une spec de régression verrouillée, le test permanent de l'incident |
La détection n'est jamais un agent : un script avec une ligne de base glissante (moyenne et écart sur une fenêtre, les règles de Western Electric pour la dérive comme pour les pics) répond de la même façon à chaque fois et se teste comme du code. Ce que le kit donne au script, ce sont les métriques ; ce qu'il donne à l'agent, c'est le journal d'audit, les traces, la CLI qui décrit le système, et deux templates.
Trois ruptures par lesquelles commencer
Section intitulée « Trois ruptures par lesquelles commencer »Les noms ci-dessous sont ceux que le kit enregistre par son port Metrics
(observabilité) ; ce que montre votre entrepôt dépend de son
exportateur, lisez donc les noms là une fois avant d'écrire les requêtes.
| Rupture | Ce que le kit émet | Requête (Prometheus) | Bande de départ |
|---|---|---|---|
| un cas d'usage échoue plus qu'avant | use_case_total{message, kind, outcome, error_code} depuis metricsMiddleware de @ddd-ts-kit/aspects, une série par classe de commande ou de requête |
sum by (message) (rate(use_case_total{outcome="failure"}[5m])) / sum by (message) (rate(use_case_total[5m])) |
le ratio par message contre sa ligne de base sur 30 jours ; un refus métier est un échec avec son error_code, si bien qu'un message qui refuse par conception (un créneau déjà pris) lit le ratio sans les codes que le métier attend |
| le relais de l'outbox s'est arrêté | outbox_pending, outbox_failed et outbox_dead, des jauges que le relais de main.ts pose depuis store.stats() après chaque passage ; aucune jauge ne donne l'âge du plus ancien enregistrement en attente, que le script lit dans la table outbox |
min_over_time(outbox_pending[15m]) > 0 or outbox_dead > 0 (un arriéré qui ne s'est jamais vidé, ou un enregistrement qui a épuisé ses tentatives) ; l'âge : SELECT extract(epoch FROM now() - min(created_at)) FROM messaging.outbox WHERE status = 'pending' (en secondes ; <schéma>.outbox là où le projet l'a mise) |
un enregistrement mort tout de suite ; un âge au-dessus de trois fois l'intervalle du relais, tenu sur deux relevés |
| un job a cessé de tourner | scheduled_job_runs_total{job, context, status, error_code} depuis @ddd-ts-kit/scheduling, status="succeeded" pour une exécution qui a tourné |
increase(scheduled_job_runs_total{job="notifications.send-reminders", status="succeeded"}[2h]) == 0 or absent(scheduled_job_runs_total{job="notifications.send-reminders", status="succeeded"}) (deux intervalles d'un job horaire) |
aucun succès pendant deux intervalles, ce qui attrape toutes les façons dont un job s'arrête, là où une alerte sur les échecs ne le fait pas |
dependency_call_total{class, method, kind, context, outcome} (l'aspect timed) et
circuit_breaker_state viennent ensuite : une dépendance qui échoue ou un disjoncteur qui
s'ouvre explique une rupture d'un cas d'usage plus souvent que le cas d'usage lui-même.
bands.yaml, trois paliers
Section intitulée « bands.yaml, trois paliers »# Versionné avec le script de détection ; un écart au tri ajuste une bande ici, dans une pull request.baseline: rolling_30drules: western_electricmetrics: use_case_failure_ratio: # par message, 5 minutes, depuis use_case_total tiers: 1sigma: { action: log } 2sigma: action: diagnose tools: "Read,Grep,Bash(npx ddd-ts-kit describe *),Bash(npx ddd-ts-kit list *),Bash(gh run view *)" 3sigma: { action: propose, routes: [intent, runbook:rollback-deploy] } outbox_oldest_pending_age_seconds: # depuis la table outbox tiers: 1sigma: { action: log } 2sigma: { action: diagnose, tools: "Read,Grep,Bash(npx ddd-ts-kit describe *)" } 3sigma: { action: propose, routes: [runbook:restart-relay, intent] } scheduled_job_success_absent: # par job, deux intervalles, depuis scheduled_job_runs_total tiers: 1sigma: { action: log } 2sigma: { action: diagnose, tools: "Read,Grep,Bash(npx ddd-ts-kit describe *)" } 3sigma: { action: propose, routes: [intent] }- log écrit la rupture là où l'équipe la lit, rien d'autre.
- diagnose lance l'agent en lecture seule, avec les outils nommés et aucun autre : le dépôt
au commit déployé,
npx ddd-ts-kit describe <context>pour ce que tient le contexte, le journal d'audit de la fenêtre par la route de recherche que la plateforme expose sous sa propre permission (journal d'audit, appelée avec un jeton en lecture seule que l'exécution reçoit pour cela), les traces par identifiant de corrélation, le dernier déploiement dans la fenêtre. Sa sortie est un diagnostic, pas un changement. - propose laisse l'agent agir par l'une de deux portes : la porte de revue, une intention
écrite depuis le template de la skill story (
plugin/skills/story/intent-template.md, avec## Evidencetenant la métrique, la fenêtre, les entrées d'audit et le déploiement dans la fenêtre), ouverte en pull request versdocs/architecture/intents/, que le responsable accepte ou clôt comme toute intention (parcours d'une story) ; ou un runbook que l'équipe a approuvé d'avance, par son nom, répété, avec un retour arrière que l'agent peut déclencher et ne peut pas inventer.
Ce qu'il faut à une exécution sans état
Section intitulée « Ce qu'il faut à une exécution sans état »Chaque exécution part de rien et ne laisse rien que son artefact : le dépôt, en lecture seule,
au commit déployé ; l'entrepôt de métriques, avec un jeton qui lit et n'écrit jamais ; la CLI
du projet (npm ci, puis npx ddd-ts-kit describe, list, check au besoin) ; la recherche
d'audit et les traces, en lecture seule ; la permission d'ouvrir une pull request sur la
branche de l'intention, et rien d'autre. Aucun identifiant de production, aucun accès en
écriture à une base de données, aucun outil de déploiement sauf si un runbook le nomme.
L'exécution est isolée comme toute session d'agent : voir
isoler les agents de code. Le déclencheur est une planification, un
webhook de l'outil d'alerte ou un cron ; deux exécutions sur la même rupture écrivent le
même diagnostic, et c'est le but.
Le compte rendu d'incident
Section intitulée « Le compte rendu d'incident »Celui qui traite l'incident (une personne, le répondeur du canal, le palier propose) écrit
docs/architecture/incidents/<id>.md depuis plugin/skills/story/incident-template.md : ce
qui a été observé (le symptôme, la métrique, la bande, la fenêtre), les preuves (la requête et
sa valeur, le déploiement dans la fenêtre, les entrées d'audit, les traces, les lignes de
journal), la cause par son nom métier quand elle est connue (le cas d'usage, l'agrégat,
l'invariant, la dépendance ; unknown sinon, avec ce qui a été écarté), ce qui a été fait (un
retour arrière, un runbook, une correction manuelle, rien, et quand la métrique est revenue),
et la suite. C'est le fichier des leçons que la prochaine investigation lit en premier, et
l'origine de la correction :
npx ddd-ts-kit story-scope FIX-412 --kind fix --from docs/architecture/incidents/INC-2026-10-18-checkout.mdstory-scope accepte un compte rendu d'incident tel quel (une intention doit d'abord être
accepted), écrit l'origine dans .ddd-ts-kit/story.json, et ## Origin de la story de
correction renvoie à l'incident. La correction est /ddd-ts-kit:fix : sa spec de régression
est écrite d'abord, échoue sur l'incident, est verrouillée et tenue par la garde, et c'est le
test permanent de l'incident ; la story de la correction la liste sous ## Regression, et
npx ddd-ts-kit story <code> lit une correction derrière cette section au lieu de
test/acceptance/. Un second incident de la même classe (le même message ou le même
error_code qu'un compte rendu antérieur, nommé sous What is next) est ce que la boucle doit
rendre rare.
Ce qui arrive d'un canal de discussion
Section intitulée « Ce qui arrive d'un canal de discussion »Un agent dans le canal d'incident, sous sa propre identité, appartient à la plateforme : le kit
n'en livre aucun. Ce qu'il dit entre dans la boucle du kit de la même façon qu'une rupture : une
correction bornée devient une story de correction, /ddd-ts-kit:fix <code>, avec le fil pour
origine (le compte rendu d'incident cite le résumé et le lien du fil, et le compte rendu est le
--from) ; un changement plus large devient une intention, écrite depuis le template avec le
résumé du fil pour problème et l'auteur de la demande pour auteur ; le post-mortem est le
compte rendu d'incident ci-dessus, écrit dans docs/architecture/incidents/. L'agent du canal
vérifie que la métrique est revenue dans sa bande avec les mêmes requêtes que le palier
diagnose, et rien de ce qu'il écrit dans le canal ne remplace le compte rendu dans le dépôt.
Ce que le kit ne fait pas
Section intitulée « Ce que le kit ne fait pas »- Pas de script de détection ni de planificateur : déterministes, testés, propres à l'entrepôt de métriques et à la plateforme ; cette page donne les requêtes et la forme, et une équipe les écrit en une journée.
- Pas de runbook : un retour arrière dépend de la plateforme cible ; le kit s'arrête à l'image.
- Pas de répondeur de canal : l'identité, le canal et les outils sont ceux de la plateforme.
- Pas de jauge pour l'âge du plus ancien enregistrement en attente de l'outbox : les jauges donnent la profondeur, le script lit l'âge dans la table.
- Aucune fusion décidée par un constat : le palier propose ouvre une pull request ou lance un runbook approuvé d'avance ; une personne accepte l'intention et un responsable du code approuve la correction.