--- name: tidy-project-structure locale: de source_locale: en source_commit: 902f69ec translator: claude translation_date: "2026-03-17" description: > Projektdateien in konventionelle Verzeichnisse organisieren, veraltete READMEs aktualisieren, Konfigurationsdrift bereinigen und veraltete Elemente archivieren ohne Code-Logik zu aendern. Anwenden wenn Dateien ohne klare Organisation verstreut sind, READMEs veraltet sind oder defekte Beispiele enthalten, Konfigurationsdateien sich ueber Dev/Staging/Prod vermehrt haben, veraltete Dateien im Projektstamm verbleiben oder Namenskonventionen ueber Verzeichnisse hinweg inkonsistent sind. license: MIT allowed-tools: Read Write Edit Bash Grep Glob metadata: author: Philipp Thoss version: "1.0" domain: maintenance complexity: intermediate language: multi tags: maintenance, organization, structure, readme, config --- # Projektstruktur aufraumen ## Wann verwenden Diesen Skill verwenden wenn die Projektorganisation von Konventionen abgewichen ist: - Dateien ohne klare Organisation ueber Verzeichnisse verstreut - READMEs veraltet oder mit defekten Beispielen - Konfigurationsdateien haben sich vermehrt (Dev-, Staging-, Prod-Drift) - Veraltete Dateien verbleiben im Projektstamm - Namenskonventionen inkonsistent ueber Verzeichnisse hinweg **NICHT verwenden** fuer Code-Refactoring oder Abhaengigkeits-Umstrukturierung. Dieser Skill konzentriert sich auf Dateiorganisation und Dokumentationshygiene. ## Eingaben | Parameter | Typ | Erforderlich | Beschreibung | |-----------|-----|--------------|-------------| | `project_path` | string | Ja | Absoluter Pfad zum Projektstamm | | `conventions` | string | Nein | Pfad zum Stilhandbuch (z.B. `docs/conventions.md`) | | `archive_mode` | enum | Nein | `move` (Standard) oder `delete` fuer veraltete Dateien | | `readme_update` | boolean | Nein | Veraltete READMEs aktualisieren (Standard: true) | ## Vorgehensweise ### Schritt 1: Verzeichnisstruktur pruefen Aktuelle Struktur mit Projektkonventionen oder sprachspezifischen Best Practices vergleichen. **Gaengige Konventionen nach Sprache**: **JavaScript/TypeScript**: ``` src/ # Quellcode tests/ # Testdateien dist/ # Build-Ausgabe (gitignored) docs/ # Dokumentation .github/ # CI/CD-Workflows ``` **Python**: ``` package_name/ # Paketcode tests/ # Testsuite docs/ # Sphinx-Dokumentation scripts/ # Hilfsskripte ``` **R**: ``` R/ # R-Quellcode tests/testthat/ # Testsuite man/ # Dokumentation (generiert) vignettes/ # Ausfuehrliche Anleitungen inst/ # Installierte Dateien data/ # Paketdaten ``` **Rust**: ``` src/ # Quellcode tests/ # Integrationstests benches/ # Benchmarks examples/ # Verwendungsbeispiele ``` **Erwartet:** Liste der gegen Konventionen verstossenden Dateien/Verzeichnisse in `structure_audit.txt` gespeichert **Bei Fehler:** Wenn keine Konventionen dokumentiert sind, sprachspezifische Standards verwenden ### Schritt 2: Fehlplatzierte Dateien verschieben Dateien in ihre konventionellen Verzeichnisse umlagern. **Haeufige Verschiebungen**: 1. Testdateien ausserhalb von `tests/` nach `tests/` verschieben 2. Dokumentation ausserhalb von `docs/` nach `docs/` verschieben 3. Build-Artefakte in `src/` loeschen (sollten gitignored sein) 4. Konfigurationsdateien im Stammverzeichnis nach `config/` oder `.config/` verschieben Fuer jede Verschiebung: ```bash # Pruefen ob Datei irgendwo referenziert wird grep -r "filename" . # Wenn keine Referenzen oder nur relative Pfadreferenzen: mkdir -p target_directory/ git mv source/file target_directory/file # Alle Imports/Requires aktualisieren # (sprachspezifisch — siehe repair-broken-references Skill) ``` **Erwartet:** Alle Dateien an konventionellen Positionen; Git-Historie ueber `git mv` erhalten **Bei Fehler:** Wenn Verschieben Imports bricht, Importpfade aktualisieren oder eskalieren ### Schritt 3: README-Aktualitaet pruefen Veraltete Informationen in allen README-Dateien identifizieren. **Veralterungsindikatoren**: 1. Letzte Aenderung vor >6 Monaten 2. Referenzen auf alte Versionsnummern 3. Defekte Links oder Code-Beispiele 4. Fehlende Abschnitte (Installation, Verwendung, Mitwirkung) 5. Kein Lizenz-Badge oder defekte Badge-Links ```bash # Alle READMEs finden find . -name "README.md" -o -name "readme.md" # Fuer jede README: # - Letztes Aenderungsdatum pruefen git log -1 --format="%ci" README.md # - Auf defekte Links pruefen markdown-link-check README.md # - Beispielcode auf Funktionsfaehigkeit pruefen (erstes Beispiel testen) ``` **Erwartet:** Liste veralteter READMEs in `readme_freshness.txt` mit konkreten Problemen **Bei Fehler:** Wenn markdown-link-check nicht verfuegbar, externe Links manuell pruefen ### Schritt 4: Veraltete READMEs aktualisieren Defekte Links reparieren, Beispiele aktualisieren, fehlende Abschnitte ergaenzen. **Standard-Korrekturen**: 1. Defekte Badge-URLs ersetzen 2. Versionsnummern in Installationsanweisungen aktualisieren 3. Defekten Beispielcode reparieren (zur Verifizierung ausfuehren) 4. Fehlende Abschnitte ergaenzen (Vorlage aus Projektkonventionen verwenden) 5. Copyright-Jahr aktualisieren **README-Vorlagenstruktur**: ```markdown # Projektname Kurzbeschreibung (1-2 Saetze). ## Installation ```bash # Sprachspezifischer Installationsbefehl ``` ## Verwendung ```language # Grundlegendes Beispiel ``` ## Dokumentation Link zur vollstaendigen Dokumentation. ## Mitwirkung Link zu CONTRIBUTING.md oder eingebettete Richtlinien. ## Lizenz LIZENZ-Badge und Link. ``` **Erwartet:** Alle READMEs aktualisiert; Beispiele auf Funktionsfaehigkeit verifiziert **Bei Fehler:** Wenn Beispielcode nicht verifizierbar, mit Warnkommentar markieren ### Schritt 5: Konfigurationsdateien ueberpruefen Konfigurationsdrift identifizieren und doppelte Einstellungen konsolidieren. **Haeufige Konfigurationsprobleme**: 1. Mehrere `.env`-Dateien (`.env`, `.env.local`, `.env.dev`, `.env.prod`) 2. Doppelte Einstellungen ueber Konfigurationsdateien hinweg 3. Hartcodierte Geheimnisse (sollten Umgebungsvariablen verwenden) 4. Veraltete API-Endpunkte oder Feature-Flags ```bash # Alle Konfigurationsdateien finden find . -name "*.config.*" -o -name ".env*" -o -name "*.yml" -o -name "*.yaml" # Fuer jede Konfiguration: # - Auf doppelte Schluessel pruefen # - Nach hartcodierten Geheimnissen suchen (API-Schluessel, Token, Passwoerter) grep -E "(api[_-]?key|token|password|secret)" config_file # - Dev- vs Prod-Einstellungen vergleichen diff .env.dev .env.prod ``` **Erwartet:** Konfigurationsdrift in `config_review.txt` dokumentiert; Geheimnisse zur Eskalation markiert **Bei Fehler:** Wenn Diff grosse Abweichungen zeigt, an devops-engineer eskalieren ### Schritt 6: Veraltete Dateien archivieren Nicht mehr benoetigte Dateien verschieben oder loeschen. **Kandidaten fuer Archivierung**: - Auskommentierte Konfigurationsdateien (z.B. `nginx.conf.old`) - Altskripte die seit >1 Jahr nicht ausgefuehrt wurden - Sicherungsdateien (z.B. `file.bak`, `file~`) - Versehentlich committete Build-Artefakte **Archivierungsprozess**: ```bash # Archivverzeichnis erstellen (wenn archive_mode=move) mkdir -p archive/YYYY-MM-DD/ # Fuer jede veraltete Datei: # 1. Pruefen ob nirgends referenziert grep -r "filename" . # 2. Git-Historie auf letzte Aenderung pruefen git log -1 --format="%ci" filename # 3. Wenn seit >1 Jahr nicht geaendert und keine Referenzen: if [ "$archive_mode" = "move" ]; then git mv filename archive/YYYY-MM-DD/ else git rm filename fi # 4. In ARCHIVE_LOG.md dokumentieren echo "- filename (Grund, letzte Aenderung: DATUM)" >> ARCHIVE_LOG.md ``` **Erwartet:** Veraltete Dateien archiviert; `ARCHIVE_LOG.md` aktualisiert **Bei Fehler:** Wenn unsicher ob Datei veraltet ist, belassen und im Bericht dokumentieren ### Schritt 7: Namenskonventionen ueberpruefen Auf inkonsistente Dateibenennung im Projekt pruefen. **Gaengige Konventionen**: - **kebab-case**: `my-file.js` (ueblich in JS/Web-Projekten) - **snake_case**: `my_file.py` (Python-Standard) - **PascalCase**: `MyComponent.tsx` (React-Komponenten) - **camelCase**: `myUtility.js` (JavaScript-Funktionen) ```bash # Dateien finden die gegen Konventionen verstossen # Beispiel: Python-Projekt mit erwarteter snake_case find . -name "*.py" | grep -v "__pycache__" | grep -E "[A-Z-]" # Fuer jeden Verstoss entweder: # 1. Umbenennen um Konventionen einzuhalten # 2. Ausnahme dokumentieren (z.B. Django settings.py Konvention) ``` **Erwartet:** Alle Dateien folgen Namenskonventionen oder Ausnahmen dokumentiert **Bei Fehler:** Wenn Umbenennung Imports bricht, Referenzen aktualisieren oder eskalieren ### Schritt 8: Bereinigungsbericht erstellen Alle strukturellen Aenderungen dokumentieren. ```markdown # Projektstruktur-Bereinigungsbericht **Datum**: JJJJ-MM-TT **Projekt**: ## Verzeichnisaenderungen - X Dateien in konventionelle Verzeichnisse verschoben - Y neue Verzeichnisse erstellt - Z veraltete Dateien archiviert ## README-Aktualisierungen - W veraltete READMEs aktualisiert - X defekte Links repariert - Y Code-Beispiele verifiziert ## Konfigurationsbereinigung - X doppelte Einstellungen konsolidiert - Y hartcodierte Geheimnisse zur Entfernung markiert - Z Konfigurationsdrift-Probleme dokumentiert ## Archivierte Dateien Siehe ARCHIVE_LOG.md fuer vollstaendige Liste (Z Dateien). ## Namenskonventionskorrekturen - X Dateien entsprechend Konventionen umbenannt - Y Ausnahmen dokumentiert ## Eskalierungen - [Konfigurationsdrift erfordert DevOps-Pruefung] - [Hartcodierte Geheimnisse erfordern Sicherheitsaudit] ``` **Erwartet:** Bericht in `TIDYING_REPORT.md` gespeichert **Bei Fehler:** (Entfaellt — Bericht unabhaengig generieren) ## Validierung Nach der Bereinigung: - [ ] Alle Dateien in konventionellen Verzeichnissen - [ ] Keine defekten Links in READMEs - [ ] README-Beispiele auf Funktionsfaehigkeit verifiziert - [ ] Konfigurationsdateien auf Geheimnisse geprueft - [ ] Veraltete Dateien mit Dokumentation archiviert - [ ] Namenskonventionen konsistent - [ ] Git-Historie erhalten (verwendet `git mv`, nicht `mv`) - [ ] Tests bestehen nach Verschiebungen weiterhin ## Haeufige Stolperfallen 1. **Relative Imports brechen**: Verschieben von Dateien bricht relative Importpfade. Alle Referenzen aktualisieren oder absolute Imports verwenden. 2. **Git-Historie verlieren**: Verwendung von `mv` statt `git mv` verliert Dateihistorie. Immer Git-Befehle fuer Verschiebungen verwenden. 3. **Ueberorganisation**: Zu viele verschachtelte Verzeichnisse erschweren die Navigation. Flach halten bis Komplexitaet Struktur erfordert. 4. **Loeschen statt Archivieren**: Direktes Loeschen verliert Wiederherstellungsmoeglichkeit. Immer zuerst archivieren wenn nicht sicher. 5. **Sprachkonventionen ignorieren**: Persoenliche Vorlieben ueber Sprachstandards stellen. Etablierte Konventionen befolgen. 6. **Dokumentation nicht aktualisieren**: Dateien verschieben ohne README-Pfade anzupassen hinterlaesst defekte Dokumentation. ## Verwandte Skills - [clean-codebase](../clean-codebase/SKILL.md) — Toten Code entfernen, Lint-Warnungen beheben - [repair-broken-references](../repair-broken-references/SKILL.md) — Links und Imports nach Verschiebungen reparieren - [escalate-issues](../escalate-issues/SKILL.md) — Komplexe Konfigurationsprobleme an Spezialisten weiterleiten - [devops/config-management](../../devops/config-management/SKILL.md) — Erweiterte Konfigurationskonsolidierung - [compliance/documentation-audit](../../compliance/documentation-audit/SKILL.md) — Umfassende Dokumentationspruefung