--- name: pipeline-optimizer version: 1.2.0 type: protocol author: Lukas Geiger (Methodik) + Claude (Verschriftlichung) created: 2026-05-16 updated: 2026-06-13 aliases: [projekt-ordner-optimizer, pipeline-renovierer, projekt-renovierer] description: > Strukturiertes 6-Schritte-Verfahren zur Verbesserung, Renovierung oder Umbau bestehender Pipelines, einzelner Projektordner, Doku-Strukturen oder Software-Stacks. Ansprechbar als "Pipeline-Optimizer" (für ganze Themen-Pipelines, z.B. eine Software-, Forschungs- oder Game-Dev-Pipeline) oder "Projekt-Ordner-Optimizer" (für einzelne Projektordner innerhalb einer Pipeline, z.B. ein einzelnes Software-Tool oder Paper-Projekt). Aktiviert sich bei Aufgaben wie "Pipeline X verbessern", "Stack optimieren", "Y umbauen", "Renovierung", "Pipeline-Refactoring", "Projekt-Ordner aufräumen", "Projektordner optimieren", "Ordnerstruktur verbessern", "Konventionen vereinheitlichen", "Doku-Konsolidierung", "in bestehendes System integrieren", oder bei substantiellen Eingriffen in etablierte Strukturen. Liefert Bausubstanz-Analyse, Zweck-Klärung, Ideal-Skizze, Lücken-Plan, empirische Schmerzpunkt-Identifikation und Retests mit frischen Subagenten. Verhindert parallele Standards, Duplikation und Pipeline-Brüche. standalone: true anthropic_compatible: true bach_compatible: true bach_origin: false category: dev tags: [pipeline, renovierung, refactoring, stack, workflow, lessons-learned] language: de status: active dependencies: tools: [] services: [] protocols: [] python: [] provenance: origin: "custom" origin_path: "~/.claude/skills/pipeline-optimizer/" origin_version: "1.1.1" last_sync_from_origin: "2026-05-16" last_sync_to_origin: null local_changes_since_sync: true --- # Pipeline-Optimizer / Projekt-Ordner-Optimizer **6-Schritte-Renovierung ohne Inkompatibilitäten** — anwendbar auf zwei Größenordnungen: | Trigger-Name | Anwendungsbereich | Beispiel | |---|---|---| | **Pipeline-Optimizer** | Ganze Pipelines, Stacks, Doku-Strukturen | Deine Themen-Pipelines, z.B. `software/`, `research/`, `games/`, ein Agenten-System | | **Projekt-Ordner-Optimizer** | Einzelne Projektordner innerhalb einer Pipeline | Ein Software-Tool, ein Paper-Projekt, ein Game-Projekt | Eine **Pipeline** meint hier eine themenbezogene Top-Level-Struktur, in der mehrere Projekte nach gemeinsamen Konventionen leben (z.B. eine Software-Pipeline mit Release-Regeln, eine Forschungs-Pipeline mit Publikationsverfahren). Beide nutzen denselben 6-Schritte-Workflow — der Unterschied liegt nur im **Scope** (Pipeline-weit vs. Einzelprojekt) und entsprechend in der Tiefe der Bausubstanz-Erfassung in Schritt A. ## Wann dieser Skill greift Der Skill greift, sobald du eine **bestehende** Struktur verbessern, umbauen oder erweitern sollst — nicht beim Greenfield-Bau. Konkrete Trigger: **Pipeline-Ebene** (Scope: ganze Pipeline): - „Pipeline X besser machen" - „Stack optimieren" - „Renovierung der Software-Pipeline" - „Doku-Konsolidierung in der Forschungs-Pipeline" - Substantieller Eingriff in eine Themen-Pipeline, zentrale `_tools/` oder System-Komponenten **Projektordner-Ebene** (Scope: einzelner Projektordner): - „Projektordner X aufräumen/optimieren" - „Ordnerstruktur in Y verbessern" - „Einzelnes Tool refactorieren" - „Paper-Projekt-Setup vereinheitlichen" - „Game-Projektordner an Pipeline-Standard anpassen" **Übergreifend:** - „X umbauen/integrieren in bestehendes Y" - „Refactoring", „Konsolidierung" - „Konventionen vereinheitlichen" - „in bestehendes System integrieren" ## Die Bausubstanz-Metapher Ein Haus zu renovieren erfordert zuerst zu wissen, **aus was es besteht** (Steine, Holz, Plastik), **wofür es da ist** (Berghütte, Softwareschmiede), und **wo es jetzt schon Funktionen erfüllt**. Dieselbe Disziplin gilt für Pipelines. --- ## Verfahren — 6 Schritte (NICHT überspringen, NICHT umsortieren) ### Schritt A — Bausubstanz erfassen **Frage:** Aus was besteht das Haus? **Pipeline-Scope** (alle Root-Dokus + Tools + Templates): - [ ] **Alle Root-Dokumente vollständig lesen** (nicht nur Snippets/Insertion-Points) - [ ] Template-Ordner (`_templates/`, `_TEMPLATES/`) und Tool-Ordner (`_tools/`) durchgehen - [ ] Policy-Dateien: z.B. GITHUB-POLICY.md, RELEASE-MANAGEMENT.md, QUALITY_RULES.md, NAMING-SYSTEM.md, Publikationsverfahren, … - [ ] Status-Snapshots: z.B. PROJECT_STATUS.md, Status-Übersichten, releases.json, Registry-Dateien - [ ] Checklisten: z.B. Release-Checklisten, Build-/PDF-Checklisten - [ ] Workflows: AGENTS.md, GUIDE.md, SKILL.md - [ ] Lessons-Learned-Dateien: LESSONS_LEARNED.md, MEMORY.md, Loop-State-Dateien **Projektordner-Scope** (Einzelprojekt-Substanz + relevante Pipeline-Konventionen): - [ ] **Alle Markdown- und Steuer-Dateien im Projektordner lesen** (README, CHANGELOG, AUFGABEN/TODO, DONE, KONZEPT, AKTIONSPLAN, Beweisnotizen, …) - [ ] **Code-Struktur erfassen:** src/, tests/, Build-Konfiguration (pyproject.toml, requirements.txt, Projekt-Manifeste, Toolchain-Dateien, …) - [ ] **Pipeline-Konventionen aus übergeordneter Pipeline berücksichtigen** (z.B. für ein Software-Projekt: GitHub-Policy, Naming-System, Release-Management, Templates) - [ ] **Bestehende Tools/Scripts im Projekt** scannen (`_tools/`, `_scripts/`, build_*.bat, START-Skripte) - [ ] **Konfigurationsdateien:** `.gitignore`, LICENSE, NOTICE, SECURITY.md, CODE_OF_CONDUCT.md **Anti-Pattern:** Mit `grep -l ""` Insertion-Points finden und dort einfügen, ohne den Kontext der Datei zu kennen. **Output:** Inventar-Notiz mit allen relevanten Konventionen, Tools, Templates auf gewähltem Scope. ### Schritt B — Zweck identifizieren **Frage:** Wofür existiert das Haus? Zweck explizit formulieren in 1-2 Sätzen. **Pipeline-Beispiele:** | Pipeline | Zweck | |---|---| | Software-Pipeline | Desktop-Anwendungen + Browser-Tools entwickeln, testen, in Stores/auf GitHub releasen | | Forschungs-Pipeline | Wissenschaftliche Papers schreiben, peer-reviewen, auf Repositorien/Preprint-Servern publizieren | | Game-Pipeline | Games entwickeln und auf der Zielplattform publishen | | Agenten-System | LLM-System zur Multi-Agent-Orchestrierung | **Projektordner-Beispiele:** | Projektordner | Zweck | |---|---| | `software/PlannerApp` | Planungs-Desktop-App, kommerziell, privates Repo | | `research/CosmologyModel` | Modell-Paper-Serie + numerische Berechnungen | | `games/SortingChaos` | Sortier-Game, Alpha-Stadium, Level-Progression | Der Zweck **lenkt jeden Eingriff** — Maßnahmen, die nicht dem Zweck dienen, fallen raus. ### Schritt C — Ideales Bild entwerfen **Frage:** Wie sähe ein perfektes Haus für diesen Zweck aus? - Aus eigener Sicht skizzieren (kurz, max. 10 Punkte) - Best-Practice-Vergleich heranziehen (z.B. Vercel-Stack für SaaS, scientific-python-stack für Forschung) - Nicht in Detail-Optimierung gehen — Top-Level-Skizze reicht **Output:** 5-10 Punkte „Idealzustand pro Pipeline" ### Schritt D — Lücken-Analyse + Plan **Vier Fragen pro Pipeline:** 1. **Was hat das Haus schon?** — Auch wenn anders gelöst als im Ideal, aber **funktional gleichwertig**. *Beispiel:* Ideal sagt „pip-licenses für Dritt-Lizenzen". Real: ein eigenes Generator-Script ist Wrapper drumherum → funktional gleichwertig, kein Eingriff nötig. 2. **Was behindert die Funktion?** — Bestehende Strukturen, die heute Brüche oder Mehraufwand verursachen. 3. **Was ist nicht funktional?** — Toter Code, veraltete Konventionen, ungenutzte Tools. 4. **Was würde Funktionen messbar verbessern?** — Konkrete Eingriffe mit erwartetem Nutzen. → Daraus **konkreter Plan**: - Was wird **neu gebaut**? - Was wird **erweitert**? - Was wird **abgerissen**? - Was bleibt **unverändert** (wichtig zu benennen!) **Output:** Plan-Tabelle mit Spalten *Eingriff* / *Bestehendes* / *Maßnahme* / *Begründung* ### Schritt E — Empirisch arbeiten Nicht nur top-down planen — Schmerzpunkte sammeln: - [ ] **Bekannte Bugs**: Issue-Tracker, AUFGABEN/TODO/DONE-Dateien - [ ] **Fehler-Historie**: Lessons-Learned-Dateien, Bugfix-Logs, Prüf-Registries - [ ] **Automatisierungs-Brüche**: „Was muss ich immer manuell machen?" - [ ] **User-Interview**: Gezielt fragen — Schmerzpunkte, Wünsche, Workarounds - [ ] **Selbsttest**: Pipeline durchspielen (neues Projekt anlegen, Build durchlaufen, Release simulieren) — wo bricht es? Die empirisch gefundenen Schmerzpunkte **priorisieren den Plan** aus Schritt D. ### Schritt F — Retests nach Umsetzung - [ ] **Frische Subagenten** beauftragen (unbelastet vom Renovierungs-Kontext), den geänderten Workflow durchzuspielen - [ ] **Messbare Vergleichswerte** vorher/nachher: Setup-Zeit, Fehlerquote, Anzahl manueller Schritte, Build-Zeit - [ ] **Anti-Regression-Check**: Funktionierten bestehende Workflows nach der Änderung weiterhin? - [ ] Falls **keine messbare Verbesserung** oder Regression: Renovierung **zurückrollen** oder nachjustieren ## Anti-Patterns (verboten) | Anti-Pattern | Schaden | Gegenmittel | |---|---|---| | Insertion-Points suchen statt Doku lesen | Parallele Standards | Schritt A vollständig | | „Best Practice von X" 1:1 übertragen | Inkompatibilität | Schritt D vergleicht funktional | | Neue Datei anlegen ohne Konvention zu prüfen | Duplikation (z.B. NOTICE.md ↔ THIRD_PARTY_LICENSES.txt) | Schritt A + Schritt D | | Top-down planen ohne Empirie | Lösung passt nicht zum Schmerzpunkt | Schritt E vor Plan-Abschluss | | Eigene Änderung nicht testen | Regression unentdeckt | Schritt F mit frischem Agenten | | „Klärung später" mit unklarem Status | User entdeckt Konflikt nachträglich | Bei Unsicherheit lieber Schritt D nochmal mit User durchgehen | ## Lehrbeispiel — NOTICE.md-Vorfall **Auftrag:** Pipeline-Verbesserungen in mehreren Themen-Pipelines (Software, Forschung, Games) umsetzen. **Fehler:** Schritt A übersprungen — nur Insertion-Points gesucht statt vollständige Policy-Dateien gelesen. **Folge:** `NOTICE.md` als „neue Lizenz-Datei" in 7 Dateien eingeführt, obwohl `THIRD_PARTY_LICENSES.txt` + ein eigener Lizenz-Generator (Wrapper um `pip-licenses`) bereits etabliert waren — dokumentiert in der GitHub-Policy der Pipeline (Pflichtdateien + Lizenz-Checkliste). Alle Software-Projekte hatten bereits THIRD_PARTY-Dateien. **Erkennung:** Erst nach Nachfrage des Users („ich bin recht sicher, dass wir schon ein Rechtemanagement hatten"). **Korrektur:** NOTICE.md aus dem Projekt-Template gelöscht, 6 weitere Dateien angepasst, der bestehende Lizenz-Generator statt `pip-licenses` referenziert. **Lehre:** Wäre Schritt A vollständig ausgeführt worden, wäre der Konflikt vor dem Schreiben erkannt worden. ## Faustregeln 1. **Bei „Pipeline verbessern" zuerst genauso lange lesen wie schreiben.** 2. **Kein neuer Standard ohne Beweis, dass kein bestehender existiert.** 3. **Bestehende Tools/Wrapper nutzen statt neue parallele.** 4. **„Mehr von demselben" ist meist schlechter als „Bestehendes erweitern".** 5. **Bei Konflikt zurückrollen** ist immer besser als zwei parallele Standards laufen lassen. ## Checkliste zum Abschluss Bevor du eine Pipeline-Renovierung als „erledigt" meldest: - [ ] Schritt A: Alle relevanten Root-Dokus gelesen? - [ ] Schritt B: Zweck der Pipeline in 1-2 Sätzen formuliert? - [ ] Schritt C: Idealbild skizziert (5-10 Punkte)? - [ ] Schritt D: Lücken-Analyse mit Tabelle (was bleibt / was erweitert / was neu / was weg)? - [ ] Schritt E: Empirie geprüft (Bugs, Lessons, Selbsttest, User-Interview)? - [ ] Plan mit User abgestimmt? - [ ] Schritt F: Mit frischem Subagenten getestet — Verbesserung messbar? - [ ] Keine parallelen Standards eingeführt? - [ ] Bei Konflikten zurückgerollt oder ehrlich Rechenschaft abgelegt? ## Optimale Projektordner-Struktur (für Projekt-Ordner-Optimizer) Wenn der Skill auf **einen einzelnen Projektordner** angewendet wird, hilft als Ideal-Referenz (Schritt C) folgende kombinierte Empfehlung: ### Anthropic-Standard (Claude Code) | Datei/Ordner | Funktion | |---|---| | `CLAUDE.md` (Root) | Auto-loaded von Claude Code, projektspezifische Anweisungen | | `.claude/settings.json` | Permissions, Env-Vars, Model-Auswahl (committed) | | `.claude/settings.local.json` | Lokale Overrides (NICHT committen, in `.gitignore`) | | `.claude/commands/*.md` | Custom Slash-Commands | | `.claude/agents/*.md` | Custom Subagents | | `.claude/skills//SKILL.md` | Projekt-Skills | ### Eigenes Projekt-Doku-Template (empfohlen) Falls du ein eigenes Projekt-Doku-Template pflegst (z.B. unter `/_templates/project-docs/`), lohnen sich **drei Ausbauprofile**. Beispiel-Aufteilung: **MINIMAL** liefert das Session-Kernset mit 7 Root-Files (`AGENTS.md`, `CLAUDE.md`, `README.md`, `START.md`, `STATE.md`, `TODO.md`, `DONE.md`) plus `_tools/`. **STANDARD** ergänzt `CHANGELOG.md`, `DECISIONS.md` und `PATTERNS.md`. **FULL** baut auf 14 Root-Files aus und ergänzt zusätzlich `ARCHITECTURE.md`, `WORKFLOWS.md`, `TOOLS.md`, `GLOSSARY.md` sowie `workflows/` und `.github/`. → **Bei neuen Projekten ein solches Template als Basis nutzen** (kopieren statt manuell anlegen). ### Pipeline-spezifische Ergänzungen (Beispiele) Je nach Pipeline kommen weitere Pflichtdateien hinzu — typische Muster: - **Software-Projekt:** LICENSE, CODE_OF_CONDUCT.md, SECURITY.md, CONTRIBUTING.md, THIRD_PARTY_LICENSES.txt (generiert), pyproject.toml/requirements.txt, Eintrag in der zentralen Release-Registry der Pipeline. → Falls vorhanden: Cookiecutter-Template der Pipeline nutzen. - **Forschungs-Projekt:** Konzept-Dokument, Aktionsplan, Publikationsplan, Archiv-/Quellen-/Ergebnis-/Daten-Ordner (`_archive/`, `_sources/`, `_results/`, `_data/`), `paper/` für LaTeX. Bei Beweisprojekten: eine Beweisnotiz-Datei mit Beweiskette und Status. - **Game-Projekt:** Projekt-Manifest und Toolchain-Dateien der Engine (z.B. bei Roblox/Rojo: default.project.json, rokit.toml, wally.toml, selene.toml), Game-Design-Dokument, `src/{server,client,shared}/` nach Engine-Konvention. ### Vollständige Detail-Referenz → Siehe **`references/optimal-project-structure.md`** in diesem Skill-Ordner. Enthält: - Beispiel-`settings.json` (Anthropic-Schema) - `.gitignore`-Pflichteinträge - Anti-Patterns (was NICHT in Projektordner) - Empfohlene Workflows pro Pipeline-Typ (Software/Forschung/Game) - YAML-Header-Konvention für Doku-Dateien - Auto-Check-Skizze ## Verwandte Skills (Wann statt diesem Skill?) | Skill | Wann nutzen | |---|---| | **`project-onboarding`** | EXTERNES bestehendes Repo ins eigene System aufnehmen | | Projekt-Bootstrapper (falls vorhanden) | NEUES Projekt in bestehender Pipeline anlegen (Greenfield, kein Umbau) | | Pipeline-Bootstrapper (falls vorhanden) | KOMPLETT NEUE Pipeline anlegen (seltener Fall) | | System-Onboarding (falls vorhanden) | Neuen Rechner einrichten | Der **Pipeline-Optimizer** ist für **Renovierung** zuständig, nicht Neubau oder Übernahme. Falls deine Skill-Sammlung einen Skill-Index hat, dort nach passenden Bootstrapping-Skills suchen. ## Querverweise - Detail-Referenz: `references/optimal-project-structure.md` (in diesem Skill-Ordner) - Anthropic Claude Code Docs: `https://docs.claude.com/en/docs/claude-code` - Falls vorhanden: globale User-Regeln (z.B. ein Abschnitt „Umbauten/Renovierungen" in deiner `~/CLAUDE.md`) und pipeline-spezifische Stack-Beschreibungen ## Scope-Wahl: Pipeline vs. Projektordner Wenn nicht klar ist, welcher Scope gemeint ist, **vor Schritt A klären**: | Indiz | Scope | |---|---| | „Die ganze Software-Pipeline verbessern" | Pipeline | | „Den Ordner von Tool X aufräumen" | Projektordner | | „Die zentrale Release-Registry synchronisieren" | Pipeline (zentrales Asset) | | „Den AssetBuilder im Game Y refactorieren" | Projektordner | | „Eine Prüf-Konvention pipeline-weit einführen" | Pipeline | | „Im Projekt Z eine Prüf-Datei anlegen" | Projektordner | Bei **Projektordner-Scope** zusätzlich immer kurz die übergeordneten Pipeline-Konventionen prüfen (Schritt A erweitert), damit der Eingriff zur Pipeline kompatibel bleibt. --- ## Changelog ### 1.2.0 (2026-06-13) - Erstveröffentlichung in der Skill-Bibliothek: persönliche Pfade, konkrete Pipeline-/Projektnamen und Verweise auf private Skills durch generische Beispiele ersetzt; Verfahren (6 Schritte, Anti-Patterns, Lehrbeispiel, Checklisten) unverändert ### 1.1.1 (2026-06-01) und früher - Interne Fassungen (privates Skill-Verzeichnis, vor Veröffentlichung)