ronan.quintin/Keryloo
1
0
Fork 0
Code Issues 3 Pull requests Projects Releases Packages Wiki Activity Actions

Agent de documentation #13

New issue
Closed
opened 2025-12-22 20:44:42 +01:00 by ronan.quintin · 0 comments
ronan.quintin commented 2025-12-22 20:44:42 +01:00
Owner
Copy link

Spécification – Gouvernance de la documentation et agent Documentation Manager

1. Contexte

Le projet Keryloo atteint un niveau de maturité nécessitant :

  • Une documentation structurée et lisible
  • Une séparation claire des responsabilités documentaires
  • Une mise à jour systématique de la documentation après chaque évolution
  • Une automatisation de cette mise à jour via des agents Claude

Cette spécification définit :

  • La structure documentaire cible
  • Le rôle précis de chaque document
  • La création d’un agent spécialisé de mise à jour de la documentation
  • Le workflow de contribution standardisé via Forgejo

2. Objectifs

  • Clarifier le rôle du README.md
  • Maintenir un guide d’installation détaillé séparé
  • Introduire un guide de contribution formel
  • Automatiser la mise à jour de la documentation
  • Garantir que toute évolution du code est accompagnée d’une mise à jour documentaire

3. Structure documentaire cible (Option A)

3.1 README.md (racine du projet)

Rôle unique : porte d’entrée du projet

Le README.md doit permettre à un développeur de :

  • Comprendre rapidement le projet
  • Lancer l’application rapidement
  • Identifier où se trouve la documentation complète

Contenu autorisé

  • Présentation synthétique du projet
  • Stack technique
  • Prérequis
  • Démarrage rapide (Quick Start)
  • Liens vers la documentation détaillée

Contenu interdit

  • Procédures longues
  • Détails d’architecture
  • Installation pas à pas
  • Déploiement production

3.2 Répertoire keryloo-doc/

01-INSTALLATION.md

Responsabilité : installation détaillée en environnement local / développement

Doit inclure :

  • Installation pas à pas
  • Configuration manuelle (sans Docker)
  • Configuration Docker
  • Configuration Keycloak
  • Configuration SMTP
  • Cas particuliers (Raspberry, NAS, etc.)
  • Troubleshooting

02-ARCHITECTURE_TECHNIQUE.md

Responsabilité : vision technique globale

Doit inclure :

  • Architecture générale
  • Découpage en modules
  • Choix techniques structurants
  • Patterns utilisés (Event Bus, Workflow, GED, Audit, Sécurité)
  • Contraintes non fonctionnelles

03-GUIDE_FONCTIONNEL.md

Responsabilité : description fonctionnelle du produit

Doit inclure :

  • Vue d’ensemble
  • Fonctionnalités existantes
  • Parcours utilisateur
  • Terminologie métier

Ne doit contenir aucun détail technique.

04-DEPLOIEMENT_PRODUCTION.md

Responsabilité : installation en production

Doit inclure :

  • Déploiement Docker / Docker Compose
  • Gestion des volumes
  • Variables d’environnement
  • Sauvegardes
  • Sécurité minimale
  • Observabilité (logs, monitoring si existant)

05-CONTRIBUTING.md (nouveau)

Responsabilité : règles de contribution au projet

4. Contenu du fichier 05-CONTRIBUTING.md

4.1 Objectif

Définir un cadre clair pour toute contribution au projet Keryloo, qu’elle soit :

  • Fonctionnelle
  • Technique
  • Documentaire

4.2 Workflow de contribution (Forgejo)

Le workflow standard est le suivant :

  1. Créer une branche à partir de main

    feature/xxx
fix/xxx
tech/xxx

  2. Implémenter la fonctionnalité ou la correction

  3. Pousser la branche sur Forgejo

  4. Créer une Merge Request vers main

  5. La Merge Request doit :

    • Décrire la modification
    • Référencer les tickets Forgejo
    • Mentionner les impacts documentaires

  6. La Merge Request est revue avant fusion

