DAT as Code : automatiser la documentation technique avec l'IA

Source: Dev.to

Introduction

L’année dernière, j’ai écrit un guide pour moderniser son DAT (Dossier d’Architecture Technique). Un an après, avec l’arrivée des coding assistants et leurs connecteurs, je me suis demandé : qu’est‑ce qu’on peut vraiment faire avec l’IA pour maintenir un DAT ?

J’ai testé sur un projet Infra‑as‑code.
Objectif : partir de zéro et arriver à une doc complète (architecture + exploitation) avec le moins d’effort possible.
Spoiler : quelques heures de setup et ça marche.

La découverte : templates + prompts

Premier test avec un coding assistant : je lui donne un fichier markdown avec une structure (titres, sections) et j’y glisse des instructions dans des commentaires HTML.

Exemple :

## 🏗️ Prérequis

## Description de la gestion IAM

Le coding assistant suit la structure et remplit chaque section selon les consignes.
Ça peut paraître simple, mais c’est la méthode la plus efficace que j’ai testée pour garder une cohérence de style documentaire globale.

Le problème : 3 outils à synchroniser

Dans un projet classique, je jongle avec :

• GitHub (code) : markdown en doc‑as‑code
• Confluence (doc) : pour la recherche et la facilité de lecture
• Jira (ticket) : pour tracer les issues et projets

Maintenir la doc Confluence à jour à la main, c’est l’enfer.
On aimerait pouvoir le faire dans GitHub à côté du code, mais c’est moins pratique pour la recherche.
L’idéal : écrire la doc avec le code et mettre Confluence à jour en conséquence, avec des liens et des références vers la doc sur GitHub.

La solution : MCP (Model Context Protocol)

Les MCP sont des connecteurs qui permettent à ton coding assistant de dialoguer avec des services externes. J’en ai identifié trois essentiels pour ce projet :

• Context7 : vérifie que la doc respecte les standards et détecte ce qui manque.
• GitHub : lit le code (Terraform dans mon cas) pour extraire l’info architecture.
• Atlassian : s’interface avec Confluence et Jira.

Setup

J’installe les 3 MCP dans mon IDE (VsCode dans mon cas, mais ça fonctionne avec Cursor, IntelliJ, etc.).
Pour Atlassian, je configure en plus dans .vscode/settings.json :

{
  // Configuration MCP
  "mcp.confluence.enabled": true,
  "mcp.confluence.baseUrl": "https://votre-domaine.atlassian.net",
  "mcp.confluence.defaultSpace": "SPACE_KEY",
  "mcp.jira.enabled": true,
  "mcp.jira.baseUrl": "https://votre-domaine.atlassian.net",
  "mcp.jira.defaultProject": "PROJECT_KEY",
  "mcp.servers": {
    "confluence": {
      "command": "mcp-confluence",
      "args": [
        "--space",
        "SPACE_KEY",
        "--page-id",
        "PAGE_ID"
      ]
    },
    "jira": {
      "command": "mcp-jira",
      "args": [
        "--project",
        "PROJECT_KEY",
        "--board",
        "BOARD_ID"
      ]
    }
  }
}

Récupérer les valeurs

• Confluence (https://domaine.atlassian.net/wiki/spaces/MON_ESPACE/pages/12345678/Titre)

  • SPACE_KEY = MON_ESPACE
  • PAGE_ID = 12345678

• Jira (https://domaine.atlassian.net/jira/software/c/projects/MON_PROJET/boards/99)

  • PROJECT_KEY = MON_PROJET
  • BOARD_ID = 99

Je teste les connexions : ça passe ✓

Ensuite, je crée un repo GitHub avec mes templates de doc dans tpl_docs/ :

• TPL_README.md : vue globale
• TPL_README_IAM.md : IAM
• TPL_README_FW.md : firewall
• TPL_README_SIZING.md : sizing
• TPL_README_PROCEDURE.md : procédures
• TPL_README_DEX.md : dossier d’exploitation

Vous pouvez consulter les templates complets sur le repository GitHub.

Itération 1 : créer la documentation

J’ai créé une commande custom create doc dans agents.md (configuration du coding assistant) pour tout faire d’un coup.

Problèmes rencontrés

1. Authentification GitHub : l’assistant essayait d’accéder à mon dépôt privé sans token → résolu en précisant le connecteur GitHub dans agents.md.
2. Dépassement de contexte (Claude Sonnet 4.5) lors de la génération de plusieurs fichiers d’un coup :

[INFO] Analyse du code Terraform... ✓
[INFO] Génération README.md... ✓
[INFO] Génération IAM.md... ✓
[INFO] Génération FW.md... ✓
[ERROR] Context length exceeded (125k tokens)
[FAIL] Process stopped

Conclusion : il faut découper le processus.

Itération 2 : approche itérative

J’ai modifié agents.md pour séparer le workflow :

1. Analyse : inspection du Terraform.
2. Plan : liste des docs à générer.
3. Exécution : un doc à la fois, une conversation par doc.

Exemple de log :

NEW CONVERSATION> Analyse le code
Analyse du code Terraform... ✓
[INFO] Génération du plan de documentation... ✓

NEW CONVERSATION> Génération README.md
[INFO] Génération README.md... ✓

NEW CONVERSATION> Génération IAM.md
[INFO] Génération IAM.md... ✓

NEW CONVERSATION> Génération FW.md
[INFO] Génération FW.md... ✓

NEW CONVERSATION> Génération SIZING.md
[INFO] Génération SIZING.md... ✓

[SUCCESS] Documentation complète générée

Résultats

• Analyse + plan : ✓
• Génération séquentielle : ✓ (mais plus long)
• Documentation complète : ✓

Le processus itératif fonctionne, mais reste verbeux. J’ai dû affiner les prompts dans les templates pour limiter la sortie à « 5 lignes max ».

Itération 3 : documentation d’exploitation (DEX)

Après l’itération 2, la doc d’architecture était prête. J’ai ajouté la documentation d’exploitation : SLA, fiche DICT, monitoring, sauvegarde, et procédures d’exploitation.

Le coding assistant excelle à générer les procédures avec les commandes précises. Exemple :

gcloud compute instances attach-disk instance-1 --disk=disk-1 --zone=europe-west1-b

Cette précision évite de perdre du temps à chercher la syntaxe exacte.

J’ai ajouté TPL_README_DEX.md et TPL_README_PROCEDURE.md, puis mis à jour agents.md. Le problème de verbosité persiste, mais les améliorations de prompts continuent d’être appliquées.