diff --git a/.claude/rules/04-code-conventions.md b/.claude/rules/04-code-conventions.md index 4001c2f..75e1616 100644 --- a/.claude/rules/04-code-conventions.md +++ b/.claude/rules/04-code-conventions.md @@ -16,6 +16,26 @@ indentations par type de fichier. caractères au plus. Tags réellement utilisés : `[UPD]`, `[FIX]`, `[ADD]`, `[IMP]`, `[REF]`. +### Le sujet + +Le sujet est lu cent fois pour une fois que le corps l'est — `git log +--oneline`, un blame, une note de version, un bisect. Il a une seule tâche : +dire **sur quoi porte le code**. + +L'épreuve : le lire seul, sans diff ni corps. Sait-on quelle partie du système +est en jeu, et ce qui y est désormais différent ? Sinon il n'est pas fini. + +Nommer la chose, puis ce qui change pour elle. Le symptôme, le message d'erreur +cité et la métaphore sont des PREUVES, et une preuve va dans le corps — un +sujet bâti sur elles se lit bien et n'apprend rien. La portée dit OÙ, les mots +après le deux-points doivent dire QUOI. + +Le sujet résume le commit ENTIER, pas sa plus grosse pièce. S'il lui faut un +« et » entre deux choses sans rapport, c'étaient deux commits. + +Le mode d'emploi complet, avec des exemples avant/après pris dans l'historique +de ce dépôt, est dans `conf/template_claude_commands_commit.md`. + ### Tout commit assisté par IA Trois exigences, sans exception — `AI_POLICY.md` en donne la raison : diff --git a/conf/template_claude_commands_commit.md b/conf/template_claude_commands_commit.md index e97ca07..ad00dc4 100644 --- a/conf/template_claude_commands_commit.md +++ b/conf/template_claude_commands_commit.md @@ -90,6 +90,39 @@ The same body, translated. Assisted-by: {MODEL} ``` +### The subject line + +The subject is read a hundred times for every time the body is read: in +`git log --oneline`, in a blame, in a release note, in a bisect. It has one +job — say what the code is about. + +**The test.** Read the subject alone, with no diff and no body. Can you say +which part of the system it concerns, and what is now different about it? If +not, it is not finished. + +**Name the thing, then what changed about it.** The symptom, the quoted error +and the metaphor are EVIDENCE, and evidence belongs in the body. A subject +built on them reads well and tells the next reader nothing: + +| Instead of | Write | +|-----------|-------| +| `[FIX] nettoyage : les enfants s'en vont avec leur rebond` | `[FIX] nettoyage : les entrées ssh qui rebondissent par une VM effacée` | +| `[FIX] proxmox : « il manque le stockage » était le symptôme, pas la cause` | `[FIX] proxmox : signaler pmxcfs à terre, et non « aucun stockage »` | +| `[FIX] migration: un module fautif n'emporte plus tout le lot` | `[FIX] migration: isoler l'échec d'un module dans la désinstallation` | + +The scope is not the subject. `proxmox` says WHERE; the words after the colon +must say WHAT. A subject that works with its scope removed is usually the +right one. + +**Summarise the whole commit, not its largest piece.** When the work has two +faces — a guard moved and the check that proves it, a screen and the service +under it — the subject covers both or the commit should have been two. If the +only honest subject needs an `and` joining two unrelated things, split it. + +**It must be complete in 72 characters.** A subject cut mid-phrase by +`--oneline` has failed at the one place it is read most. Write it to fit +rather than trimming it afterwards: drop the adjectives, keep the nouns. + ### Keep it short The body answers one question: why was this necessary. Stop once it is