4.3 Règles de contribution

  • Toute nouvelle fonctionnalité doit être documentée
  • Toute modification technique structurante doit être documentée
  • Le README ne doit être modifié que si le démarrage du projet change
  • La documentation ne doit jamais anticiper des fonctionnalités non implémentées

4.4 Rôles des agents Claude

  • architect : analyse globale, orchestration
  • backend-developer / frontend-developer : implémentation
  • backend-reviewer / frontend-reviewer : revue
  • documentation-manager : mise à jour documentaire

5. Création de l’agent documentation-manager

5.1 Nom

documentation-manager

5.2 Responsabilités

  • Identifier les impacts documentaires d’une demande
  • Mettre à jour les fichiers concernés
  • Maintenir la cohérence globale
  • Ne jamais modifier le code applicatif
  • Ne documenter que l’existant

5.3 Entrées

  • Spécification fonctionnelle ou technique
  • Résumé des changements implémentés
  • Structure documentaire actuelle

5.4 Sorties

  • Fichiers Markdown mis à jour
  • Liste des sections modifiées
  • Signalement des incohérences détectées

6. Orchestration des agents

6.1 Rôle de l’agent architect

L’agent architect est responsable de :

  • Analyser la demande
  • Identifier les impacts
    • Code
    • Architecture
    • Documentation
  • Orchestrer les agents dans l’ordre suivant :

architect
→ backend-developer / frontend-developer
→ backend-reviewer / frontend-reviewer
-> test etc...
→ Et à la toute fin : documentation-manager

6.2 Règle obligatoire

Une demande n’est considérée comme terminée que si :

  • l’agent documentation-manager a été exécuté
  • la documentation a été mise à jour si nécessaire

7. Bonnes pratiques documentaires

  • À faire
  • Être factuel
  • Être concis
  • Respecter la structure
  • Éviter les redondances

À éviter

  • Dupliquer l’information
  • Mélanger fonctionnel et technique
  • Documenter des évolutions futures
  • Transformer la documentation en spécification

8. Critères de succès

  • Documentation toujours alignée avec le code
  • README clair et lisible en moins de 5 minutes
  • Installation détaillée accessible sans lire le code
  • Processus de contribution clair et reproductible

9. Évolutions futures possibles

Validation documentaire en CI

Génération automatique de changelog

Publication de la documentation

