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

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:

# Check if file is referenced anywhere
grep -r "filename" .

# If no references or only relative path references:
mkdir -p target_directory/
git mv source/file target_directory/file

# Update any imports/requires
# (language-specific — see 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

# Find all READMEs
find . -name "README.md" -o -name "readme.md"

# For each README:
# - Check last modified date
git log -1 --format="%ci" README.md

# - Check for broken links
markdown-link-check README.md

# - Verify example code still runs (sample first example)

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

```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

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

# Create archive directory (if archive_mode=move)
mkdir -p archive/YYYY-MM-DD/

# For each deprecated file:
# 1. Verify not referenced anywhere
grep -r "filename" .

# 2. Check git history for last modification
git log -1 --format="%ci" filename

# 3. If not modified in >1 year and no references:
if [ "$archive_mode" = "move" ]; then
  git mv filename archive/YYYY-MM-DD/
else
  git rm filename
fi

# 4. Document in ARCHIVE_LOG.md
echo "- filename (reason, last modified: DATE)" >> 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)

# Find files violating conventions
# Example: Python project expecting snake_case
find . -name "*.py" | grep -v "__pycache__" | grep -E "[A-Z-]"

# For each violation, either:
# 1. Rename to match conventions
# 2. Document exception (e.g., Django settings.py convention)

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