La documentation d'architecture ment. Pas intentionnellement -- elle cesse simplement d'etre vraie des que le code change. Aujourd'hui, nous lancons l'Architecture Drift Score : un chiffre unique qui vous indique a quel point votre modele C4 reflete fidelement votre codebase. Calcule en quelques secondes, suivi dans le temps et applicable dans votre CI.

Architecture Drift Score : votre documentation dit-elle la verite ?

Il y a un secret inavoue dans l'architecture logicielle : la plupart de la documentation est fausse.

Pas fausse comme "contient des erreurs". Fausse comme "decrit un systeme qui n'existe plus". Le diagramme montre un microservice fusionne avec un autre il y a six mois. Le modele C4 mentionne un cache Redis remplace par Memcached lors d'un incident un week-end. Le diagramme de composants reference un PaymentGateway renomme en BillingService lors d'un refactoring dont personne n'a informe l'architecte.

Ce n'est pas un probleme de discipline. C'est un probleme structurel. Le code change en continu. La documentation change quand quelqu'un y pense. L'ecart entre la realite et la documentation -- ce que nous appelons la derive architecturale -- grandit silencieusement jusqu'a ce que le diagramme au mur ne ressemble plus du tout au systeme en production.

Nous avons construit le Drift Score pour rendre cet ecart visible, mesurable et exploitable.

Un chiffre unique : de 0 a 100

L'Architecture Drift Score repond a une seule question : quel pourcentage de votre architecture documentee existe reellement dans votre codebase ?

Ouvrez n'importe quel projet dans Archyl, cliquez sur l'icone de battement de coeur dans l'en-tete, puis appuyez sur "Compute Drift Score". En quelques secondes, vous obtiendrez un chiffre entre 0 et 100 :

90-100% -- Excellent. Votre documentation correspond fidelement a la codebase.
70-89% -- Bien. Globalement fidele, quelques ecarts a combler.
50-69% -- Moyen. Derive significative detectee. Il est temps de mettre a jour.
En dessous de 50% -- Votre documentation est de la fiction.

C'est tout. Pas de rapport volumineux a lire. Pas d'evaluation subjective. Un chiffre que vous pouvez suivre, analyser et imposer.

Ce qui est reellement verifie

L'analyse de derive est legere par conception -- un seul appel API a votre fournisseur git, pas d'IA, pas de contenu de fichier recupere. Elle valide votre architecture selon cinq dimensions :

Systems -- Le nom de votre depot correspond-il au systeme documente ? Nous utilisons la meme convention de nommage PascalCase que le pipeline de decouverte IA, avec une correspondance floue pour que EkoAuthz corresponde a un depot nomme authz.

Containers -- Les repertoires de premier niveau de votre depot correspondent-ils aux containers documentes ? frontend/ correspond a FrontendWebApp. backend/ correspond a BackendApiServer. Les containers d'infrastructure (bases de donnees, files d'attente, monitoring) qui n'ont pas de repertoire source sont correctement exclus -- ce sont des documentations valides de services externes, pas de la derive.

Components -- Les composants sous chaque container sont-ils toujours valides ? Si le repertoire du container parent existe, ses composants sont presumes valides. Si le repertoire du container a disparu, tous ses composants sont signales.

Code Elements -- C'est la verification la plus precise. Chaque element de code dans votre modele C4 possede un filePath. Nous verifions que chaque fichier existe toujours dans le depot. Fichier renomme ? Classe supprimee ? Module deplace ? Le drift score le detecte instantanement.

Relationships -- Une relation est valide si ses elements source et cible ont passe la validation. Si l'un des points de terminaison a derive, la relation est signalee.

Le resultat est une ventilation par element montrant exactement ce qui correspond, ce qui manque et ce qui est nouveau -- pas un score opaque, mais un rapport exploitable.

Pourquoi la legerete est importante

Nous avons deliberement choisi de ne pas executer le pipeline complet de decouverte IA pour la detection de derive. Voici pourquoi :

Rapidite. L'analyse IA prend plusieurs minutes pour les gros depots. Le calcul du drift score prend quelques secondes. Vous pouvez l'executer a chaque push sans ralentir votre pipeline.

Determinisme. L'IA peut produire des resultats differents sur la meme codebase en fonction de la temperature du modele, des variations de prompts et des limites de tokens. L'existence d'un chemin de fichier est binaire -- soit le fichier est la, soit il ne l'est pas. Votre score est reproductible.

Cout. Aucun token d'IA consomme. Aucune limite de taux API atteinte. Executez-le cent fois par jour si vous le souhaitez.

Simplicite. L'algorithme est auditable. Verifier les chemins de fichiers, faire correspondre les noms de repertoires, valider les relations. Pas de boite noire.

Suivez les tendances, pas seulement les instantanes

Un score unique est utile. Une tendance est puissante.

Chaque calcul de derive est stocke avec sa ventilation complete. L'onglet Overview affiche un graphique en barres de votre score dans le temps. Cliquez sur n'importe quelle barre pour charger ce rapport historique et voir exactement ce qui a change.

Cela transforme le scoring de derive d'un audit ponctuel en une metrique de sante continue. Vous pouvez voir :

Le refactoring de la semaine derniere a-t-il ameliore ou degrade la precision de la documentation ?
La derive s'aggrave-t-elle avec le temps ? (Spoiler : sans automatisation, c'est toujours le cas.)
Quel sprint a introduit le plus de changements non documentes ?

Imposez-le dans la CI

Une metrique que vous n'imposez pas est une metrique que vous ignorerez. C'est pourquoi nous avons construit une GitHub Action.

