create-gef 1.1.1 → 1.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.cursorrules +187 -0
- package/.windsurfrules +187 -0
- package/CHANGELOG.md +15 -0
- package/ENGINEERING_PLAYBOOK.md +3 -1
- package/ci-templates/pr-intention-check.yml +22 -0
- package/generator/features/scaffold-ai-rules.js +29 -0
- package/generator/index.js +2 -0
- package/hooks/pre-commit +9 -1
- package/package.json +1 -1
- package/prompts/system_prompt.md +2 -2
package/.cursorrules
ADDED
|
@@ -0,0 +1,187 @@
|
|
|
1
|
+
# 🛡️ GILDAS ENGINEERING FRAMEWORK (GEF) — RÈGLES COMPLÈTES POUR L'IA
|
|
2
|
+
# Référence absolue : ENGINEERING_PLAYBOOK.md
|
|
3
|
+
# Ce fichier est lu nativement par Cursor, Windsurf, et GitHub Copilot.
|
|
4
|
+
# Toute IA opérant sur ce projet doit lire, intérioriser et respecter CHACUNE de ces règles.
|
|
5
|
+
# Il n'est PAS nécessaire de demander à l'utilisateur ce que l'IA est censée faire :
|
|
6
|
+
# ce fichier est la réponse à toutes ces questions.
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## § 0. AVANT TOUTE ACTION — PROTOCOLE D'ENTRÉE
|
|
11
|
+
|
|
12
|
+
Avant d'écrire une seule ligne de code, l'IA DOIT :
|
|
13
|
+
|
|
14
|
+
1. **Identifier la phase du projet** : (Idée → R&D → Dev Contractuel → Release → Maintenance).
|
|
15
|
+
- Si R&D : les règles CI/CD sont souples, le code reste dans un dépôt `prototype` isolé.
|
|
16
|
+
- Si Contractuel/Production : les règles de tests, sécurité et CI/CD sont NON-NÉGOCIABLES dès le premier commit.
|
|
17
|
+
2. **Confirmer l'intention métier** : Ne jamais deviner le "Pourquoi". Si l'objectif métier n'est pas explicite, DEMANDER avant de coder.
|
|
18
|
+
3. **Vérifier la branche Git** : Ne JAMAIS travailler sur `main` ou `master`. Créer une branche (`git checkout -b feat/xxx` ou `fix/xxx`) si ce n'est pas déjà fait.
|
|
19
|
+
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
## § 1. CRASH CLAUSE — ZÉRO CONTOURNEMENT SILENCIEUX
|
|
23
|
+
|
|
24
|
+
> C'est la règle la plus importante du framework. Elle prévaut sur toutes les autres.
|
|
25
|
+
|
|
26
|
+
- **Face à une erreur, un obstacle ou une ambiguïté** : ARRÊTER IMMÉDIATEMENT et signaler le problème à l'utilisateur avec précision.
|
|
27
|
+
- **Ne JAMAIS improviser une solution de contournement (workaround) silencieuse** pour atteindre l'objectif coûte que coûte.
|
|
28
|
+
- **Si une commande échoue** : diagnostiquer la cause racine, documenter, et attendre une validation humaine avant de continuer.
|
|
29
|
+
- **Si une consigne est ambiguë** : poser la question plutôt que d'interpréter.
|
|
30
|
+
|
|
31
|
+
---
|
|
32
|
+
|
|
33
|
+
## § 2. CLEAN CODE — HARD LIMITS ABSOLUS
|
|
34
|
+
|
|
35
|
+
Ces limites sont non-négociables. L'IA ne peut JAMAIS générer du code qui les viole.
|
|
36
|
+
|
|
37
|
+
- **Fonctions / Méthodes** : `{{MAX_LINES}}` lignes max.
|
|
38
|
+
- **Paramètres** : `{{MAX_PARAMS}}` arguments max. Au-delà, utiliser un objet de configuration.
|
|
39
|
+
- **Complexité Cyclomatique** : `{{MAX_COMPLEXITY}}` chemins logiques max par fonction.
|
|
40
|
+
- **Nesting / Profondeur** : 3 niveaux max. Utiliser les **Guard Clauses (Early Return)** pour réduire le nesting.
|
|
41
|
+
- **Composants UI** : 150 à 200 lignes max. Logique > 50 lignes → extraire en Custom Hook.
|
|
42
|
+
- **Fichiers** : 300 à 400 lignes max.
|
|
43
|
+
- **Règle de 3** : 1ère duplication = OK. 2ème = toléré. 3ème = refactorisation en abstraction OBLIGATOIRE.
|
|
44
|
+
|
|
45
|
+
### Conventions de Nommage
|
|
46
|
+
- **Fichiers / Dossiers** : `kebab-case` (ex: `user-profile.tsx`)
|
|
47
|
+
- **Classes / Composants** : `PascalCase` (ex: `UserProfile`)
|
|
48
|
+
- **Variables / Fonctions** : `camelCase` (ex: `getUserData`)
|
|
49
|
+
- **Constantes Globales** : `UPPER_SNAKE_CASE` (ex: `MAX_RETRY_COUNT`)
|
|
50
|
+
- **Règle absolue** : Zéro warning de lint ignoré sans commentaire explicatif.
|
|
51
|
+
|
|
52
|
+
---
|
|
53
|
+
|
|
54
|
+
## § 3. ARCHITECTURE — CLEAN ARCHITECTURE & SOLID
|
|
55
|
+
|
|
56
|
+
- **Feature-Sliced Design (obligatoire)** : Organiser les dossiers par fonctionnalité métier, PAS par couche technique.
|
|
57
|
+
- ❌ Interdit : `/controllers`, `/models`, `/views`
|
|
58
|
+
- ✅ Correct : `/features/auth/api.ts`, `/features/auth/components/`, `/features/billing/model.ts`
|
|
59
|
+
- **SRP (Single Responsibility Principle)** : Une classe/fonction ne fait qu'une seule chose.
|
|
60
|
+
- **DIP (Dependency Inversion)** : Le domaine dépend d'interfaces, jamais d'implémentations concrètes.
|
|
61
|
+
|
|
62
|
+
---
|
|
63
|
+
|
|
64
|
+
## § 4. GESTION DES ERREURS — RESILIENCE
|
|
65
|
+
|
|
66
|
+
- **Information Hiding** : Ne JAMAIS exposer de stack traces ou détails techniques à l'utilisateur final. Renvoyer une erreur générique avec un ID de log.
|
|
67
|
+
- **Typage des Erreurs** : Créer des classes d'exceptions typées (`DomainError`, `InfraError`, `ValidationError`).
|
|
68
|
+
- **Result Pattern** : Remplacer les blocs `try/catch` massifs par `Result<Success, Failure>` pour forcer la gestion explicite de chaque échec.
|
|
69
|
+
|
|
70
|
+
---
|
|
71
|
+
|
|
72
|
+
## § 5. SÉCURITÉ — OWASP HARD LIMITS
|
|
73
|
+
|
|
74
|
+
*"La complexité est l'ennemie de la sécurité."*
|
|
75
|
+
|
|
76
|
+
- **Zero Trust** : Ne jamais faire confiance aux entrées utilisateur. Validation stricte à toutes les frontières (ex: `Zod`, `Joi`).
|
|
77
|
+
- **Fail-Safe Defaults** : Tout accès est REFUSÉ par défaut. On accorde explicitement les permissions.
|
|
78
|
+
- **Protection SQLi** : Requêtes paramétrées OBLIGATOIRES. Aucune requête SQL dynamique non-paramétrée.
|
|
79
|
+
- **Protection XSS** : Encodage des données à la sortie.
|
|
80
|
+
|
|
81
|
+
### Limites Dures
|
|
82
|
+
| Paramètre | Limite |
|
|
83
|
+
|-----------|--------|
|
|
84
|
+
| Access Token (JWT) | 15 minutes max |
|
|
85
|
+
| Refresh Token | 7 jours max (cookie `HttpOnly`) |
|
|
86
|
+
| Corps de requête API (JSON) | `{{MAX_PAYLOAD}}` max |
|
|
87
|
+
| Upload d'image/fichier | 5 Mo max |
|
|
88
|
+
| Tentatives de connexion échouées | Blocage 15 min après 5 échecs |
|
|
89
|
+
| Limite globale API | 100 requêtes / minute / IP |
|
|
90
|
+
| Secrets | Toujours via `.env`. JAMAIS hardcodés. |
|
|
91
|
+
|
|
92
|
+
---
|
|
93
|
+
|
|
94
|
+
## § 6. STRATÉGIE GIT — GITHUB FLOW
|
|
95
|
+
|
|
96
|
+
- **Branche `main` = intouchable** : Pushes directs STRICTEMENT INTERDITS.
|
|
97
|
+
- **Branches courtes** : `feat/xxx`, `fix/xxx`, `docs/xxx`. Durée de vie max : quelques jours.
|
|
98
|
+
- **Une action = Un commit** : Ne jamais grouper la création d'un fichier et sa modification dans le même commit.
|
|
99
|
+
- **Pull Requests (PR) obligatoires** : Tout code passe par une PR. La CI doit être verte avant merge.
|
|
100
|
+
- **Revue de code** : Une approbation humaine est requise. L'IA prépare la PR mais NE MERGE JAMAIS elle-même.
|
|
101
|
+
- **Conventional Commits (strict)** :
|
|
102
|
+
- Format : `type: description courte (#ticket-kanban)`
|
|
103
|
+
- Types : `feat:`, `fix:`, `docs:`, `chore:`, `refactor:`, `style:`, `test:`
|
|
104
|
+
- Exemple : `feat: ajout de l'authentification OAuth (#42)`
|
|
105
|
+
|
|
106
|
+
---
|
|
107
|
+
|
|
108
|
+
## § 7. DOCUMENTATION — DIÁTAXIS & DOCS-AS-CODE
|
|
109
|
+
|
|
110
|
+
- **Commenter le POURQUOI** : Les commentaires expliquent l'intention, pas l'implémentation.
|
|
111
|
+
- **Structure Diátaxis** (dossier `docs/`) :
|
|
112
|
+
- `docs/tutorials/` → Prise en main
|
|
113
|
+
- `docs/how-to/` → Guides de tâches spécifiques
|
|
114
|
+
- `docs/reference/` → API, DB, schémas
|
|
115
|
+
- `docs/explanation/adr/` → Architecture Decision Records (ADR)
|
|
116
|
+
- **ADR obligatoire** : Toute décision architecturale majeure (changement de DB, framework, cloud...) nécessite un fichier ADR dans `docs/explanation/adr/ADR-XXX-titre.md`.
|
|
117
|
+
- **RESEARCH_LOG obligatoire** : Tout bug critique résolu doit être documenté dans `docs/research/RESEARCH_LOG.md` avec : Symptôme / Cause Racine / Résolution / Leçon apprise.
|
|
118
|
+
- **Modèle C4** : L'architecture est visualisée et versionnée via Mermaid.js (Contexte, Conteneurs, Composants).
|
|
119
|
+
|
|
120
|
+
---
|
|
121
|
+
|
|
122
|
+
## § 8. ASSURANCE QUALITÉ — TEST PYRAMID & SHIFT-LEFT
|
|
123
|
+
|
|
124
|
+
- **Shift-Left** : La réflexion sur les tests commence dès l'écriture des spécifications, avant le code.
|
|
125
|
+
- **BDD obligatoire** : Les tests d'intégration et E2E suivent la syntaxe `Given / When / Then`.
|
|
126
|
+
- **Pyramide des tests** :
|
|
127
|
+
- 🟢 **80%** de Tests Unitaires (rapides, sans DB, ciblent la logique métier).
|
|
128
|
+
- 🟡 **15%** de Tests d'Intégration (valident DB / API).
|
|
129
|
+
- 🔴 **5%** de Tests E2E Playwright (lents, fragiles — ne pas en abuser).
|
|
130
|
+
- **TDD pour les features** : Écrire le test E2E décrivant le comportement AVANT d'écrire le code métier.
|
|
131
|
+
|
|
132
|
+
---
|
|
133
|
+
|
|
134
|
+
## § 9. MÉTHODOLOGIE PAS-À-PAS — PILOTAGE & AUTONOMIE
|
|
135
|
+
|
|
136
|
+
- **Cycle de travail** : `Propose → Explique → Implémente → Commite → Valide`. Jamais de larges blocs d'un coup.
|
|
137
|
+
- **Découpage en Issues** : Utiliser `gh issue create` pour transformer un grand chantier en sous-tâches traçables.
|
|
138
|
+
- **Création de PR** : Utiliser `gh pr create` avec la mention `Closes #XYZ` et une description incluant l'intention métier.
|
|
139
|
+
- **Zéro Scories** : Scripts de debug, fichiers temporaires et commentaires "commentés" sont supprimés AVANT tout push.
|
|
140
|
+
- **Séparation R&D** : Les expérimentations sans cahier des charges vivent dans un dépôt privé séparé. L'historique Git officiel reste propre.
|
|
141
|
+
|
|
142
|
+
---
|
|
143
|
+
|
|
144
|
+
## § 10. WORKFLOWS CONTEXTUELS — COMPORTEMENT SELON LA TÂCHE
|
|
145
|
+
|
|
146
|
+
### Kickoff d'un nouveau projet
|
|
147
|
+
1. Demander : "Ce projet est-il R&D ou Contractuel/Production ?"
|
|
148
|
+
2. Aider à remplir `PROJECT_CONFIG.md`.
|
|
149
|
+
3. Proposer la structure Feature-Sliced Design.
|
|
150
|
+
4. Créer `docs/` avec les 4 quadrants Diátaxis.
|
|
151
|
+
5. Préparer le workflow GitHub Actions (Lint, Tests, Sécurité) dès le premier jour.
|
|
152
|
+
6. Premier commit : `chore: initialisation du projet via GEF (structure, CI/CD, docs)`
|
|
153
|
+
|
|
154
|
+
### Développement d'une Feature
|
|
155
|
+
1. Créer un ticket `gh issue create`.
|
|
156
|
+
2. Créer une branche `feat/xxx`.
|
|
157
|
+
3. Écrire le test BDD AVANT le code (TDD).
|
|
158
|
+
4. Micro-commits fréquents avec `feat: ... (#ticket)`.
|
|
159
|
+
5. Ouvrir une PR avec `gh pr create` et demander le merge à l'utilisateur.
|
|
160
|
+
|
|
161
|
+
### Résolution d'un Bug
|
|
162
|
+
1. **Reproduire** le bug de manière isolée. Ne rien modifier avant de comprendre la cause racine.
|
|
163
|
+
2. Évaluer l'impact sécurité en priorité absolue.
|
|
164
|
+
3. Corriger avec un commit `fix: ... (#ticket)`.
|
|
165
|
+
4. Écrire ou mettre à jour un test couvrant le scénario.
|
|
166
|
+
5. Documenter dans `RESEARCH_LOG.md` OBLIGATOIREMENT.
|
|
167
|
+
|
|
168
|
+
### Revue de Code (checklist avant tout merge)
|
|
169
|
+
- [ ] Hard Limits respectées (lignes, paramètres, complexité, nesting) ?
|
|
170
|
+
- [ ] Feature-Sliced Design respecté ?
|
|
171
|
+
- [ ] SRP respecté (une seule responsabilité par classe/fonction) ?
|
|
172
|
+
- [ ] Entrées validées (Zod/Joi) ? Pas de SQL dynamique ? Pas de secrets hardcodés ?
|
|
173
|
+
- [ ] Tests unitaires couvrent la logique nouvelle/modifiée ?
|
|
174
|
+
- [ ] Conventional Commits avec ID ticket ?
|
|
175
|
+
- [ ] ADR créé si décision architecturale majeure ?
|
|
176
|
+
- [ ] Code commenté sur l'INTENTION (le pourquoi), pas le quoi ?
|
|
177
|
+
- **Si un point échoue → bloquer le merge et proposer le correctif.**
|
|
178
|
+
|
|
179
|
+
### Rédaction d'un ADR
|
|
180
|
+
- Fichier : `docs/explanation/adr/ADR-XXX-titre_descriptif.md`
|
|
181
|
+
- Structure : Contexte / Options Considérées / Décision / Conséquences / Diagramme Mermaid (si applicable)
|
|
182
|
+
- Commit dédié : `docs(adr): création ADR-XXX — [titre] (#ticket)`
|
|
183
|
+
- ⚠️ Ne PAS consigner les ADR dans le RESEARCH_LOG (réservé aux bugs).
|
|
184
|
+
|
|
185
|
+
---
|
|
186
|
+
|
|
187
|
+
*Ce fichier est la loi fondamentale du GEF. Il garantit un niveau d'ingénierie DORA "Elite" sur tous les projets.*
|
package/.windsurfrules
ADDED
|
@@ -0,0 +1,187 @@
|
|
|
1
|
+
# 🛡️ GILDAS ENGINEERING FRAMEWORK (GEF) — RÈGLES COMPLÈTES POUR L'IA
|
|
2
|
+
# Référence absolue : ENGINEERING_PLAYBOOK.md
|
|
3
|
+
# Ce fichier est lu nativement par Cursor, Windsurf, et GitHub Copilot.
|
|
4
|
+
# Toute IA opérant sur ce projet doit lire, intérioriser et respecter CHACUNE de ces règles.
|
|
5
|
+
# Il n'est PAS nécessaire de demander à l'utilisateur ce que l'IA est censée faire :
|
|
6
|
+
# ce fichier est la réponse à toutes ces questions.
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## § 0. AVANT TOUTE ACTION — PROTOCOLE D'ENTRÉE
|
|
11
|
+
|
|
12
|
+
Avant d'écrire une seule ligne de code, l'IA DOIT :
|
|
13
|
+
|
|
14
|
+
1. **Identifier la phase du projet** : (Idée → R&D → Dev Contractuel → Release → Maintenance).
|
|
15
|
+
- Si R&D : les règles CI/CD sont souples, le code reste dans un dépôt `prototype` isolé.
|
|
16
|
+
- Si Contractuel/Production : les règles de tests, sécurité et CI/CD sont NON-NÉGOCIABLES dès le premier commit.
|
|
17
|
+
2. **Confirmer l'intention métier** : Ne jamais deviner le "Pourquoi". Si l'objectif métier n'est pas explicite, DEMANDER avant de coder.
|
|
18
|
+
3. **Vérifier la branche Git** : Ne JAMAIS travailler sur `main` ou `master`. Créer une branche (`git checkout -b feat/xxx` ou `fix/xxx`) si ce n'est pas déjà fait.
|
|
19
|
+
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
## § 1. CRASH CLAUSE — ZÉRO CONTOURNEMENT SILENCIEUX
|
|
23
|
+
|
|
24
|
+
> C'est la règle la plus importante du framework. Elle prévaut sur toutes les autres.
|
|
25
|
+
|
|
26
|
+
- **Face à une erreur, un obstacle ou une ambiguïté** : ARRÊTER IMMÉDIATEMENT et signaler le problème à l'utilisateur avec précision.
|
|
27
|
+
- **Ne JAMAIS improviser une solution de contournement (workaround) silencieuse** pour atteindre l'objectif coûte que coûte.
|
|
28
|
+
- **Si une commande échoue** : diagnostiquer la cause racine, documenter, et attendre une validation humaine avant de continuer.
|
|
29
|
+
- **Si une consigne est ambiguë** : poser la question plutôt que d'interpréter.
|
|
30
|
+
|
|
31
|
+
---
|
|
32
|
+
|
|
33
|
+
## § 2. CLEAN CODE — HARD LIMITS ABSOLUS
|
|
34
|
+
|
|
35
|
+
Ces limites sont non-négociables. L'IA ne peut JAMAIS générer du code qui les viole.
|
|
36
|
+
|
|
37
|
+
- **Fonctions / Méthodes** : `{{MAX_LINES}}` lignes max.
|
|
38
|
+
- **Paramètres** : `{{MAX_PARAMS}}` arguments max. Au-delà, utiliser un objet de configuration.
|
|
39
|
+
- **Complexité Cyclomatique** : `{{MAX_COMPLEXITY}}` chemins logiques max par fonction.
|
|
40
|
+
- **Nesting / Profondeur** : 3 niveaux max. Utiliser les **Guard Clauses (Early Return)** pour réduire le nesting.
|
|
41
|
+
- **Composants UI** : 150 à 200 lignes max. Logique > 50 lignes → extraire en Custom Hook.
|
|
42
|
+
- **Fichiers** : 300 à 400 lignes max.
|
|
43
|
+
- **Règle de 3** : 1ère duplication = OK. 2ème = toléré. 3ème = refactorisation en abstraction OBLIGATOIRE.
|
|
44
|
+
|
|
45
|
+
### Conventions de Nommage
|
|
46
|
+
- **Fichiers / Dossiers** : `kebab-case` (ex: `user-profile.tsx`)
|
|
47
|
+
- **Classes / Composants** : `PascalCase` (ex: `UserProfile`)
|
|
48
|
+
- **Variables / Fonctions** : `camelCase` (ex: `getUserData`)
|
|
49
|
+
- **Constantes Globales** : `UPPER_SNAKE_CASE` (ex: `MAX_RETRY_COUNT`)
|
|
50
|
+
- **Règle absolue** : Zéro warning de lint ignoré sans commentaire explicatif.
|
|
51
|
+
|
|
52
|
+
---
|
|
53
|
+
|
|
54
|
+
## § 3. ARCHITECTURE — CLEAN ARCHITECTURE & SOLID
|
|
55
|
+
|
|
56
|
+
- **Feature-Sliced Design (obligatoire)** : Organiser les dossiers par fonctionnalité métier, PAS par couche technique.
|
|
57
|
+
- ❌ Interdit : `/controllers`, `/models`, `/views`
|
|
58
|
+
- ✅ Correct : `/features/auth/api.ts`, `/features/auth/components/`, `/features/billing/model.ts`
|
|
59
|
+
- **SRP (Single Responsibility Principle)** : Une classe/fonction ne fait qu'une seule chose.
|
|
60
|
+
- **DIP (Dependency Inversion)** : Le domaine dépend d'interfaces, jamais d'implémentations concrètes.
|
|
61
|
+
|
|
62
|
+
---
|
|
63
|
+
|
|
64
|
+
## § 4. GESTION DES ERREURS — RESILIENCE
|
|
65
|
+
|
|
66
|
+
- **Information Hiding** : Ne JAMAIS exposer de stack traces ou détails techniques à l'utilisateur final. Renvoyer une erreur générique avec un ID de log.
|
|
67
|
+
- **Typage des Erreurs** : Créer des classes d'exceptions typées (`DomainError`, `InfraError`, `ValidationError`).
|
|
68
|
+
- **Result Pattern** : Remplacer les blocs `try/catch` massifs par `Result<Success, Failure>` pour forcer la gestion explicite de chaque échec.
|
|
69
|
+
|
|
70
|
+
---
|
|
71
|
+
|
|
72
|
+
## § 5. SÉCURITÉ — OWASP HARD LIMITS
|
|
73
|
+
|
|
74
|
+
*"La complexité est l'ennemie de la sécurité."*
|
|
75
|
+
|
|
76
|
+
- **Zero Trust** : Ne jamais faire confiance aux entrées utilisateur. Validation stricte à toutes les frontières (ex: `Zod`, `Joi`).
|
|
77
|
+
- **Fail-Safe Defaults** : Tout accès est REFUSÉ par défaut. On accorde explicitement les permissions.
|
|
78
|
+
- **Protection SQLi** : Requêtes paramétrées OBLIGATOIRES. Aucune requête SQL dynamique non-paramétrée.
|
|
79
|
+
- **Protection XSS** : Encodage des données à la sortie.
|
|
80
|
+
|
|
81
|
+
### Limites Dures
|
|
82
|
+
| Paramètre | Limite |
|
|
83
|
+
|-----------|--------|
|
|
84
|
+
| Access Token (JWT) | 15 minutes max |
|
|
85
|
+
| Refresh Token | 7 jours max (cookie `HttpOnly`) |
|
|
86
|
+
| Corps de requête API (JSON) | `{{MAX_PAYLOAD}}` max |
|
|
87
|
+
| Upload d'image/fichier | 5 Mo max |
|
|
88
|
+
| Tentatives de connexion échouées | Blocage 15 min après 5 échecs |
|
|
89
|
+
| Limite globale API | 100 requêtes / minute / IP |
|
|
90
|
+
| Secrets | Toujours via `.env`. JAMAIS hardcodés. |
|
|
91
|
+
|
|
92
|
+
---
|
|
93
|
+
|
|
94
|
+
## § 6. STRATÉGIE GIT — GITHUB FLOW
|
|
95
|
+
|
|
96
|
+
- **Branche `main` = intouchable** : Pushes directs STRICTEMENT INTERDITS.
|
|
97
|
+
- **Branches courtes** : `feat/xxx`, `fix/xxx`, `docs/xxx`. Durée de vie max : quelques jours.
|
|
98
|
+
- **Une action = Un commit** : Ne jamais grouper la création d'un fichier et sa modification dans le même commit.
|
|
99
|
+
- **Pull Requests (PR) obligatoires** : Tout code passe par une PR. La CI doit être verte avant merge.
|
|
100
|
+
- **Revue de code** : Une approbation humaine est requise. L'IA prépare la PR mais NE MERGE JAMAIS elle-même.
|
|
101
|
+
- **Conventional Commits (strict)** :
|
|
102
|
+
- Format : `type: description courte (#ticket-kanban)`
|
|
103
|
+
- Types : `feat:`, `fix:`, `docs:`, `chore:`, `refactor:`, `style:`, `test:`
|
|
104
|
+
- Exemple : `feat: ajout de l'authentification OAuth (#42)`
|
|
105
|
+
|
|
106
|
+
---
|
|
107
|
+
|
|
108
|
+
## § 7. DOCUMENTATION — DIÁTAXIS & DOCS-AS-CODE
|
|
109
|
+
|
|
110
|
+
- **Commenter le POURQUOI** : Les commentaires expliquent l'intention, pas l'implémentation.
|
|
111
|
+
- **Structure Diátaxis** (dossier `docs/`) :
|
|
112
|
+
- `docs/tutorials/` → Prise en main
|
|
113
|
+
- `docs/how-to/` → Guides de tâches spécifiques
|
|
114
|
+
- `docs/reference/` → API, DB, schémas
|
|
115
|
+
- `docs/explanation/adr/` → Architecture Decision Records (ADR)
|
|
116
|
+
- **ADR obligatoire** : Toute décision architecturale majeure (changement de DB, framework, cloud...) nécessite un fichier ADR dans `docs/explanation/adr/ADR-XXX-titre.md`.
|
|
117
|
+
- **RESEARCH_LOG obligatoire** : Tout bug critique résolu doit être documenté dans `docs/research/RESEARCH_LOG.md` avec : Symptôme / Cause Racine / Résolution / Leçon apprise.
|
|
118
|
+
- **Modèle C4** : L'architecture est visualisée et versionnée via Mermaid.js (Contexte, Conteneurs, Composants).
|
|
119
|
+
|
|
120
|
+
---
|
|
121
|
+
|
|
122
|
+
## § 8. ASSURANCE QUALITÉ — TEST PYRAMID & SHIFT-LEFT
|
|
123
|
+
|
|
124
|
+
- **Shift-Left** : La réflexion sur les tests commence dès l'écriture des spécifications, avant le code.
|
|
125
|
+
- **BDD obligatoire** : Les tests d'intégration et E2E suivent la syntaxe `Given / When / Then`.
|
|
126
|
+
- **Pyramide des tests** :
|
|
127
|
+
- 🟢 **80%** de Tests Unitaires (rapides, sans DB, ciblent la logique métier).
|
|
128
|
+
- 🟡 **15%** de Tests d'Intégration (valident DB / API).
|
|
129
|
+
- 🔴 **5%** de Tests E2E Playwright (lents, fragiles — ne pas en abuser).
|
|
130
|
+
- **TDD pour les features** : Écrire le test E2E décrivant le comportement AVANT d'écrire le code métier.
|
|
131
|
+
|
|
132
|
+
---
|
|
133
|
+
|
|
134
|
+
## § 9. MÉTHODOLOGIE PAS-À-PAS — PILOTAGE & AUTONOMIE
|
|
135
|
+
|
|
136
|
+
- **Cycle de travail** : `Propose → Explique → Implémente → Commite → Valide`. Jamais de larges blocs d'un coup.
|
|
137
|
+
- **Découpage en Issues** : Utiliser `gh issue create` pour transformer un grand chantier en sous-tâches traçables.
|
|
138
|
+
- **Création de PR** : Utiliser `gh pr create` avec la mention `Closes #XYZ` et une description incluant l'intention métier.
|
|
139
|
+
- **Zéro Scories** : Scripts de debug, fichiers temporaires et commentaires "commentés" sont supprimés AVANT tout push.
|
|
140
|
+
- **Séparation R&D** : Les expérimentations sans cahier des charges vivent dans un dépôt privé séparé. L'historique Git officiel reste propre.
|
|
141
|
+
|
|
142
|
+
---
|
|
143
|
+
|
|
144
|
+
## § 10. WORKFLOWS CONTEXTUELS — COMPORTEMENT SELON LA TÂCHE
|
|
145
|
+
|
|
146
|
+
### Kickoff d'un nouveau projet
|
|
147
|
+
1. Demander : "Ce projet est-il R&D ou Contractuel/Production ?"
|
|
148
|
+
2. Aider à remplir `PROJECT_CONFIG.md`.
|
|
149
|
+
3. Proposer la structure Feature-Sliced Design.
|
|
150
|
+
4. Créer `docs/` avec les 4 quadrants Diátaxis.
|
|
151
|
+
5. Préparer le workflow GitHub Actions (Lint, Tests, Sécurité) dès le premier jour.
|
|
152
|
+
6. Premier commit : `chore: initialisation du projet via GEF (structure, CI/CD, docs)`
|
|
153
|
+
|
|
154
|
+
### Développement d'une Feature
|
|
155
|
+
1. Créer un ticket `gh issue create`.
|
|
156
|
+
2. Créer une branche `feat/xxx`.
|
|
157
|
+
3. Écrire le test BDD AVANT le code (TDD).
|
|
158
|
+
4. Micro-commits fréquents avec `feat: ... (#ticket)`.
|
|
159
|
+
5. Ouvrir une PR avec `gh pr create` et demander le merge à l'utilisateur.
|
|
160
|
+
|
|
161
|
+
### Résolution d'un Bug
|
|
162
|
+
1. **Reproduire** le bug de manière isolée. Ne rien modifier avant de comprendre la cause racine.
|
|
163
|
+
2. Évaluer l'impact sécurité en priorité absolue.
|
|
164
|
+
3. Corriger avec un commit `fix: ... (#ticket)`.
|
|
165
|
+
4. Écrire ou mettre à jour un test couvrant le scénario.
|
|
166
|
+
5. Documenter dans `RESEARCH_LOG.md` OBLIGATOIREMENT.
|
|
167
|
+
|
|
168
|
+
### Revue de Code (checklist avant tout merge)
|
|
169
|
+
- [ ] Hard Limits respectées (lignes, paramètres, complexité, nesting) ?
|
|
170
|
+
- [ ] Feature-Sliced Design respecté ?
|
|
171
|
+
- [ ] SRP respecté (une seule responsabilité par classe/fonction) ?
|
|
172
|
+
- [ ] Entrées validées (Zod/Joi) ? Pas de SQL dynamique ? Pas de secrets hardcodés ?
|
|
173
|
+
- [ ] Tests unitaires couvrent la logique nouvelle/modifiée ?
|
|
174
|
+
- [ ] Conventional Commits avec ID ticket ?
|
|
175
|
+
- [ ] ADR créé si décision architecturale majeure ?
|
|
176
|
+
- [ ] Code commenté sur l'INTENTION (le pourquoi), pas le quoi ?
|
|
177
|
+
- **Si un point échoue → bloquer le merge et proposer le correctif.**
|
|
178
|
+
|
|
179
|
+
### Rédaction d'un ADR
|
|
180
|
+
- Fichier : `docs/explanation/adr/ADR-XXX-titre_descriptif.md`
|
|
181
|
+
- Structure : Contexte / Options Considérées / Décision / Conséquences / Diagramme Mermaid (si applicable)
|
|
182
|
+
- Commit dédié : `docs(adr): création ADR-XXX — [titre] (#ticket)`
|
|
183
|
+
- ⚠️ Ne PAS consigner les ADR dans le RESEARCH_LOG (réservé aux bugs).
|
|
184
|
+
|
|
185
|
+
---
|
|
186
|
+
|
|
187
|
+
*Ce fichier est la loi fondamentale du GEF. Il garantit un niveau d'ingénierie DORA "Elite" sur tous les projets.*
|
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,20 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## [1.2.0](https://github.com/Gnzikoune/GEF/compare/v1.1.1...v1.2.0) (2026-07-21)
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
### Features
|
|
7
|
+
|
|
8
|
+
* ajout des regles cursor et IDE IA lors du scaffold ([#4](https://github.com/Gnzikoune/GEF/issues/4)) ([b9fa757](https://github.com/Gnzikoune/GEF/commit/b9fa75744fa8229ca31c6c0d93dc16e18bd947f2))
|
|
9
|
+
* ajout des regles IA globales au framework lui-meme ([#6](https://github.com/Gnzikoune/GEF/issues/6)) ([e4c32b5](https://github.com/Gnzikoune/GEF/commit/e4c32b5bfbb4fffeed782c1d0ebb0d33d3573452))
|
|
10
|
+
* ajout du verrouillage de la branche main dans le hook pre-commi… ([61513df](https://github.com/Gnzikoune/GEF/commit/61513dfabe876cbb5e71a1ea35bbd4bbf296d469))
|
|
11
|
+
* ajout du verrouillage de la branche main dans le hook pre-commit ([#3](https://github.com/Gnzikoune/GEF/issues/3)) ([9f76e4f](https://github.com/Gnzikoune/GEF/commit/9f76e4f11a9edfe1dfeb8481351331b4b18339df))
|
|
12
|
+
* ajout du workflow CI forcant l intention dans la PR ([#5](https://github.com/Gnzikoune/GEF/issues/5)) ([389a31a](https://github.com/Gnzikoune/GEF/commit/389a31a63b7c7029cd8c02d4f1721a5a06b30ba0))
|
|
13
|
+
* cursorrules completement refait avec toutes les regles GEF + source unique de verite ([#8](https://github.com/Gnzikoune/GEF/issues/8)) ([bc50b69](https://github.com/Gnzikoune/GEF/commit/bc50b69758b8fa8d8c158c00f5bd1d4e3c02708c))
|
|
14
|
+
* cursorrules complets - toutes les regles GEF injectees nativement dans les IDEs IA ([60fefcf](https://github.com/Gnzikoune/GEF/commit/60fefcf6d6156f90e88207a89264ef468c52c732))
|
|
15
|
+
* integration de toutes les regles du playbook dans les cursorrules ([#7](https://github.com/Gnzikoune/GEF/issues/7)) ([888feae](https://github.com/Gnzikoune/GEF/commit/888feaefb71901570c18781736537e3b912c85b4))
|
|
16
|
+
* workflow CI qui bloque les PR sans intention metier declaree ([bee28e3](https://github.com/Gnzikoune/GEF/commit/bee28e322613abbb95b7adec2f3d8beb3ffaa013))
|
|
17
|
+
|
|
3
18
|
## [1.1.1](https://github.com/Gnzikoune/GEF/compare/v1.1.0...v1.1.1) (2026-07-20)
|
|
4
19
|
|
|
5
20
|
|
package/ENGINEERING_PLAYBOOK.md
CHANGED
|
@@ -123,10 +123,12 @@ La qualité s'injecte avant le code, pas après.
|
|
|
123
123
|
|
|
124
124
|
## 8. Pilotage Kanban et Autonomie de l'IA
|
|
125
125
|
|
|
126
|
-
L'IA agit comme un Tech Lead autonome.
|
|
126
|
+
L'IA agit comme un Tech Lead autonome, mais sous le contrôle strict de l'intention métier.
|
|
127
|
+
- **Le "Pourquoi" avant tout :** Chaque Issue, PR ou tâche doit obligatoirement commencer par expliciter le but ultime (l'intention métier). L'IA ne doit pas deviner le but, elle doit le suivre.
|
|
127
128
|
- **Découpage en Issues :** Utiliser la CLI GitHub (`gh issue create`) pour découper un grand chantier en sous-tâches.
|
|
128
129
|
- **Création de Pull Requests (PR) :** Si des branches temporaires sont requises pour une revue par l'utilisateur, utiliser `gh pr create`.
|
|
129
130
|
- **Validation Humaine Obligatoire :** L'IA ne merge **JAMAIS** de Pull Request elle-même. Elle prépare tout et demande à l'utilisateur de cliquer sur le bouton de Merge.
|
|
131
|
+
- **Crash Clause Anti-Contournement :** Face à un mur (erreur technique, consigne ambiguë, outil manquant), l'IA doit échouer bruyamment (Fail Fast) et s'arrêter pour demander de l'aide à l'utilisateur, plutôt que d'improviser une solution toxique ou de masquer l'erreur en silence.
|
|
130
132
|
|
|
131
133
|
---
|
|
132
134
|
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
name: Intention Check (Anti-Bypass)
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
pull_request:
|
|
5
|
+
types: [opened, edited, synchronize]
|
|
6
|
+
|
|
7
|
+
jobs:
|
|
8
|
+
check-intention:
|
|
9
|
+
runs-on: ubuntu-latest
|
|
10
|
+
steps:
|
|
11
|
+
- name: Vérifier la présence du Pourquoi
|
|
12
|
+
run: |
|
|
13
|
+
BODY="${{ github.event.pull_request.body }}"
|
|
14
|
+
|
|
15
|
+
if echo "$BODY" | grep -iqE "(intention|pourquoi)"; then
|
|
16
|
+
echo "✅ Intention détectée dans la description de la PR."
|
|
17
|
+
exit 0
|
|
18
|
+
else
|
|
19
|
+
echo "❌ ERREUR: Le Playbook GEF exige que chaque Pull Request explique explicitement le 'Pourquoi' (l'intention métier)."
|
|
20
|
+
echo "Veuillez modifier la description de votre Pull Request pour y inclure un bloc décrivant votre intention."
|
|
21
|
+
exit 1
|
|
22
|
+
fi
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
import fs from 'fs';
|
|
2
|
+
import path from 'path';
|
|
3
|
+
import chalk from 'chalk';
|
|
4
|
+
|
|
5
|
+
export function scaffoldAiRules(gefDir, projectPath) {
|
|
6
|
+
console.log(chalk.blue('Configuration des barrières de sécurité IA (.cursorrules)...'));
|
|
7
|
+
|
|
8
|
+
// Source unique de vérité : le .cursorrules du framework GEF lui-même
|
|
9
|
+
const sourceRulesPath = path.join(gefDir, '.cursorrules');
|
|
10
|
+
|
|
11
|
+
if (!fs.existsSync(sourceRulesPath)) {
|
|
12
|
+
console.warn(chalk.yellow('Avertissement: .cursorrules source introuvable dans le répertoire GEF. Les règles IA ne seront pas copiées.'));
|
|
13
|
+
return;
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
const aiRulesContent = fs.readFileSync(sourceRulesPath, 'utf-8');
|
|
17
|
+
|
|
18
|
+
// Écriture pour Cursor et Windsurf
|
|
19
|
+
fs.writeFileSync(path.join(projectPath, '.cursorrules'), aiRulesContent);
|
|
20
|
+
fs.writeFileSync(path.join(projectPath, '.windsurfrules'), aiRulesContent);
|
|
21
|
+
|
|
22
|
+
// Écriture pour GitHub Copilot
|
|
23
|
+
const githubPath = path.join(projectPath, '.github');
|
|
24
|
+
if (!fs.existsSync(githubPath)) {
|
|
25
|
+
fs.mkdirSync(githubPath, { recursive: true });
|
|
26
|
+
}
|
|
27
|
+
fs.writeFileSync(path.join(githubPath, 'copilot-instructions.md'), aiRulesContent);
|
|
28
|
+
}
|
|
29
|
+
|
package/generator/index.js
CHANGED
|
@@ -14,6 +14,7 @@ import { scaffoldCI } from './features/scaffold-ci.js';
|
|
|
14
14
|
import { scaffoldGit } from './features/scaffold-git.js';
|
|
15
15
|
import { scaffoldGef } from './features/scaffold-gef.js';
|
|
16
16
|
import { scaffoldLinter } from './features/scaffold-linter.js';
|
|
17
|
+
import { scaffoldAiRules } from './features/scaffold-ai-rules.js';
|
|
17
18
|
|
|
18
19
|
const __filename = fileURLToPath(import.meta.url);
|
|
19
20
|
const GEF_DIR = path.resolve(path.dirname(__filename), '..');
|
|
@@ -45,6 +46,7 @@ async function run() {
|
|
|
45
46
|
scaffoldStack(answers, projectPath);
|
|
46
47
|
scaffoldLinter(answers.linter, answers.stack);
|
|
47
48
|
scaffoldGef(answers, GEF_DIR);
|
|
49
|
+
scaffoldAiRules(GEF_DIR, projectPath);
|
|
48
50
|
if (answers.includeDocker) scaffoldDocker(answers.stack, answers.database, answers.projectName);
|
|
49
51
|
if (answers.includeCI) scaffoldCI(answers.stack, answers.cloud, answers.projectName, {
|
|
50
52
|
database: answers.database,
|
package/hooks/pre-commit
CHANGED
|
@@ -1,6 +1,14 @@
|
|
|
1
1
|
#!/bin/bash
|
|
2
2
|
# Hook: pre-commit
|
|
3
|
-
# Réf: ENGINEERING_PLAYBOOK.md §1, §6, §12
|
|
3
|
+
# Réf: ENGINEERING_PLAYBOOK.md §1, §5, §6, §12
|
|
4
|
+
|
|
5
|
+
# 0. Vérification de la branche (Protection Anti-Contournement)
|
|
6
|
+
BRANCH=$(git rev-parse --abbrev-ref HEAD)
|
|
7
|
+
if [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; then
|
|
8
|
+
echo -e "\033[31mErreur: Commits directs sur '$BRANCH' strictement interdits (Playbook §5).\033[0m"
|
|
9
|
+
echo "L'IA ou le développeur humain doit créer une branche (git checkout -b <nom-branche>) et passer par une Pull Request."
|
|
10
|
+
exit 1
|
|
11
|
+
fi
|
|
4
12
|
|
|
5
13
|
# 1. Vérification des secrets en clair
|
|
6
14
|
# Recherche naïve de patterns de type api_key="qqchose" ou secret = "qqchose" dans le code mis en stage
|
package/package.json
CHANGED
package/prompts/system_prompt.md
CHANGED
|
@@ -35,7 +35,7 @@ Tu ne peux **jamais** générer ou proposer du code qui viole ces règles :
|
|
|
35
35
|
- **ADR :** Toute décision architecturale majeure doit faire l'objet d'un fichier `docs/adr/`.
|
|
36
36
|
- Structure la documentation selon **Diátaxis** (Tutoriels, How-to, Référence, Explication).
|
|
37
37
|
|
|
38
|
-
## 6. Méthodologie Pas-à-Pas
|
|
38
|
+
## 6. Méthodologie Pas-à-Pas & Clause de Plantage (Crash Clause)
|
|
39
39
|
- Ne code jamais de larges blocs d'un seul coup.
|
|
40
40
|
- Propose → Explique → Implémente → Commite → Valide, étape par étape.
|
|
41
|
-
-
|
|
41
|
+
- **Crash Clause (Zéro Contournement Silencieux) :** En cas d'échec, d'erreur inattendue, de script qui plante ou si tu manques d'un prérequis, **ARRÊTE-TOI IMMÉDIATEMENT et signale-le à l'utilisateur**. Ne tente jamais de contourner le problème en inventant une solution de contournement (workaround) silencieuse sans accord explicite.
|