# Spécification – Gouvernance de la documentation et agent Documentation Manager ## 1. Contexte Le projet **Keryloo** atteint un niveau de maturité nécessitant : - Une documentation structurée et lisible - Une séparation claire des responsabilités documentaires - Une mise à jour systématique de la documentation après chaque évolution - Une automatisation de cette mise à jour via des agents Claude Cette spécification définit : - La structure documentaire cible - Le rôle précis de chaque document - La création d’un agent spécialisé de mise à jour de la documentation - Le workflow de contribution standardisé via Forgejo --- ## 2. Objectifs - Clarifier le rôle du README.md - Maintenir un guide d’installation détaillé séparé - Introduire un guide de contribution formel - Automatiser la mise à jour de la documentation - Garantir que toute évolution du code est accompagnée d’une mise à jour documentaire --- ## 3. Structure documentaire cible (Option A) ### 3.1 README.md (racine du projet) **Rôle unique : porte d’entrée du projet** Le README.md doit permettre à un développeur de : - Comprendre rapidement le projet - Lancer l’application rapidement - Identifier où se trouve la documentation complète #### Contenu autorisé - Présentation synthétique du projet - Stack technique - Prérequis - Démarrage rapide (Quick Start) - Liens vers la documentation détaillée #### Contenu interdit - Procédures longues - Détails d’architecture - Installation pas à pas - Déploiement production --- ### 3.2 Répertoire `keryloo-doc/` #### 01-INSTALLATION.md **Responsabilité : installation détaillée en environnement local / développement** Doit inclure : - Installation pas à pas - Configuration manuelle (sans Docker) - Configuration Docker - Configuration Keycloak - Configuration SMTP - Cas particuliers (Raspberry, NAS, etc.) - Troubleshooting --- #### 02-ARCHITECTURE_TECHNIQUE.md **Responsabilité : vision technique globale** Doit inclure : - Architecture générale - Découpage en modules - Choix techniques structurants - Patterns utilisés (Event Bus, Workflow, GED, Audit, Sécurité) - Contraintes non fonctionnelles --- #### 03-GUIDE_FONCTIONNEL.md **Responsabilité : description fonctionnelle du produit** Doit inclure : - Vue d’ensemble - Fonctionnalités existantes - Parcours utilisateur - Terminologie métier Ne doit contenir **aucun détail technique**. --- #### 04-DEPLOIEMENT_PRODUCTION.md **Responsabilité : installation en production** Doit inclure : - Déploiement Docker / Docker Compose - Gestion des volumes - Variables d’environnement - Sauvegardes - Sécurité minimale - Observabilité (logs, monitoring si existant) --- #### 05-CONTRIBUTING.md (nouveau) **Responsabilité : règles de contribution au projet** --- ## 4. Contenu du fichier 05-CONTRIBUTING.md ### 4.1 Objectif Définir un cadre clair pour toute contribution au projet Keryloo, qu’elle soit : - Fonctionnelle - Technique - Documentaire --- ### 4.2 Workflow de contribution (Forgejo) Le workflow standard est le suivant : 1. Créer une branche à partir de `main` ```text feature/xxx fix/xxx tech/xxx ``` 2. Implémenter la fonctionnalité ou la correction 3. Pousser la branche sur Forgejo 4. Créer une Merge Request vers main 5. La Merge Request doit : - Décrire la modification - Référencer les tickets Forgejo - Mentionner les impacts documentaires 6. La Merge Request est revue avant fusion --- ### 4.3 Règles de contribution - Toute nouvelle fonctionnalité doit être documentée - Toute modification technique structurante doit être documentée - Le README ne doit être modifié que si le démarrage du projet change - La documentation ne doit jamais anticiper des fonctionnalités non implémentées 4.4 Rôles des agents Claude - **architect** : analyse globale, orchestration - **backend-developer / frontend-developer** : implémentation - **backend-reviewer / frontend-reviewer** : revue - **documentation-manager** : mise à jour documentaire --- ## 5. Création de l’agent documentation-manager ### 5.1 Nom **documentation-manager** --- ### 5.2 Responsabilités - Identifier les impacts documentaires d’une demande - Mettre à jour les fichiers concernés - Maintenir la cohérence globale - Ne jamais modifier le code applicatif - Ne documenter que l’existant --- ### 5.3 Entrées - Spécification fonctionnelle ou technique - Résumé des changements implémentés - Structure documentaire actuelle --- ### 5.4 Sorties - Fichiers Markdown mis à jour - Liste des sections modifiées - Signalement des incohérences détectées --- ## 6. Orchestration des agents ### 6.1 Rôle de l’agent architect L’agent architect est responsable de : - Analyser la demande - Identifier les impacts - Code - Architecture - Documentation - Orchestrer les agents dans l’ordre suivant : architect → backend-developer / frontend-developer → backend-reviewer / frontend-reviewer -> test etc... → Et à la toute fin : documentation-manager --- ### 6.2 Règle obligatoire Une demande n’est considérée comme terminée que si : - l’agent documentation-manager a été exécuté - la documentation a été mise à jour si nécessaire --- ## 7. Bonnes pratiques documentaires - À faire - Être factuel - Être concis - Respecter la structure - Éviter les redondances À éviter - Dupliquer l’information - Mélanger fonctionnel et technique - Documenter des évolutions futures - Transformer la documentation en spécification --- ## 8. Critères de succès - Documentation toujours alignée avec le code - README clair et lisible en moins de 5 minutes - Installation détaillée accessible sans lire le code - Processus de contribution clair et reproductible --- ## 9. Évolutions futures possibles Validation documentaire en CI Génération automatique de changelog Publication de la documentation ---
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
No results found.
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference: ronan.quintin/Keryloo#13
No description provided.
Delete branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?