nemunai.re/CLAUDE.md

Style d'écriture

Deux registres distincts

Le blog contient deux types d'articles qui n'obéissent pas aux mêmes règles :

Articles d'opinion / éditoriaux (ex. : La complexité est devenue la solution paresseuse, L'architecture pragmatique de mes projets) :

• Ton personnel, première personne du singulier ("je")
• Phrases courtes et rythmées, parfois elliptiques
• Titres de sections affirmatifs ou interrogatifs à fort impact
• Anecdotes personnelles pour étayer les arguments
• Questions rhétoriques pour interpeller le lecteur

Articles tutoriels / techniques (ex. : Whiteout files, IPv6 dans Docker, Auto-hébergement) :

• "On" acceptable et même préférable quand il désigne le lecteur en train de suivre les étapes
• Ton instructionnel, pas d'interpellations rhétoriques
• Sections structurées en étapes logiques
• Blocs de code avec prompt spécifique : 42sh$ pour l'hôte, incntr$ dans un conteneur
• Notes d'information ou d'avertissement avec le shortcode {{% card color="info/danger/success" title="..." %}}
• Footnotes [^clé] pour les références et sources

Caractéristiques communes aux deux registres

• Registre soutenu mais accessible : le texte s'adresse à des techniciens sans être hermétique. Pas de jargon inutile, mais une exigence dans la formulation.
• Anecdotes personnelles : les arguments s'appuient sur des expériences vécues concrètes.
• Structure forte : les articles sont toujours découpés en sections clairement titrées.
• Liens enrichissants : liens internes avec {{< relref "..." >}} et liens externes vers les outils ou sources mentionnés.

Corrections à appliquer systématiquement

1. Pronom personnel

Dans les articles d'opinion : remplacer le "on" par "je" quand c'est l'auteur qui parle.

• ❌ on peut générer un système entier → ✅ je peux générer un système entier
• ✅ on copie les architectures de Netflix (le "on" est correct ici, il désigne l'industrie)

Dans les tutoriels : "on" est correct quand il désigne le lecteur qui suit les étapes ("on relance Docker", "on vérifie que...").

Le "on" reste valide dans les deux registres quand il désigne une pratique collective ou l'industrie en général.

2. Registre des formulations

Éviter les tournures relâchées ou familières au profit de formulations plus soignées.

• ❌ Pourquoi il n'y a pas Kubernetes ? → ✅ Pourquoi n'y a-t-il pas Kubernetes ?
• ❌ utiliser le système de fichiers comme ça → ✅ utiliser le système de fichiers ainsi
• ❌ ça valorise une carrière → ✅ valorise une carrière
• ❌ c'est que ce n'est pas si compliqué → ✅ reformuler en phrase affirmative directe

3. Anglicismes évitables

Préférer les équivalents français quand ils existent et sonnent naturellement.

À éviter	Préférer
start-up	entreprise qui démarre
IA / outils d'IA	intelligence artificielle / logiciels d'intelligence artificielle
CPU	processeur
briques	composants

Les anglicismes techniques sans bon équivalent restent acceptables (custom, service mesh, micro-services).

4. Affirmations sans hésitation

Éviter les formulations qui affaiblissent le propos quand le texte assume une position.

• ❌ il me semble que la paresse se situe ici → selon le contexte, peut rester pour nuancer, mais à utiliser avec parcimonie
• ❌ on pourrait dire que → ✅ dire directement
• Les titres de sections doivent être affirmatifs, pas interrogatifs sur le fond

5. Transitions en début de phrase

Éviter les chevilles faibles en début de phrase.

• ❌ Et c'est là que... → ✅ reformuler directement
• ❌ Mais c'est précisément... → ✅ commencer par le sujet
• ✅ Autrement dit, est une bonne charnière de reformulation

6. "Très" et intensificateurs inutiles

Supprimer les adverbes qui n'ajoutent pas de sens.

• ❌ extrêmement complexes → ✅ complexes
• ❌ très courant → ✅ courant
• ❌ très simple → ✅ simple
• ❌ beaucoup plus simple → ✅ plus simple (sauf si l'insistance est vraiment nécessaire)
• ❌ fonctionnait très bien → ✅ fonctionnait bien ou reformuler

7. Découpage des phrases longues

Quand une phrase contient plus de deux propositions, envisager de la couper.

• ❌ Certes le cœur est devenu un produit générique, mais tout ce qu'il y a autour : l'orchestration, les scripts, le scotch, les adaptations, sont devenus le nouveau custom.
• ✅ Certes, le cœur du système est devenu un logiciel générique.\nMais tout ce qui le complète — l'orchestration, les scripts, les adaptations — est devenu le nouveau *custom*.

8. Interpellation du lecteur

Ajouter ponctuellement une courte phrase d'interpellation après une affirmation forte, pour briser le rythme et créer de la connivence.

• Cela vous parle ?
• Cela vous semble logique ?
• Devinez quoi ?

Ne pas en abuser : une ou deux par article suffisent.

9. Structure des listes

Dans les énumérations à la première personne, veiller à la cohérence du pronom.

• ❌ mélanger on sait et je comprends dans la même liste
• ✅ choisir un pronom et s'y tenir pour toute la liste

10. Reformulations personnelles et narratives

Éviter les formulations passives ou impersonnelles au profit d'une narration active à la première personne.

• ❌ J'ai donc déplacé la partie publique → ✅ Ma solution a consisté à déplacer la partie publique
• ❌ Lorsqu'on lit certaines discussions → ✅ Lorsqu'on lit reste valide ici (désigne les lecteurs en général), mais préférer je dès que c'est l'auteur qui parle

11. Vocabulaire technique plus précis

Préférer les termes les plus précis et les moins galvaudés.

• ❌ cluster Kubernetes → ✅ environnement Kubernetes
• ❌ pipeline CI → ✅ processus de génération ou chaîne d'intégration
• ❌ utilisateur → dans les schémas d'architecture → ✅ navigateur → (plus précis techniquement)

12. Structure des titres de sections

Dans Hugo, les titres de sections d'article utilisent ## (pas #, réservé au titre principal du document).

13. Enrichissement par les liens

Les articles gagnent à être enrichis de liens internes avec {{< relref >}} vers d'autres articles du site, et de liens externes vers les outils ou sources mentionnés. Ne pas hésiter à en ajouter quand un outil, un projet ou un article connexe est mentionné.