on:
  push:
    branches: [main]

jobs:
  drift:
    runs-on: ubuntu-latest
    steps:
      - uses: archyl-com/actions/drift-score@v1
        with:
          api-key: ${{ secrets.ARCHYL_API_KEY }}
          organization-id: ${{ secrets.ARCHYL_ORG_ID }}
          project-id: 'your-project-uuid'
          threshold: '70'

Definissez threshold: '70' et l'action echoue si la precision de votre documentation architecturale passe en dessous de 70%. Le resume du job affiche un tableau formate avec la ventilation complete -- visible directement dans les checks de votre PR.

Vous pouvez egalement publier le score en commentaire de PR :

- uses: archyl-com/actions/drift-score@v1
  id: drift
  with:
    api-key: ${{ secrets.ARCHYL_API_KEY }}
    organization-id: ${{ secrets.ARCHYL_ORG_ID }}
    project-id: 'your-project-uuid'

- uses: actions/github-script@v7
  if: github.event_name == 'pull_request'
  with:
    script: |
      github.rest.issues.createComment({
        issue_number: context.issue.number,
        owner: context.repo.owner,
        repo: context.repo.repo,
        body: '## Architecture Drift: ' +
              '${{ steps.drift.outputs.score }}%\n' +
              'Matched: ${{ steps.drift.outputs.matched-count }}' +
              ' / ${{ steps.drift.outputs.total-elements }}'
      })

Chaque developpeur voit l'impact de la derive de ses changements avant le merge. La documentation d'architecture devient un citoyen de premiere classe dans votre pipeline CI -- aux cotes des tests, du linting et des analyses de securite.

MCP : des agents IA qui connaissent leur precision

Si vous utilisez Claude Code, Cursor ou tout agent IA compatible MCP avec le serveur MCP d'Archyl, le scoring de derive est disponible en tant qu'outil :

compute_drift_score({ projectId: "..." })
get_drift_score({ projectId: "..." })
get_drift_history({ projectId: "..." })
get_drift_details({ scoreId: "..." })

Cela signifie qu'un agent IA peut verifier la precision de la documentation avant de commencer a travailler. L'outil get_agent_context fournit deja le modele C4 complet, les ADRs et les regles de conformite. Desormais, il peut aussi verifier la fiabilite de cette documentation.

Un agent qui voit un drift score de 45% sait qu'il doit etre prudent avec le contexte architectural recu. Un agent qui voit 95% peut s'appuyer en confiance sur la structure documentee. C'est la base d'agents IA auto-conscients qui adaptent leur comportement en fonction de la qualite de la documentation.

Alertes webhook : soyez informe quand la derive survient

Deux nouveaux evenements webhook vous permettent de rester informe sans consulter les tableaux de bord :

drift.score_computed -- Se declenche a chaque fois qu'un drift score termine son calcul. Envoyez-le dans un canal Slack pour plus de visibilite.
drift.score_degraded -- Se declenche lorsque le score baisse de 10 points ou plus par rapport au calcul precedent. C'est votre systeme d'alerte precoce -- l'architecture derive rapidement.

Configurez ces evenements dans les parametres webhook d'Archyl. Ils fonctionnent avec Slack, Microsoft Teams, Discord et tout endpoint HTTP generique.

L'API REST

Pour les equipes qui souhaitent un controle programmatique complet :

# Declencher le calcul
curl -X POST https://api.archyl.com/api/v1/drift/compute \
  -H "X-API-Key: $API_KEY" \
  -H "X-Organization-ID: $ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{"projectId": "your-project-uuid"}'

# Obtenir le dernier score
curl https://api.archyl.com/api/v1/drift/latest?projectId=...

# Obtenir l'historique des scores
curl https://api.archyl.com/api/v1/drift/history?projectId=...&limit=20

Le calcul est asynchrone -- le POST retourne immediatement avec un ID de score, et vous interrogez jusqu'a ce que le status devienne completed. La GitHub Action gere cela automatiquement.

Ce que cela signifie pour l'ere agentique

Nous entrons dans une ere ou les agents IA ecrivent une part significative du code de production. Ces agents sont rapides, performants et aveugles au contexte. Ils ne savent pas que le AuthService a ete scinde en IdentityService et AccessControl le mois dernier. Ils ne savent pas que le repertoire frontend/ a ete renomme en web/.

Le drift score cree une boucle de retroaction :

L'agent IA lit le modele C4 via MCP avant d'ecrire du code.
Les changements de code se produisent (par des humains ou des agents).
Le drift score detecte l'ecart entre la documentation et la realite.
La porte CI empeche l'ecart de depasser un seuil.
Le webhook alerte l'equipe lorsque la derive s'accelere.
L'equipe met a jour la documentation (ou lance une decouverte pour la mettre a jour automatiquement).
L'agent IA lit le modele mis a jour. La boucle se ferme.

Sans l'etape 3, la boucle est ouverte. La documentation derive. Les agents s'appuient sur un contexte obsolete. Les mauvaises decisions s'accumulent.

Le drift score ferme la boucle.

Pour commencer

Ouvrez n'importe quel projet dans Archyl
Cliquez sur l'icone de battement de coeur dans la barre d'outils de l'en-tete
Cliquez sur "Compute Drift Score"
Configurez la GitHub Action pour un suivi continu
Configurez un webhook Slack pour les alertes drift.score_degraded

Votre documentation d'architecture reflete la realite ou non. Desormais, vous avez un chiffre qui vous dit laquelle des deux options correspond a votre situation.

Architecture Drift Score : votre documentation dit-elle la verite ? - Archyl Blog