Décisions en ADR ; plans et feuille de route temporaires
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Pierre MARTIN
co-authored by
Claude Opus 5.5
Claude Opus 5.5
parent
6958accec2
commit
d017f3338b
+45
-51
@@ -2,7 +2,7 @@
|
||||
|
||||
Ce document décrit qui fait quoi et où chaque chose est consignée. Le but : que
|
||||
tout le travail, humain comme agentique, soit suivi et vérifiable a posteriori
|
||||
en lisant uniquement le dépôt.
|
||||
en lisant le dépôt et ses merge requests.
|
||||
|
||||
## Rôles
|
||||
|
||||
@@ -12,69 +12,58 @@ en lisant uniquement le dépôt.
|
||||
- **Claude Code, session principale : chef de projet technique.** Tient la
|
||||
feuille de route, découpe le travail, rédige les plans, délègue l'exécution à
|
||||
des sous-agents, vérifie leurs résultats (`make lint`, `make test`, relecture
|
||||
du diff), fait les commits et tient le journal.
|
||||
du diff), rédige les ADR, ouvre et fusionne les merge requests, tient le
|
||||
journal.
|
||||
- **Sous-agents** : exécutent une tâche bornée décrite par un plan. Ils ne
|
||||
décident rien de structurant : ils rapportent, la session principale tranche
|
||||
ou soumet à Pierre.
|
||||
|
||||
## Où se trouve quoi
|
||||
|
||||
Deux familles de documents, de durée de vie différente (ADR 0001).
|
||||
|
||||
**Durables** : ils restent et font foi.
|
||||
|
||||
| Document | Contenu | Mis à jour |
|
||||
| --- | --- | --- |
|
||||
| `docs/cadrage.md` | Vision, périmètre, architecture cible | Quand Pierre change le cadrage |
|
||||
| `docs/feuille-de-route.md` | Étapes, état de chacune, prochaine action | À chaque changement d'état |
|
||||
| `docs/etape-0.md` (puis `etape-N.md`) | Spécification détaillée de l'étape en cours | Au début de chaque étape |
|
||||
| `docs/plans/` | Un fichier par tâche déléguée : mission, consignes, résultat, vérification | Avant et après chaque délégation |
|
||||
| `docs/decisions.md` | Décisions structurantes, avec raisons et alternatives | À chaque décision validée |
|
||||
| `docs/journal.md` | Une entrée datée par session | En fin de session |
|
||||
| `docs/adr/` | Un ADR par décision structurante ; index dans `docs/adr/README.md` | À chaque décision ; jamais réécrit une fois accepté |
|
||||
| `docs/journal.md` | Une entrée datée par session : fait, décidé, suite | En fin de session |
|
||||
| Merge requests (git.sans.pub) | Le détail de chaque changement : pourquoi, comment, vérification | À chaque changement |
|
||||
|
||||
**Règle** : rien d'important ne vit seulement dans la mémoire d'une session.
|
||||
Une information utile pour la suite est écrite dans `docs/` et commitée.
|
||||
**Temporaires** : ils décrivent le travail à faire et disparaissent une fois
|
||||
réalisé.
|
||||
|
||||
| Document | Contenu | Cycle de vie |
|
||||
| --- | --- | --- |
|
||||
| `docs/feuille-de-route.md` | Le travail restant et son état | Une ligne réalisée est retirée |
|
||||
| `docs/etape-N.md` | Spécification détaillée de l'étape en cours | Supprimé à la fin de l'étape |
|
||||
| `docs/plans/` | Un plan par tâche déléguée (modèle : `docs/plans/README.md`) | Supprimé quand la tâche est close |
|
||||
|
||||
**Règle** : rien d'important ne vit seulement dans la mémoire d'une session, ni
|
||||
seulement dans un document temporaire. Avant de supprimer un plan, ce qu'il
|
||||
contient de durable passe dans un ADR, dans la description de la merge request
|
||||
ou dans le journal.
|
||||
|
||||
## Cycle d'une tâche déléguée
|
||||
|
||||
1. **Plan** : la session principale crée `docs/plans/AAAA-MM-JJ-sujet.md`
|
||||
(modèle ci-dessous) et le commite avant de lancer l'agent.
|
||||
1. **Plan** : la session principale crée `docs/plans/AAAA-MM-JJ-sujet.md` et
|
||||
le commite sur la branche de la tâche avant de lancer l'agent.
|
||||
2. **Délégation** : l'agent reçoit le contenu du plan comme consigne ; il
|
||||
travaille sur une branche ou un espace de travail isolé quand il modifie
|
||||
du code.
|
||||
3. **Vérification** : la session principale relit le résultat, lance
|
||||
`make lint` et `make test`, et contrôle les critères de réussite du plan.
|
||||
4. **Clôture** : le plan reçoit sa section « Résultat » (fait, écarts, preuves),
|
||||
puis le travail est commité. Une décision qui en découle va dans
|
||||
`docs/decisions.md` (après validation de Pierre si elle est structurante).
|
||||
travaille dans un espace isolé quand il modifie du code.
|
||||
3. **Vérification** : la session principale relit le résultat, recoupe les
|
||||
affirmations décisives, lance `make lint` et `make test`, et contrôle les
|
||||
critères de réussite du plan.
|
||||
4. **Clôture** : une décision qui en découle devient un ADR (après validation de
|
||||
Pierre si elle est structurante). Le plan est supprimé dans la même merge
|
||||
request, dont la description reprend le résultat et les preuves.
|
||||
|
||||
Une tâche qui échoue est clôturée de la même façon, avec la cause : un échec
|
||||
Une tâche qui échoue est close de la même façon, avec la cause : un échec
|
||||
documenté est un résultat.
|
||||
|
||||
## Modèle de plan
|
||||
|
||||
```markdown
|
||||
# <Sujet>
|
||||
|
||||
- **Date** : AAAA-MM-JJ
|
||||
- **Étape** : 0a, 0b…
|
||||
- **Statut** : prévu | en cours | terminé | abandonné
|
||||
- **Exécutant** : sous-agent <type> | session principale
|
||||
|
||||
## Objectif
|
||||
Ce qui doit être vrai à la fin, en une ou deux phrases.
|
||||
|
||||
## Consignes
|
||||
Ce que l'agent doit faire, ses limites (fichiers, dépendances, durée),
|
||||
ce qu'il doit rapporter.
|
||||
|
||||
## Critères de réussite
|
||||
Commandes ou constats vérifiables.
|
||||
|
||||
## Résultat
|
||||
Rempli à la clôture : fait, écarts, preuves (sorties de commandes, mesures),
|
||||
suites à donner.
|
||||
```
|
||||
|
||||
## Branches et merge requests
|
||||
|
||||
Aucun commit direct sur `main`. Pour chaque changement :
|
||||
Aucun commit direct sur `main` (ADR 0006). Pour chaque changement :
|
||||
|
||||
1. Une branche au nom court et explicite (`moteur-reference`, `engine-cli`…).
|
||||
2. Des commits petits, en français.
|
||||
@@ -92,12 +81,17 @@ Aucun commit direct sur `main`. Pour chaque changement :
|
||||
5. Fusion par Claude Code (commit de fusion, pour garder l'historique de la
|
||||
branche), puis suppression de la branche.
|
||||
|
||||
Une MR qui touche à un point soumis à validation (voir ci-dessous) n'est
|
||||
fusionnée qu'après l'accord de Pierre, consigné dans `docs/decisions.md`.
|
||||
Règles de forme pour Gitea :
|
||||
- les hash de commit s'écrivent sans backticks, sinon Gitea ne crée pas de lien ;
|
||||
- pas d'émojis ni d'autres caractères sur 4 octets dans les titres et
|
||||
descriptions : la base de données du serveur les refuse.
|
||||
|
||||
Une MR qui touche à un point soumis à validation n'est fusionnée qu'après
|
||||
l'accord de Pierre, consigné dans l'ADR correspondant.
|
||||
|
||||
## Validation par Pierre
|
||||
|
||||
Sont soumis à Pierre avant d'être appliqués : le choix de la source du moteur,
|
||||
le choix du socle (PWA ou Android), toute nouvelle dépendance, tout ce qui touche
|
||||
au produit ou à l'identité. Le reste est décidé par la session principale et
|
||||
consigné.
|
||||
Sont soumis à Pierre avant d'être appliqués : le choix du socle (PWA ou
|
||||
Android), toute nouvelle dépendance, tout ce qui touche au produit ou à
|
||||
l'identité, et toute décision qui remplace un ADR accepté. Le reste est décidé
|
||||
par la session principale et consigné.
|
||||
|
||||
Reference in New Issue
Block a user