<img src="banner.png" width="100%" alt="pipeline-optimizer banner">

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 "<keyword>" 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/<name>/SKILL.md	Projekt-Skills

Eigenes Projekt-Doku-Template (empfohlen)

Falls du ein eigenes Projekt-Doku-Template pflegst (z.B. unter <dein-workspace>/_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)