GaoFei2025-0314/tidy

Tidy · Règles de propreté du projet

Chaque fichier du dépôt doit pouvoir répondre à trois questions :

1. Pourquoi existe-t-il ? (Nécessité) — Que casserait sa suppression ?
2. Pourquoi est-il ici ? (Appartenance) — Selon les conventions de répertoire du projet, à quel répertoire appartient-il ?
3. Les autres peuvent-ils le comprendre ? (Lisibilité) — Rien qu'avec le nom du fichier et le README, un nouveau venu peut-il deviner à quoi il sert ?

Lorsque l'utilisateur tape /tidy, exécutez directement le « Mode 2 : Réorganiser un projet existant » ci-dessous.

Mécanisme en trois couches

Couche	Rôle	Exécuté par
Conventions de répertoires .claude/tidy.json	Déclare ce que contient chaque répertoire racine, transforme le « où le mettre » en une simple consultation	Vous, lors de la réorganisation du projet, puis maintenu à long terme
Hooks (installés avec le plugin)	Injectent les règles et les conventions de répertoires en début de session ; bloquent les nouveaux fichiers non conformes ; vérifient les nouveaux fichiers à la fin de chaque tour	Automatique, voir « Lorsque vous recevez une notification de hook » ci-dessous
Ce skill	Critère de jugement pendant l'écriture de code, processus de réorganisation des projets existants	Vous

Les hooks ne vérifient que les nouveaux fichiers ; les problèmes existants dans un projet ancien sont traités par le « Mode 2 ».

Trois niveaux de vérification

Quand	Quoi faire
À la création d'un fichier	Passez les 4 questions ci-dessous (avec les hooks, bloquage automatique)
À la fin d'une étape / d'une tâche	audit.py <racine> --changed (projet git, seulement les changements par rapport à HEAD) ou --since 2h (par date de modification, fonctionne aussi pour les projets non-git). Pour les outils sans hooks (Codex, Cursor), exécutez-le avant chaque livraison.
L'utilisateur demande une réorganisation du projet	Audit complet audit.py <racine>, suivez le « Mode 2 »

Pour les alertes vérifiées et jugées non problématiques (copies de livraison intentionnelles, noms de fichiers tiers), utilisez audit.py <racine> --review <règle> <chemin> --reason <conclusion> pour les enregistrer. Elles ne seront plus signalées ; si le contenu du fichier change, l'alerte réapparaîtra pour vous inviter à re-vérifier.

---

Mode 1 : Pendant l'écriture de code (applicable à chaque fois)

Les 4 questions avant de créer un fichier

Question	Que faire en cas d'échec
Est-ce nécessaire ? Peut-il être intégré à un fichier existant ? N'est-il que temporaire ?	Intégrez-le dans un fichier existant ; pour du contenu temporaire, écrivez-le dans la réponse, ne le sauvegardez pas
Où le mettre ? Respecte-t-il la configuration de .claude/tidy.json ?	Placez-le dans un répertoire déjà déclaré ; si un nouveau répertoire racine est vraiment nécessaire, enregistrez-le d'abord dans layout et dans la section « Structure des répertoires » du README
Comment le nommer ? Le nom explique-t-il son utilité et est-il cohérent avec le style du répertoire ?	Suivez les conventions de references/naming.md
Doit-il être commité ? Est-ce un artefact de build, une dépendance, une clé secrète, un fichier volumineux ?	Ajoutez-le à .gitignore, ne l'incluez pas dans le dépôt

Les pires habitudes de l'IA (interdites)

