327 lines
16 KiB
Markdown
327 lines
16 KiB
Markdown
# AGENTS.md
|
||
|
||
## Table des matières
|
||
- [Introduction](#introduction)
|
||
- [Principes communs](#principes-communs)
|
||
- [Agents fondamentaux](#agents-fondamentaux)
|
||
- [Agents spécialisés documentation](#agents-spécialisés-documentation)
|
||
- [Agents spécialisés tests](#agents-spécialisés-tests)
|
||
- [Agents techniques](#agents-techniques)
|
||
- [Agents frontend](#agents-frontend)
|
||
- [Agents open source et CI](#agents-open-source-et-ci)
|
||
- [Agents de synchronisation et dérogations](#agents-de-synchronisation-et-d%C3%A9rogations)
|
||
- [Matrice de coordination](#matrice-de-coordination)
|
||
- [Conclusion](#conclusion)
|
||
|
||
---
|
||
|
||
## Introduction
|
||
Ce document définit les agents, leurs rôles et leurs responsabilités dans le projet `4NK/4NK_node` et, par extension, tout dépôt dérivé de `4NK_project_template`.
|
||
Il impose une coordination stricte entre code, documentation, tests, dépendances, CI/CD, synchronisation de template et gouvernance open source.
|
||
Les règles opérationnelles détaillées sont précisées dans `.cursor/rules/` (notamment `41-ssh-automation.mdc` et `42-template-sync.mdc`).
|
||
|
||
---
|
||
|
||
## Principes communs
|
||
- Langue exclusive : français.
|
||
- Pas d’exemples de code applicatif injectés dans la base.
|
||
- Toute contribution doit contenir une introduction et/ou une conclusion.
|
||
- Interdiction de secrets en clair dans le dépôt.
|
||
- Confirmation nécessaire avant `push` et `tag`.
|
||
- Toute modification impactant des éléments normatifs doit mettre à jour la documentation et le changelog.
|
||
- Le flux de publication applique un garde de release (tests/doc/build/alignement version/changelog/tag, latest vs wip).
|
||
|
||
---
|
||
|
||
## Agents fondamentaux
|
||
|
||
### Agent Fondation (Responsable)
|
||
**Missions**
|
||
- Garantir la conformité éditoriale : français, pas d’exemples applicatifs, introduction/conclusion.
|
||
- Vérifier la cohérence terminologique.
|
||
|
||
**Artefacts**
|
||
- Tous fichiers.
|
||
|
||
---
|
||
|
||
### Agent Structure (Responsable)
|
||
**Missions**
|
||
- Maintenir l’arborescence canonique (incluant `.cursor/`, `.gitea/`, `scripts/`, `docs/SSH_UPDATE.md`).
|
||
- Archiver le contenu obsolète dans `archive/` avec métadonnées.
|
||
- Interdire toute suppression non tracée.
|
||
|
||
**Artefacts**
|
||
- `archive/`, `docs/**`, `tests/**`, `.cursor/**`, `.gitea/**`, `scripts/**`, `CHANGELOG.md`.
|
||
|
||
---
|
||
|
||
## Agents spécialisés documentation
|
||
|
||
### Agent Documentation (Responsable)
|
||
**Missions**
|
||
- Mettre à jour `docs/**` selon l’impact des changements.
|
||
- Tenir `docs/INDEX.md` comme table des matières centrale.
|
||
- Produire des REX techniques dans `archive/` en cas d’investigations multiples.
|
||
|
||
**Artefacts**
|
||
- `docs/**`, `README.md`, `archive/**`.
|
||
|
||
---
|
||
|
||
### Agent Données CSV (Responsable)
|
||
**Missions**
|
||
- Traiter les CSV comme source des modèles de données (en-têtes multi-lignes inclus).
|
||
- Exiger une définition complète de toutes les colonnes.
|
||
- Corriger et documenter les incohérences de types.
|
||
|
||
**Artefacts**
|
||
- `docs/API.md`, `docs/ARCHITECTURE.md`, `docs/USAGE.md`.
|
||
|
||
---
|
||
|
||
### Agent Documents bureautiques (Consulté)
|
||
**Missions**
|
||
- Lire `.docx` via `docx2txt`; proposer des alternatives en cas d’échec.
|
||
- Documenter les imports dans `docs/INDEX.md`.
|
||
|
||
**Artefacts**
|
||
- `docs/**`, `archive/**`.
|
||
|
||
---
|
||
|
||
## Agents spécialisés tests
|
||
|
||
### Agent Tests (Responsable)
|
||
**Missions**
|
||
- Couvrir `unit`, `integration`, `connectivity`, `performance`, `external`.
|
||
- Gérer `tests/logs` et `tests/reports`.
|
||
- Exiger des tests verts avant commit.
|
||
|
||
**Artefacts**
|
||
- `tests/**`, `docs/TESTING.md`.
|
||
|
||
---
|
||
|
||
### Agent Performance (Consulté)
|
||
**Missions**
|
||
- Réaliser des benchmarks reproductibles.
|
||
- Valider l’impact performance avant fusion.
|
||
|
||
**Artefacts**
|
||
- `tests/performance/`, `tests/reports/`, `docs/TESTING.md`.
|
||
|
||
---
|
||
|
||
## Agents techniques
|
||
|
||
### Agent Qualité technique (Responsable)
|
||
**Missions**
|
||
- Définir et faire respecter les standards de qualité: lint, formatage, conventions de code, revues.
|
||
- Superviser l’analyse statique (types, duplication, complexité, sécurité basique) et corriger les écarts.
|
||
- Assurer l’exécution automatique des contrôles qualité dans la CI et bloquer en cas d’échec.
|
||
|
||
**Artefacts**
|
||
- `.gitea/workflows/ci.yml` (jobs de lint/format/type-check), `CHANGELOG.md`, `docs/ARCHITECTURE.md` (section standards).
|
||
|
||
---
|
||
|
||
### Agent Dépendances (Responsable)
|
||
**Missions**
|
||
- Ajouter les dépendances manquantes lorsque justifié.
|
||
- Vérifier les dernières versions stables.
|
||
- Documenter les impacts dans `ARCHITECTURE.md`, `CONFIGURATION.md`, `CHANGELOG.md`.
|
||
|
||
**Artefacts**
|
||
- `docs/ARCHITECTURE.md`, `docs/CONFIGURATION.md`, `CHANGELOG.md`.
|
||
|
||
---
|
||
|
||
### Agent Compilation (Responsable)
|
||
**Missions**
|
||
- Compiler très régulièrement et aux étapes critiques.
|
||
- Bloquer toute progression en cas d’erreurs de build/runtime.
|
||
|
||
**Artefacts**
|
||
- Artefacts de build, scripts d’outillage.
|
||
|
||
---
|
||
|
||
### Agent Résolution (Responsable)
|
||
**Missions**
|
||
- Conduire la boucle de diagnostic complète : reproduction minimale, logs, bissection, hypothèses, tests ciblés, correctif, non-régression.
|
||
- Produire un REX quand plusieurs hypothèses ont été testées.
|
||
|
||
**Artefacts**
|
||
- `tests/**`, `archive/**`
|
||
|
||
---
|
||
|
||
### Agent SSH & scripts (Responsable)
|
||
**Missions**
|
||
- Garantir la présence et l’usage correct de `scripts/auto-ssh-push.sh`, `scripts/init-ssh-env.sh`, `scripts/setup-ssh-ci.sh`.
|
||
- Assurer permissions d’exécution, idempotence, journalisation non sensible, gestion d’erreurs robuste.
|
||
- Interdire secrets en clair, gérer via secrets CI et variables d’environnement.
|
||
- Exiger la mise à jour de `docs/SSH_UPDATE.md` à toute évolution des scripts ou des flux SSH.
|
||
|
||
**Artefacts**
|
||
- `scripts/**`, `.gitea/workflows/ci.yml`, `docs/SSH_UPDATE.md`, `docs/CONFIGURATION.md`, `CHANGELOG.md`.
|
||
|
||
---
|
||
|
||
## Agents frontend
|
||
|
||
### Agent Frontend (Responsable)
|
||
**Missions**
|
||
- Mettre en place `React.lazy`/`Suspense` (code splitting).
|
||
- Centraliser l’état (Redux ou Context API).
|
||
- Abstraire les services de données.
|
||
|
||
**Artefacts**
|
||
- `docs/ARCHITECTURE.md`, `docs/TESTING.md`.
|
||
|
||
---
|
||
|
||
## Agents open source et CI
|
||
|
||
### Agent Open Source (Responsable)
|
||
**Missions**
|
||
- Maintenir : `LICENSE`, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `docs/OPEN_SOURCE_CHECKLIST.md`.
|
||
- Vérifier l’alignement continu avec `4NK_node`.
|
||
|
||
**Artefacts**
|
||
- Fichiers de gouvernance cités ci-dessus.
|
||
|
||
---
|
||
|
||
### Agent Gitea (Responsable)
|
||
**Missions**
|
||
- Garantir `.gitea/ISSUE_TEMPLATE/*`, `PULL_REQUEST_TEMPLATE.md`, `.gitea/workflows/ci.yml`.
|
||
- Documenter la configuration distante dans `docs/GITEA_SETUP.md`.
|
||
- Déclencher les étapes CI pertinentes (tests, lint, sécurité, vérifs `scripts/`).
|
||
|
||
**Artefacts**
|
||
- `.gitea/**`, `docs/GITEA_SETUP.md`.
|
||
|
||
---
|
||
|
||
### Agent Versionnage (Responsable)
|
||
**Missions**
|
||
- Tenir `CHANGELOG.md` comme source unique de vérité.
|
||
- Proposer un bump sémantique justifié.
|
||
- Demander confirmation avant push et tag.
|
||
- Orchestrer le `release-guard` (CI + scripts) et consigner latest vs wip.
|
||
|
||
**Artefacts**
|
||
- `CHANGELOG.md`, `docs/RELEASE_PLAN.md`, `docs/ROADMAP.md`.
|
||
|
||
---
|
||
|
||
### Agent Sécurité (Responsable)
|
||
**Missions**
|
||
- Assurer une vigilance continue sécurité sur le code, la config et la CI.
|
||
- Orchestrer l’audit de sécurité automatisé: `scripts/security/audit.sh` (cargo audit, npm audit, scan secrets).
|
||
- Interdire l’introduction de secrets en clair et exiger la rotation des secrets CI.
|
||
- Valider les permissions sensibles (clés, cookies, conf) et la non-exposition d’endpoints privés.
|
||
- Bloquer toute release si l’audit de sécurité échoue (intégré au `release-guard`).
|
||
|
||
**Artefacts**
|
||
- `scripts/security/audit.sh`, `.gitea/workflows/ci.yml` (job `security-audit`), `docs/SECURITY_AUDIT.md`, `docs/CONFIGURATION.md`.
|
||
|
||
---
|
||
|
||
### Agent Déploiement (Responsable)
|
||
**Missions**
|
||
- Définir et documenter la stratégie de déploiement (environnements, prérequis, secrets, rollbacks).
|
||
- Vérifier la présence et la cohérence des artefacts de déploiement et des variables d’environnement requises.
|
||
- Intégrer des contrôles CI « deployment-checks » avant toute release; coordonner avec `release-guard`.
|
||
|
||
**Artefacts**
|
||
- `docs/DEPLOYMENT.md`, `.gitea/workflows/ci.yml` (job `deployment-checks`), `CHANGELOG.md`, `docs/RELEASE_PLAN.md`.
|
||
|
||
---
|
||
|
||
### Agent Gouvernance du Template (Accountable)
|
||
**Missions**
|
||
- Garantir la cohérence d’ensemble du template (règles Cursor, CI, scripts, docs).
|
||
- Examiner les issues « Template Feedback », arbitrer et prioriser.
|
||
- Orchestrer la montée de version du template (`TEMPLATE_VERSION`) et le `CHANGELOG.md`.
|
||
- Communiquer les changements aux projets consommateurs.
|
||
|
||
**Artefacts**
|
||
- `.cursor/rules/**`, `.gitea_template/**`, `docs/TEMPLATE_*`, `TEMPLATE_VERSION`, `CHANGELOG.md`.
|
||
|
||
---
|
||
|
||
### Agent Adaptation Projet (Responsable)
|
||
**Missions**
|
||
- Accompagner l’adaptation locale du template (CI, docs, `AGENTS.md`).
|
||
- S’assurer que `security-audit` et `release-guard` ne sont pas retirés.
|
||
- Remonter en feedback toute amélioration générique.
|
||
|
||
**Artefacts**
|
||
- `.gitea/workflows/ci.yml`, `docs/INDEX.md`, `docs/SECURITY_AUDIT.md`, `AGENTS.md`, `LOCAL_OVERRIDES.yml` (si utilisé).
|
||
|
||
---
|
||
|
||
## Agents de synchronisation et dérogations
|
||
|
||
### Agent Synchronisation de template (Accountable)
|
||
**Références**
|
||
- `.4nk-sync.yml` (manifeste), `TEMPLATE_VERSION` (pointeur), `.gitea/workflows/template-sync.yml` (CI dédiée).
|
||
- Règles Cursor : `.cursor/rules/42-template-sync.mdc` et `.cursor/rules/10-project-structure.mdc`.
|
||
|
||
**Missions**
|
||
- Assurer l’alignement automatique sur le template pour : `.cursor/**`, `.gitea/**`, `AGENTS.md`, `scripts/**`, `docs/SSH_UPDATE.md`.
|
||
- Déclencher/valider la PR `[template-sync]` créée par la CI.
|
||
- Exiger la mise à jour de `CHANGELOG.md` et `docs/INDEX.md` après synchronisation.
|
||
- Vérifier l’intégrité (`manifest_checksum`, checksums de fichiers si publiés), les permissions, l’absence de secrets.
|
||
- Mettre à jour `TEMPLATE_VERSION` dans la PR.
|
||
|
||
**Artefacts**
|
||
- `.4nk-sync.yml`, `TEMPLATE_VERSION`, `.cursor/**`, `.gitea/**`, `AGENTS.md`, `scripts/**`, `docs/SSH_UPDATE.md`, `CHANGELOG.md`.
|
||
|
||
---
|
||
|
||
### Agent Dérogations locales (Responsable)
|
||
**Références**
|
||
- `LOCAL_OVERRIDES.yml` (facultatif, mais recommandé).
|
||
|
||
**Missions**
|
||
- Enregistrer toute divergence locale dans le périmètre synchronisé (path, raison, propriétaire, échéance).
|
||
- Faire respecter : seules les dérogations listées et non expirées sont tolérées par la CI.
|
||
- Auditer périodiquement et résorber les dérogations.
|
||
|
||
**Artefacts**
|
||
- `LOCAL_OVERRIDES.yml`, `CHANGELOG.md` (mentionner les dérogations significatives).
|
||
|
||
---
|
||
|
||
## Matrice de coordination
|
||
|
||
| Type de changement | Agents impliqués | Artefacts principaux | Validation obligatoire |
|
||
|----------------------------------|----------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------|------------------------|
|
||
| Ajout de fonctionnalité | Documentation, Tests, Dépendances, Frontend | `docs/API.md`, `docs/USAGE.md`, `docs/ARCHITECTURE.md`, `tests/unit`, `tests/integration`, `CHANGELOG.md` (*Added*) | Oui |
|
||
| Correction de bug | Résolution, Tests, Documentation | `tests/unit`, `docs/TESTING.md`, `archive/` (REX si nécessaire), `CHANGELOG.md` (*Fixed*) | Oui |
|
||
| Refactorisation / amélioration | Structure, Documentation, Compilation | `docs/ARCHITECTURE.md`, `archive/`, `CHANGELOG.md` (*Changed*) | Oui |
|
||
| Dépendance ajoutée/mise à jour | Dépendances, Compilation, Documentation | `docs/ARCHITECTURE.md`, `docs/CONFIGURATION.md`, `CHANGELOG.md` (*Dependencies*) | Oui |
|
||
| Données CSV modifiées | Données CSV, Documentation, Tests | `docs/API.md`, `docs/ARCHITECTURE.md`, `docs/USAGE.md`, `tests/unit`, `CHANGELOG.md` (*Data model update*) | Oui |
|
||
| Migration / breaking change | Documentation, Tests, Résolution, Versionnage | `docs/MIGRATION.md`, `docs/INSTALLATION.md`, `docs/RELEASE_PLAN.md`, `docs/ROADMAP.md`, `tests/integration`, `CHANGELOG.md` (*Breaking*) | Oui |
|
||
| Sécurité / audit | Documentation, Tests, Open Source, Sécurité proactive | `docs/SECURITY_AUDIT.md`, `tests/external`, `tests/connectivity`, `CHANGELOG.md` (*Security*) | Oui |
|
||
| Préparation open source / CI | Open Source, Gitea, Versionnage, Documentation communautaire, Contributeurs externes | `.gitea/**`, `docs/GITEA_SETUP.md`, `docs/OPEN_SOURCE_CHECKLIST.md`, `CHANGELOG.md` (*CI/CD* / *Governance*) | Oui |
|
||
| Optimisation performance | Performance, Tests, Documentation | `tests/performance`, `tests/reports`, `docs/ARCHITECTURE.md`, `CHANGELOG.md` (*Performance*) | Oui |
|
||
| Évolution frontend | Frontend, Documentation, Tests | `docs/ARCHITECTURE.md`, `docs/USAGE.md`, `tests/integration`, `CHANGELOG.md` (*Frontend*) | Oui |
|
||
| Évolution CI/CD ou scripts SSH | SSH & scripts, Gitea, Versionnage, Documentation | `scripts/**`, `.gitea/workflows/ci.yml`, `docs/SSH_UPDATE.md`, `docs/CONFIGURATION.md`, `CHANGELOG.md` (*CI/CD*) | Oui |
|
||
| Déploiement | Déploiement, Versionnage, Sécurité, Documentation | `docs/DEPLOYMENT.md`, `.gitea/workflows/ci.yml` (deployment-checks), `CHANGELOG.md` (*Deployment*) | Oui |
|
||
| **Synchronisation de template** | **Synchronisation de template**, Gitea, Versionnage, Structure, Documentation, SSH & scripts | `.4nk-sync.yml`, `TEMPLATE_VERSION`, `.cursor/**`, `.gitea/**`, `AGENTS.md`, `scripts/**`, `docs/SSH_UPDATE.md`, `CHANGELOG.md` | **Oui** |
|
||
| Dérogation locale contrôlée | Dérogations locales, Gitea, Synchronisation de template, Versionnage | `LOCAL_OVERRIDES.yml`, `CHANGELOG.md` (mention), CI tolérante uniquement sur chemins listés et non expirés | Oui |
|
||
|
||
---
|
||
|
||
## Requetes complexes
|
||
|
||
Quand tu fais une commande ou un requète complexe, explique là avant de la lancer.
|
||
|
||
## Conclusion
|
||
Ce `AGENTS.md` mis à jour introduit l’**Agent Synchronisation de template** et l’**Agent Dérogations locales**, renforce l’**Agent SSH & scripts**, et rattache l’ensemble aux règles Cursor et à la CI Gitea. La matrice de coordination formalise les validations obligatoires pour chaque type de changement, garantissant cohérence structurelle, qualité documentaire, sécurité, traçabilité et stabilité à long terme sur tous les projets issus de `4NK_project_template`.
|