Anglais Simplifié
Aperçu
Règle 1 des règles de Jarrett : les sorties de chat, les documents générés, les commentaires de code et les messages de commit utilisent un anglais technique simplifié. Le style est basé sur les principes de l'ASD-STE100. Les lecteurs trouvent les faits plus vite. Les lecteurs dont la première langue n'est pas l'anglais comprennent mieux.
Cette compétence est notre propre résumé. Elle n'est pas le standard ASD-STE100 et n'inclut pas son dictionnaire.
Quand l'Utiliser
- Vous écrivez ou éditez une spécification, un plan, un ADR, un README, une entrée de vocabulaire ou un autre document.
- Vous écrivez un commentaire de code ou un message de commit.
- Vous révisez du texte pour la règle 1.
Ne l'appliquez pas aux identifiants de code, aux sorties citées (erreurs, logs, sortie de commande), aux fichiers de compétence ou au texte écrit par l'utilisateur.
Processus
Écrivez le texte. Ensuite, vérifiez-le par rapport à chaque règle.
| # | Règle | Pas ceci | Ceci |
|---|---|---|---|
| 1 | Un sujet par phrase. | Le hook lit le fichier et, s'il manque, il imprime un avertissement, que l'utilisateur voit. | Le hook lit le fichier. Si le fichier manque, le hook imprime un avertissement. L'utilisateur voit l'avertissement. |
| 2 | Instructions : 20 mots ou moins. Descriptions : 25 mots ou moins. | Assurez-vous qu'avant de pousser la branche vous avez exécuté toute la suite de tests et vérifié la sortie. | Exécutez ./scripts/test.sh. Ensuite, poussez la branche. |
| 3 | Utilisez la voix active. | Les règles sont chargées par le hook. | Le hook charge les règles. |
| 4 | Les instructions utilisent l'impératif. | Le test devrait être exécuté avant le commit. | Exécutez le test avant le commit. |
| 5 | Un mot a un sens. Utilisez les termes dans .claude-work/docs/VOCABULARY.md. | Avertir, puis plus tard "signaler", "alerter" ou "notifier" pour la même action. | Avertissez, à chaque fois. |
| 6 | Utilisez des temps simples : présent, passé, futur. | Le hook aurait vérifié l'entrée. | Le hook vérifie l'entrée. |
| 7 | Utilisez un seul verbe, pas un verbe à particule ou une expression idiomatique. | Lancez la construction. Trouvez la cause. | Démarrez la construction. Trouvez la cause. |
| 8 | Gardez "le" et "un". | Exécutez script, vérifiez sortie. | Exécutez le script. Vérifiez la sortie. |
| 9 | Une instruction par étape. | 1. Ouvrez le fichier et modifiez la version. | 1. Ouvrez le fichier. 2. Modifiez la version. |
| 10 | Paragraphes : 6 phrases ou moins. | Un bloc de dix phrases. | Deux courts paragraphes, ou une liste. |
Autres règles :
- Écrivez un avertissement ou une mise en garde avant l'étape à laquelle il s'applique. Commencez par le danger : "Avertissement : cela supprime la branche."
- Utilisez des chiffres, pas des mots, pour les valeurs : "72 caractères", pas "soixante-douze caractères".
- Utilisez une liste ou un tableau lorsque vous donnez trois éléments ou plus.
- N'utilisez pas de synonymes pour varier le texte. Répétez le même terme.
- N'utilisez pas "il" ou "ceci" lorsque le nom n'est pas clair. Nommez à nouveau le nom.
- Lorsqu'un terme n'est pas dans le vocabulaire et que le sens n'est pas clair, demandez à l'utilisateur. Ensuite, ajoutez le terme au vocabulaire.
Rationalisations Courantes
| Rationalisation | Réalité |
|---|---|
| "Les phrases courtes sonnent robotiques." | Les phrases courtes sont rapides à lire et difficiles à mal interpréter. La vitesse du lecteur importe plus que le style. |
| "Un synonyme rend le texte moins répétitif." | Un synonyme fait se demander au lecteur s'il s'agit d'une chose différente. |
| "Ce commentaire est trop petit pour les règles." | Les commentaires et les messages de commit sont dans le champ d'application. Un petit texte est facile à corriger. |
| "La voix passive est plus formelle." | La voix passive cache qui fait l'action. Nommez l'acteur. |
Drapeaux Rouges
- Phrases avec "et", "qui" ou "de sorte que" qui joignent deux sujets.
- "Devrait", "pourrait" ou "peut" dans une instruction.
- La même chose a deux noms dans un document.
- Une étape avec deux actions.
- Un avertissement après l'étape à laquelle il s'applique.
Vérification
- Chaque phrase a un sujet.
- Aucune instruction n'est plus longue que 20 mots. Aucune description n'est plus longue que 25 mots.
- Toutes les instructions utilisent l'impératif et la voix active.
- Tous les termes correspondent au vocabulaire.
- Chaque étape de liste a une instruction.
- Aucun paragraphe n'est plus long que 6 phrases.