❌ Mauvaise habitude	✅ Bonne pratique
Écrire des scripts temporaires test.py, debug.js, check_xxx.py à la racine	Écrivez-les dans .scratch/ (assurez-vous qu'il est ignoré) ou dans le répertoire temporaire du système, supprimez-les à la fin de la tâche
Copier foo_v2.ts, foo_new.ts, foo.backup.ts, foo_old/	Modifiez directement le fichier original, l'historique est géré par git
Générer IMPLEMENTATION_SUMMARY.md, FIX_REPORT.md après chaque action	Résumez dans la réponse et le message de commit ; intégrez la connaissance durable dans le README ou la documentation existante dans docs/
Commiter build/, out/, dist/, des vidéos/audio générés, des logs	Ajoutez-les à .gitignore ; expliquez dans le README comment les générer
node_modules/, .venv/ commités ou éparpillés	Ignorez-les ; chaque chaîne d'outils multilangue doit être à sa place (voir structure.md « Projets mixtes »)
Noms de fichiers avec caractères chinois, espaces, parenthèses : 提示词分享.md, final (1).mp4	Utilisez des noms en anglais en kebab-case, mettez le chinois dans le titre du fichier
Échafaudages non nettoyés, gros blocs de code commenté, dépendances inutilisées	Supprimez après avoir vérifié qu'ils ne sont pas référencés
Même configuration écrite deux fois (.prettierrc + package.json#prettier)	Ne conservez qu'un seul endroit
Créer à l'avance des répertoires ou fichiers vides « pour utilisation future »	Créez-les seulement quand vous en avez besoin

Lorsque vous recevez une notification de hook

• Nouveau fichier bloqué : Suivez les conseils — fusionnez dans un fichier existant, changez de répertoire, changez de nom, ou ne le sauvegardez pas. N'essayez pas de contourner le blocage en écrivant le fichier avec Bash (la vérification Stop le détectera quand même).
• Vérification de fin de session liste des problèmes : Traitez-les un par un (supprimez les fichiers temporaires, fusionnez les copies, déplacez, ajoutez à .gitignore), puis terminez.
• L'utilisateur demande explicitement une dérogation (par exemple, veut un nom de fichier en chinois) : Ajoutez le chemin dans la section allow de .claude/tidy.json (ex. {"non-portable-name": ["docs/课程/**"]}) et expliquez-le dans la réponse. Limitez la dérogation au maximum, n'utilisez pas disable pour désactiver une règle entière, et n'ajoutez pas de dérogation de votre propre chef.
• Fichiers à conserver localement mais pas à commiter (vidéo finale, narration approuvée, poids de modèle, etc.) : Enregistrez-les dans keepLocal avec la raison, puis ajoutez-les à .gitignore. Ne les supprimez pas.
• Besoin d'un nouveau répertoire racine : Assurez-vous qu'aucun répertoire existant ne convient, puis enregistrez-le dans layout et dans la section « Structure des répertoires » du README.

---

Mode 2 : Réorganiser un projet existant

Les scripts se trouvent dans le répertoire scripts/ de ce skill et ne dépendent que de la bibliothèque standard Python 3.9+.

Étape 1 : Scanner

python3 <skill>/scripts/audit.py <racine_du_projet>            # Rapport texte
python3 <skill>/scripts/audit.py <racine_du_projet> --format json

Étape 2 : Comprendre le projet, vérifier les références

Le script est heuristique ; chaque alerte doit être vérifiée avant d'être traitée. Le rapport texte regroupe les problèmes similaires en grand nombre ; utilisez --all pour voir chaque entrée. Avant de conclure :

• Lisez le README, les scripts et points d'entrée dans package.json / pyproject.toml ;

• Pour chaque fichier à supprimer ou déplacer, vérifiez les références :

  python3 <skill>/scripts/refs.py <racine_du_projet> <fichier> [<fichier> ...]
  

  Le résultat a quatre catégories : in-use (référence explicite), convention (chargé par convention du framework), maybe (correspondance faible), unreferenced (aucune trouvée). Même pour unreferenced, tenez compte des chemins dynamiques et des appels externes ; les critères de décision sont dans references/file-necessity.md.

Étape 3 : Proposer un plan de réorganisation, attendre la confirmation

Chemin	Action	Destination	Raison
提示词分享.md	Déplacer + Renommer	docs/prompts.md	Document éparpillé à la racine ; nom de fichier non ASCII
out/	Ignorer	—	Artefact de build, peut être regénéré par npm run render
src/Root_old.tsx	Supprimer	—	refs.py : non référencé ; contenu identique à Root.tsx

Les actions sont limitées à sept : Conserver / Déplacer / Renommer / Supprimer / Archiver / Ignorer / Conserver localement (ignorer mais ne pas supprimer, enregistrer dans keepLocal). Marquez « À confirmer » si vous n'êtes pas sûr. Si l'alerte est attendue (copie de livraison, captures d'écran consécutives), l'action est d'ajouter une règle dans allow, pas de supprimer le fichier.

Les suppressions et les déplacements en masse doivent d'abord être confirmés par l'utilisateur. Ne touchez pas aux fichiers avant la confirmation du plan.

Étape 4 : Exécuter

1. Assurez-vous que l'espace de travail est propre ; s'il ne s'agit pas d'un dépôt git, suggérez d'abord git init et faites un commit initial comme instantané.
2. python3 <skill>/scripts/audit.py <racine> --fix-gitignore : ajoute automatiquement au .gitignore les dépendances, artefacts, fichiers indésirables et clés non ignorés (ne fait qu'ajouter, ne supprime rien). Les fichiers déjà suivis par git seront listés ; vous devrez peut-être utiliser git rm --cached.
3. Utilisez git mv pour les déplacements / renommages ; après, exécutez refs.py ou grep sur les anciens chemins pour corriger toutes les références (imports, staticFile(), configurations, scripts, liens de documentation).
4. Lancez la construction / les tests / le linting pour vérifier que rien n'est cassé.
5. Commitez séparément les changements de structure et les modifications de code.

Étape 5 : Consolider les conventions de répertoires (ne sautez pas)

Après la réorganisation, générez les conventions de répertoires pour que chaque session future les respecte automatiquement :

python3 <skill>/scripts/audit.py <racine> --init     # Génère un brouillon de .claude/tidy.json basé sur les répertoires racine existants

Puis complétez la description de chaque répertoire (remplacez TODO). Rédigez-la de manière à guider la décision de placement, par exemple "public/": "Ressources lues par staticFile() : images, polices, voix-off", pas seulement « Ressources statiques ». Mettez à jour la section « Structure des répertoires » du README en même temps. Le format de configuration est décrit dans references/config.md.

Principes de sécurité

• Les fichiers non régénérés (ressources utilisateur, enregistrements audio, prompts manuscrits, données) ne doivent jamais être supprimés sans confirmation — déplacez-les vers un répertoire approprié ou archivez-les.
• Ne lisez pas, n'affichez pas le contenu des clés comme .env ; si vous découvrez qu'une clé est suivie par git, alertez l'utilisateur pour qu'il remplace la clé et nettoie l'historique, ne vous contentez pas de supprimer le fichier.
• Si vous n'êtes pas sûr qu'un fichier est utilisé, marquez-le comme « À confirmer », ne devinez pas.

---

Supprimer ou archiver ?

« Entrer dans git » et « Supprimer » sont deux décisions distinctes.

Ce fichier…
├─ Peut-il être regénéré à faible coût ? (artefact de build, cache, logs, dépendances, captures temporaires)
│    └─ Oui → Supprimer + ajouter à .gitignore
├─ Peut-il être regénéré, mais à coût élevé ? (vidéo finale, narration approuvée, paquet de cours rendu, modèle entraîné — nécessite du temps, de l'argent ou une re-validation)
│    └─ Oui → Conserver localement + ajouter à .gitignore + enregistrer dans keepLocal de tidy.json (avec la raison) + expliquer comment le générer dans le README
├─ S'agit-il d'un code obsolète déjà suivi par git ?
│    └─ Oui → Supprimer directement (l'historique git sert d'archive)
├─ Est-il non régénéré et a-t-il encore une valeur de référence ? (notes de recherche, prompts anciens, maquettes, décisions documentées)
│    └─ Oui → Déplacer vers docs/archive/, ajouter un préfixe de date au nom de fichier, noter une ligne de raison dans docs/archive/README.md
├─ S'agit-il d'une ressource volumineuse ? (audio/vidéo, jeux de données, modèles)
│    └─ Oui → Ne pas inclure dans git (ou utiliser Git LFS), expliquer comment l'obtenir dans le README
└─ Est-il non régénéré et sans valeur → Lister, supprimer après confirmation de l'utilisateur

Les détails sur l'archivage sont dans references/docs.md.

Fichiers de référence

Fichier	Contenu	Quand le lire
references/structure.md	Liste blanche des répertoires racine, structure standard pour divers types de projets (Node/TS, Remotion, Python, mixte)	Pour décider où mettre un fichier, concevoir le layout
references/file-necessity.md	Comment juger si un fichier est nécessaire, modèles souvent supprimables	Pour décider si on peut supprimer
references/naming.md	Conventions de nommage par langage, modèles de noms interdits	Pour créer ou renommer un fichier
references/docs.md	Exigences minimales du README, structure de docs/, règles d'archivage	Pour écrire de la documentation, archiver
references/config.md	Description des champs et exemples de .claude/tidy.json	Pour générer ou modifier les conventions de répertoires
assets/README.template.md	Modèle de README	Quand le projet manque de README
assets/gitignore/	Fragments de .gitignore : général, Node, Python, médias	Pour compléter les règles d'ignorance
assets/agents-rules.md	Règles à copier dans AGENTS.md (pour autres outils IA sans hooks)	Quand le projet utilise aussi Cursor / Codex, etc.