GaoFei2025-0314/tidy

Tidy · Projekt-Sauberkeit und -Struktur

Jede Datei im Repository muss drei Fragen beantworten können:

1. Warum existiert sie? (Notwendigkeit) – Was würde kaputtgehen, wenn man sie löscht?
2. Warum ist sie hier? (Zugehörigkeit) – Zu welchem Verzeichnis gehört sie gemäß den Konventionen dieses Projekts?
3. Versteht sie jemand anderes? (Lesbarkeit) – Könnte ein Neuling anhand des Dateinamens und der README erraten, wofür sie ist?

Wenn der Benutzer /tidy eingibt, führe direkt den untenstehenden „Modus 2: Bestehendes Projekt aufräumen“ aus.

Drei-Ebenen-Mechanismus

Ebene	Zweck	Ausgeführt von
Verzeichnis-Konvention .claude/tidy.json	Legt fest, was in jedes Top-Level-Verzeichnis gehört, verwandelt „Wohin damit?“ von Urteil in Nachschlagen	Du erstellst sie beim Aufräumen, pflegst sie dann langfristig
Hooks (mit Plugin-Installation)	Injizieren Regeln und Verzeichnis-Konventionen zu Sitzungsbeginn; blockieren neue, nicht konforme Dateien; prüfen am Ende jeder Runde auf neue Dateien	Automatisch, siehe unten „Wenn ein Hook-Hinweis kommt“
Dieses Skill	Maßstab beim Schreiben von Code, Prozess zum Aufräumen alter Projekte	Du

Hooks prüfen nur neue Dateien; bestehende Probleme alter Projekte werden durch „Modus 2“ behoben.

Drei Prüf-Granularitäten

Zeitpunkt	Was tun
Beim Erstellen einer neuen Datei	Gehe die 4 Fragen unten durch (mit Hooks automatische Blockade)
Bei Phasenabschluss / Aufgabenende	audit.py <Wurzelverzeichnis> --changed (für Git-Projekte, nur Änderungen relativ zu HEAD) oder --since 2h (nach Änderungszeit, auch für Nicht-Git-Projekte). Tools ohne Hooks (Codex, Cursor) vor jeder Übergabe einmal ausführen.
Benutzer fordert Projekt-Aufräumung	Vollständig audit.py <Wurzelverzeichnis>, gehe zu „Modus 2“

Warnungen, die nach Prüfung als nicht behandlungsbedürftig bestätigt wurden (beabsichtigte Lieferkopien, Dateinamen von Drittanbietern), werden mit audit.py <Wurzelverzeichnis> --review <Regel> <Pfad> --reason <Begründung> festgehalten und danach nicht mehr gemeldet; wenn sich der Dateiinhalt ändert, erscheinen sie erneut und erfordern eine erneute Überprüfung.

---

Modus 1: Beim Codieren (immer anwendbar)

4 Fragen vor dem Erstellen einer neuen Datei

Frage	Vorgehen bei Nichtbestehen
Notwendig? Kann es in eine bestehende Datei geschrieben werden? Ist es nur einmalig?	In bestehende Datei einfügen; einmalige Inhalte in die Antwort schreiben, nicht speichern
Wohin? Entspricht es dem Layout in .claude/tidy.json?	In ein bereits deklariertes Verzeichnis legen; bei Bedarf für ein neues Top-Level-Verzeichnis dieses erst im Layout und in der README unter „Verzeichnisstruktur“ eintragen
Wie heißen? Sagt der Name den Zweck und ist er konsistent mit dem Stil im selben Verzeichnis?	Nach references/naming.md benennen
Soll es committet werden? Ist es ein Build-Artefakt, eine Abhängigkeit, ein Geheimnis oder eine große Datei?	Zu .gitignore hinzufügen, nicht versionieren

Häufigste schlechte Angewohnheiten von KI (verboten)

