pjt222/tidy-project-structure

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:

# 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

# 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:

# Projektname

Kurzbeschreibung (1-2 Saetze).

## Installation

```bash
# Sprachspezifischer Installationsbefehl

Verwendung

# 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:

# 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)

# 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.

# Projektstruktur-Bereinigungsbericht

**Datum**: JJJJ-MM-TT
**Projekt**: <projektname>

## 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 — Toten Code entfernen, Lint-Warnungen beheben
• repair-broken-references — Links und Imports nach Verschiebungen reparieren
• escalate-issues — Komplexe Konfigurationsprobleme an Spezialisten weiterleiten
• devops/config-management — Erweiterte Konfigurationskonsolidierung
• compliance/documentation-audit — Umfassende Dokumentationspruefung