❌ Schlechte Angewohnheit	✅ Richtiges Vorgehen
Temporäre Skripte wie test.py, debug.js, check_xxx.py im Root-Verzeichnis anlegen	In .scratch/ schreiben (sicherstellen, dass es ignoriert wird) oder in ein System-Temp-Verzeichnis, nach Aufgabenende löschen
Kopien wie foo_v2.ts, foo_new.ts, foo.backup.ts, foo_old/ erstellen	Direkt die Originaldatei ändern, den Verlauf überlässt man Git
Nach jeder Aktion IMPLEMENTATION_SUMMARY.md, FIX_REPORT.md generieren	Zusammenfassung in die Antwort und die Commit-Nachricht schreiben; langfristiges Wissen in README oder vorhandene docs/-Dokumente einpflegen
build/, out/, dist/, gerenderte Videos/Audios, Logs committen	Zu .gitignore hinzufügen; in der README klar beschreiben, wie man sie generiert
node_modules/, .venv/ werden committet oder liegen verstreut	Ignorieren; Toolchains für verschiedene Sprachen an ihren Platz (siehe structure.md „Mixed Projects“)
Chinesische Zeichen, Leerzeichen, Klammern in Dateinamen: 提示词分享.md, final (1).mp4	Dateinamen in Englisch mit kebab-case, chinesische Inhalte in den Dateititel schreiben
Boilerplate vom Scaffolding nicht aufgeräumt, große Mengen auskommentierten alten Codes, ungenutzte Abhängigkeiten	Nach Bestätigung der fehlenden Referenzen löschen
Dieselbe Konfiguration doppelt (.prettierrc + package.json#prettier)	Nur eine Stelle behalten
Leere Verzeichnisse oder Dateien „für später“ vorab anlegen	Erst anlegen, wenn sie gebraucht werden

Wenn ein Hook-Hinweis kommt

• Neue Datei wird blockiert: Folge dem Hinweis – füge sie in eine bestehende Datei ein, wechsle das Verzeichnis, ändere den Namen oder speichere sie gar nicht. Verwende nicht Bash, um Dateien zu schreiben, um die Blockade zu umgehen (die Stop-Prüfung wird es trotzdem finden).
• Die Endprüfung listet Probleme auf: Bearbeite sie einzeln (lösche temporäre Dateien, führe Kopien zusammen, verschiebe, ergänze .gitignore), bevor du die Aufgabe beendest.
• Der Benutzer fordert dies ausdrücklich (z. B. möchte er einen chinesischen Dateinamen): Füge den Pfad gemäß den Regeln zu allow in .claude/tidy.json hinzu (z. B. {"non-portable-name": ["docs/课程/**"]}) und erkläre es in der Antwort. Halte den Ausnahmebereich so klein wie möglich, deaktiviere nicht die gesamte Regel mit disable, und füge keine Ausnahmen eigenmächtig hinzu.
• Dateien, die lokal bleiben sollen, aber nicht ins Git sollen (fertige Videos, abgenommene Sprachaufnahmen, Modellgewichte usw.): Trage sie in keepLocal ein, mit Begründung, und ergänze .gitignore. Lösche sie nicht.
• Ein neues Top-Level-Verzeichnis wird benötigt: Stelle zuerst sicher, dass es kein passendes bestehendes Verzeichnis gibt, und trage es dann im layout und in der README unter „Verzeichnisstruktur“ ein.

---

Modus 2: Bestehendes Projekt aufräumen

Die Skripte befinden sich im scripts/-Verzeichnis dieses Skills und benötigen nur Python 3.9+ Standardbibliothek.

Schritt 1: Scannen

python3 <skill>/scripts/audit.py <Projekt-Wurzelverzeichnis>            # Textbericht
python3 <skill>/scripts/audit.py <Projekt-Wurzelverzeichnis> --format json

Schritt 2: Projekt verstehen, Referenzen prüfen

Das Skript ist heuristisch; jede Warnung muss vor der Bearbeitung überprüft werden. Der Textbericht klappt viele gleichartige Probleme zusammen; verwende --all, um sie einzeln zu sehen. Bevor du Schlüsse ziehst:

• Lies README, package.json / pyproject.toml auf Skripte und Einstiegspunkte;

• Prüfe für jede zu löschende oder zu verschiebende Datei die Referenzen:

  python3 <skill>/scripts/refs.py <Projekt-Wurzelverzeichnis> <Datei> [<Datei> ...]
  

  Die Schlussfolgerung ist eine von vier: in-use (eindeutige Referenz), convention (Framework lädt per Konvention), maybe (nur schwache Übereinstimmung), unreferenced (nicht gefunden). Bei unreferenced auch dynamische Pfade und externe Aufrufe berücksichtigen; die Bewertungskriterien finden sich in references/file-necessity.md.

Schritt 3: Lösungsvorschlag unterbreiten, auf Bestätigung warten

Pfad	Aktion	Zielort	Grund
提示词分享.md	Verschieben + Umbenennen	docs/prompts.md	Dokumente im Root-Verzeichnis; nicht-ASCII-Dateiname
out/	Ignorieren	—	Rendering-Artefakt, kann mit npm run render neu generiert werden
src/Root_old.tsx	Löschen	—	refs.py: unreferenced; Inhalt gleich wie Root.tsx

Es gibt nur sieben Aktionen: Behalten / Verschieben / Umbenennen / Löschen / Archivieren / Ignorieren / Lokal behalten (ignorieren, aber nicht löschen, in keepLocal eintragen). Markiere unsichere Fälle mit „Bestätigung ausstehend“. Wenn Warnungen erwartet werden (Lieferkopien, fortlaufende Einzelbilder), ist die Aktion das Hinzufügen zu allow gemäß den Regeln, nicht das Löschen der Datei.

Löschen und Massenverschiebungen müssen zuerst vom Benutzer bestätigt werden. Verschiebe keine Dateien, bevor der Vorschlag bestätigt ist.

Schritt 4: Ausführen

1. Stelle sicher, dass das Arbeitsverzeichnis sauber ist; wenn es kein Git-Repository ist, schlage zuerst git init und einen initialen Commit als Schnappschuss vor.
2. python3 <skill>/scripts/audit.py <Wurzelverzeichnis> --fix-gitignore: Fügt automatisch nicht ignorierte Abhängigkeiten, Build-Artefakte, Müll und Geheimnisse zu .gitignore hinzu (nur anfügen, nicht löschen). Bereits von Git verfolgte Dateien werden aufgelistet; ein git rm --cached ist nötig.
3. Verwende für Verschiebungen/Umbenennungen git mv; führe danach refs.py oder grep auf dem alten Pfad aus, um alle Referenzen zu reparieren (Importe, staticFile(), Konfigurationen, Skripte, Dokumentlinks).
4. Führe Build / Tests / Lint aus, um sicherzustellen, dass nichts kaputt ist.
5. Führe Strukturänderungen und Codeänderungen in separaten Commits durch.

Schritt 5: Verzeichnis-Konventionen festschreiben (nicht überspringen)

Nach dem Aufräumen generiere die Verzeichnis-Konventionen, damit jede zukünftige Sitzung sie automatisch einhalten kann:

python3 <skill>/scripts/audit.py <Wurzelverzeichnis> --init     # Generiert einen .claude/tidy.json-Entwurf basierend auf den aktuellen Top-Level-Verzeichnissen

Fülle dann die Beschreibung jedes Verzeichnisses aus (ersetze TODO). Die Beschreibung sollte so sein, dass sie die Platzierungsentscheidung leitet, z. B. "public/": "Von staticFile() gelesene Medien: Bilder, Schriftarten, Sprachaufnahmen", nicht nur „Statische Ressourcen“. Aktualisiere gleichzeitig die README unter „Verzeichnisstruktur“. Das Konfigurationsformat findet sich in references/config.md.

Sicherheitsuntergrenze

• Nicht regenerierbare Dateien (Benutzermedien, Audioaufnahmen, handgeschriebene Prompts, Daten) niemals ohne Bestätigung löschen – stattdessen in ein geeignetes Verzeichnis verschieben oder archivieren.
• Lies .env und andere Geheimnis-Inhalte nicht aus und gib sie nicht aus; wenn du feststellst, dass ein Geheimnis bereits von Git verfolgt wird, erinnere den Benutzer daran, das Geheimnis zu rotieren und den Verlauf zu bereinigen, nicht nur die Datei zu löschen.
• Wenn du dir nicht sicher bist, ob eine Datei verwendet wird, markiere sie als „Bestätigung ausstehend“ und rate nicht.

---

Löschen oder Archivieren?

„Ob etwas ins Git gehört“ und „ob es gelöscht wird“ werden getrennt beurteilt.

Diese Datei …
├─ Kann sie mit geringem Aufwand neu generiert werden? (Build-Artefakt, Cache, Log, Abhängigkeit, temporärer Frame)
│    └─ Ja → Löschen + zu .gitignore hinzufügen
├─ Kann neu generiert werden, aber der Aufwand ist hoch? (Fertiges Video, abgenommene Sprachaufnahme, gerendertes Kurs-Paket, trainiertes Modell – kostet Zeit, Geld oder erneute Abnahme)
│    └─ Ja → Lokal behalten + zu .gitignore hinzufügen + in keepLocal von tidy.json eintragen (mit Begründung), in README die Generierungsmethode beschreiben
├─ Ist es veralteter Code, der bereits von Git verfolgt wird?
│    └─ Ja → Direkt löschen (Git-Verlauf ist das Archiv)
├─ Ist es nicht regenerierbar und hat noch Referenzwert? (Recherche-Notizen, alte Prompts, Designentwürfe, Entscheidungsdokumente)
│    └─ Ja → Nach docs/archive/ verschieben, Dateiname mit Datumspräfix versehen, einen Grund in docs/archive/README.md notieren
├─ Sind es große Mediendateien? (Audio/Video, Datensätze, Modelle)
│    └─ Ja → Nicht ins Git (oder Git LFS verwenden), Beschaffungsmethode in README beschreiben
└─ Ist es nicht regenerierbar und wertlos → Auflisten, nach Benutzerbestätigung löschen

Archivierungsdetails in references/docs.md.

Referenzdateien

Datei	Inhalt	Wann lesen
references/structure.md	Whitelist für Root-Verzeichnisse, Standard-Verzeichnislayout für verschiedene Projekttypen (Node/TS, Remotion, Python, Mixed)	Bei Entscheidung, wohin eine Datei gehört, beim Entwerfen des Layouts
references/file-necessity.md	Kriterien zur Beurteilung der Notwendigkeit einer Datei, häufig löschbare Boilerplate	Bei Entscheidung, ob eine Datei gelöscht werden kann
references/naming.md	Namenskonventionen pro Sprache, verbotene Namensmuster	Beim Erstellen oder Umbenennen einer Datei
references/docs.md	Mindestanforderungen an README, docs/-Layout, Archivierungsregeln	Beim Schreiben von Dokumentation, beim Archivieren
references/config.md	Felder und Beispiele für .claude/tidy.json	Beim Generieren oder Ändern von Verzeichnis-Konventionen
assets/README.template.md	README-Vorlage	Wenn ein Projekt eine README vermissen lässt
assets/gitignore/	.gitignore-Ausschnitte: Allgemein, Node, Python, Medien	Zum Vervollständigen der Ignorier-Regeln
assets/agents-rules.md	Regeln zum Einfügen in AGENTS.md (für andere KI-Tools, die keine Hooks unterstützen)	Wenn das Projekt auch von Cursor / Codex usw. verwendet wird