lesson-learned

Überblick über den lesson-learned-Skill

Der lesson-learned-Skill macht aus aktueller Git-Aktivität konkrete Learnings für die Softwareentwicklung. Statt abstrakte Ratschläge zu geben, prüft er echte Diffs, die Commit-Historie und geänderte Dateien und ordnet das Geschehene benannten Prinzipien wie SRP, DRY, KISS, YAGNI und verwandten Anti-Patterns zu. Am nützlichsten ist lesson-learned daher für Entwickler, die bereits Code geändert haben und nun verstehen wollen: Was haben wir aus dieser Arbeit gelernt, welchen Trade-off sind wir eingegangen, und was sollten wir beim nächsten Mal wiederholen oder vermeiden?

Für wen der lesson-learned-Skill geeignet ist

Am besten passt der Skill für:

• Entwickler, die gerade ein Feature, Refactoring, Bugfix oder Cleanup abgeschlossen haben
• Reviewer, die nach einer PR eine lernorientierte Zusammenfassung wollen
• Team Leads, die leichte Engineering-Reflexionsroutinen etablieren möchten
• Agents, die das Prinzip hinter aktuellen Codeänderungen erklären sollen

Wenn du Design-Reflexion auf Basis echter Repository-Historie willst, ist der lesson-learned skill deutlich stärker als ein generischer Prompt wie „review this code“.

Welche Aufgabe der Skill tatsächlich übernimmt

Die Kernaufgabe ist kein klassisches Code Review im Sinne von bestanden/nicht bestanden. lesson-learned schaut rückwärts auf abgeschlossene oder laufende Arbeit und extrahiert 1–3 Erkenntnisse, die sich durch den Diff belegen lassen. Gute Ausgaben enthalten meist:

• den Namen des Prinzips
• wie die Änderung dieses Prinzip zeigt
• warum das relevant ist
• eine Empfehlung für den nächsten Schritt

Genau dieses Format macht den Skill besonders nützlich für Retrospektiven, Mentoring und Lernnotizen zu PRs.

Was lesson-learned von einem generischen Prompt unterscheidet

Zwei Punkte sind hier entscheidend:

1. Der Skill ist Git-History-getrieben und analysiert deshalb echte Änderungen statt hypothetischer Snippets.
2. Er setzt einen Prinzipien-Katalog voraus, insbesondere references/se-principles.md, damit das Modell Muster konsistent benennen kann.

Diese Kombination hilft dem Skill, Erkenntnisse zu liefern, die sich wirklich aus dem Code ergeben und nicht wie aus einem Lehrbuch für Software Engineering kopiert wirken.

Wann du lesson-learned nicht wählen solltest

Verzichte auf lesson-learned, wenn dein eigentliches Ziel ist:

• Bugs Zeile für Zeile vor dem Merge zu finden
• ein Security Audit durchzuführen
• ausschließlich Stil- oder Lint-Feedback zu bekommen
• Architektur zu planen, obwohl noch keine Codeänderungen existieren
• eine große Codebasis ohne klaren Scope zu prüfen

In solchen Fällen ist ein Skill für Code Review, Security oder Design meist das bessere erste Werkzeug.

So verwendest du den lesson-learned-Skill

lesson-learned-Installationskontext

Das Repository veröffentlicht in skills/lesson-learned/SKILL.md keinen eigenen Installationsbefehl. Wie die Installation aussieht, hängt also davon ab, wie du Skills aus softaworks/agent-toolkit lädst. Wenn deine Umgebung das Hinzufügen eines Skills direkt aus diesem Repository unterstützt, ist das übliche Muster:

npx skills add softaworks/agent-toolkit --skill lesson-learned

Wenn dein Agent Skills direkt aus dem Repo lädt, verwende den Skill-Pfad:

skills/lesson-learned

Wichtig in beiden Fällen: Betrachte SKILL.md als Spezifikation für das Laufzeitverhalten, nicht nur als README.

Diese Dateien solltest du vor dem ersten Einsatz lesen

Für einen schnellen Start mit möglichst wenig Rätselraten lies die Dateien in dieser Reihenfolge:

1. skills/lesson-learned/SKILL.md
2. skills/lesson-learned/references/se-principles.md
3. skills/lesson-learned/references/anti-patterns.md
4. skills/lesson-learned/README.md

Das wichtigste Detail für die Einführung ist leicht zu übersehen: Der Skill sagt ausdrücklich, dass du nicht weitermachen sollst, bevor se-principles.md geladen wurde.

Welche Eingaben der lesson-learned-Skill braucht

Die lesson-learned usage funktioniert am besten, wenn das Modell Zugriff auf Folgendes hat:

• ein Repository mit Git-Historie
• den aktuellen Branch-Namen oder ein benanntes Vergleichsziel wie main
• einen Commit-Bereich, eine Commit-SHA, einen Branch-Diff oder einen Working-Tree-Diff
• genug Dateikontext, um die am stärksten geänderten Dateien zu prüfen

Ohne Git-Kontext wird die Ausgabe sehr schnell generisch.

Wähle zuerst den richtigen Analysescopе

Dieser Skill ist nur so gut wie der Scope, den du vorgibst. Das Repository definiert dafür praxistaugliche Defaults:

• Feature-Branch: Branch-Arbeit mit main vergleichen
• main-Branch: die letzten 5 Commits analysieren
• bestimmter Commit: genau eine SHA prüfen
• uncommittete Änderungen: unstaged und staged Diffs prüfen

Ein gutes lesson-learned guide beginnt damit, diese Entscheidung früh zu erzwingen. Wenn der Scope unscharf bleibt, vermischt das Ergebnis meist mehrere voneinander unabhängige Erkenntnisse.

Nützliche Git-Befehle für bessere lesson-learned-Nutzung

Der Workflow des Skills basiert auf typischen Git-Ansichten wie:

• git log main..HEAD --oneline
• git diff main...HEAD
• git log --oneline -5
• git diff HEAD~5..HEAD
• git show <sha>
• git diff
• git diff --cached

Du brauchst nicht jedes Mal alle Befehle. Nimm den, der zu der Entwicklungsgeschichte passt, die der Skill erklären soll.

So wird aus einer vagen Anfrage ein starker Prompt

Schwacher Prompt:

“Reflect on my recent work.”

Stärkerer Prompt:

“Use lesson-learned on my feature branch versus main. Read references/se-principles.md first. Focus on the 3 files with the largest behavioral changes. Give me 2 lessons grounded in the diff, each with the principle name, code evidence, trade-off, and one thing I should repeat in future PRs.”

Warum das funktioniert:

• der Scope ist klar definiert
• die Referenzdatei, von der der Skill abhängt, wird explizit benannt
• die Analysefläche wird begrenzt
• das gewünschte Ausgabeformat ist vorgegeben

Prompt-Muster für lesson-learned in Code Reviews

lesson-learned for Code Review funktioniert am besten als Reflexionsschicht nach einem normalen Review, nicht als dessen Ersatz. Ein praxistauglicher Prompt ist:

“Run lesson-learned on this PR branch against main. Summarize the engineering lesson behind the changes, not just defects. Highlight 1 positive principle demonstrated, 1 anti-pattern risk if relevant, and cite the changed files that support each point.”

Das ist besonders nützlich, wenn du einen Review-Kommentar willst, der etwas vermittelt und nicht nur blockiert.

Empfohlenes Ausgabeformat

Bitte um eine kompakte Struktur wie:

• Lesson
• Principle
• Evidence from changes
• Why it matters
• Next step

Das passt zur Absicht des Repositorys und reduziert generisches Füllmaterial.

So gehst du mit großen Diffs um

Bei großen PRs solltest du den Skill nicht bitten, „alles zu analysieren“. Stattdessen:

• die am stärksten geänderten Dateien identifizieren
• Änderungen thematisch clustern
• offensichtliche mechanische Edits ignorieren
• nur 1–3 Erkenntnisse anfordern

Der Skill ist stark darin, Muster herauszuarbeiten, nicht darin, jede einzelne Dateiveränderung vollständig zu katalogisieren.

Typischer Workflow, der Zeit spart

Ein verlässlicher Ablauf ist:

1. se-principles.md laden
2. Scope festlegen
3. Git-Log und Diff prüfen
4. die am stärksten geänderten Dateien lesen
5. optional anti-patterns.md laden
6. 1–3 Erkenntnisse mit Belegen erzeugen
7. nachschärfen, falls das Ergebnis zu breit oder zu moralisierend ist

Diese Reihenfolge ist wichtig, weil der Prinzipien-Katalog der Analyse ein deutlich robusteres Vokabular gibt.

lesson-learned-Skill FAQ

Ist lesson-learned gut für Einsteiger?

Ja, sofern Einsteiger echte Änderungen zum Analysieren haben. Der Skill erklärt Prinzipien anhand der Arbeit, die gerade erledigt wurde. Das ist oft leichter zugänglich, als zuerst nur Theorie zu lesen. Weniger nützlich ist er für Personen ohne Repo-Zugriff oder ohne aktuelle Diffs.

Ist lesson-learned dasselbe wie Code Review?

Nein. lesson-learned ist rückblickend und prinzipienorientiert. Code Review fokussiert sich in der Regel stärker auf Korrektheit, Risiken und Wartbarkeit. Es gibt Überschneidungen, aber das Ziel der Ausgabe ist ein anderes.

Braucht der lesson-learned-Skill Zugriff auf Git?

Für starke Ergebnisse: ja. Das Repository ist klar um Git-Historie und Diffs herum aufgebaut. Wenn du nur ein Code-Snippet einfügst, kann das Modell zwar weiterhin Prinzipien kommentieren, nutzt den Skill dann aber nicht mehr in seiner stärksten Form.

Was macht lesson-learned besser als einen normalen Prompt?

Der Vorteil liegt in der Struktur: explizite Scope-Wahl, verpflichtende Prinzipien-Referenzen und ein Workflow, der Erkenntnisse an konkrete Signale im Code zurückbindet. Normale Prompts springen oft direkt zu generischen „best practices“.

Kann ich lesson-learned auf uncommittete Änderungen anwenden?

Ja. Der Skill unterstützt Working Changes über git diff und git diff --cached. Das ist besonders hilfreich vor einem Commit, wenn du verstehen willst, welche Erkenntnis oder welcher Trade-off in dem steckt, was du gleich auslieferst.

Wann passt lesson-learned schlecht?

Verzichte darauf, wenn:

• es keine sinnvollen aktuellen Änderungen gibt
• der Diff überwiegend aus generiertem Code oder Formatierungsrauschen besteht
• du eher Defekt-Triage als Reflexion brauchst
• der Branch viele voneinander unabhängige Aufgaben bündelt

In solchen Fällen solltest du den Scope enger ziehen oder zuerst einen anderen Skill verwenden.

So verbesserst du den lesson-learned-Skill

Gib lesson-learned eine engere Geschichte

Der größte Hebel für Qualität ist der Scope. „Meine Arbeit aus dem letzten Monat“ ist zu breit. „Dieses Refactoring, das API-Calls von UI-Rendering getrennt hat“ ist deutlich besser. Ein enger Scope führt zu präziseren Erkenntnissen, klareren Prinzipien und belastbareren Belegen.

Lade die Prinzipien-Referenz jedes Mal

Hier ist das Repository ungewöhnlich eindeutig: references/se-principles.md sollte vor der Analyse geladen werden. Wenn du das auslässt, liefert das Modell zwar oft trotzdem Beobachtungen, benennt Muster aber seltener konsistent und verknüpft sie schlechter mit anerkannten Prinzipien.

Nutze Anti-Patterns für Balance, nicht für Negativität

references/anti-patterns.md hilft vor allem dann, wenn der Diff Risikosignale enthält, etwa verstreute Änderungen, Überabstraktion oder wachsende „god“ modules. Bitte um eine zurückhaltende Formulierung, damit das Ergebnis nützlich bleibt und nicht belehrend oder strafend klingt.

Verlange Belege, die an geänderte Dateien gebunden sind

Ein typischer Fehlmodus sind allgemeine Ratschläge ohne Nachweis. Bessere lesson-learned-Ausgaben bekommst du, wenn du explizit nach Folgendem fragst:

• beteiligte geänderte Dateien
• welche strukturelle Änderung stattgefunden hat
• welchen Trade-off sie impliziert
• warum das einem bestimmten Prinzip zugeordnet wird

Diese Belege trennen echte Erkenntnisse von generischem Kommentar.

Begrenze die Zahl der Erkenntnisse

Mehr Erkenntnisse bedeuten meist schwächere Erkenntnisse. Fordere nur 1–3 Learnings an. Das erzwingt Priorisierung und macht die Ausgabe glaubwürdiger und leichter nutzbar für PR-Notizen, Retrospektiven oder Coaching.

Sag dem Skill, welche Art von Erkenntnis du willst

Du kannst die Analyse gezielt über eine Perspektive steuern:

• Erkenntnis zur Wartbarkeit
• Erkenntnis zum Refactoring
• Erkenntnis zum Bugfix
• Erkenntnis zu Design-Trade-offs
• Erkenntnis zum Teamprozess, gebunden an Codeänderungen

Das erhöht die Relevanz, ohne gegen den eigentlichen Workflow des Skills zu arbeiten.

Korrigiere generische Erstentwürfe mit einem zweiten Durchgang

Wenn das erste Ergebnis vage bleibt, starte nicht sofort komplett neu. Bitte stattdessen um Folgendes:

• “Tie each lesson to a specific file or diff hunk.”
• “Replace general advice with what this branch actually demonstrates.”
• “Name the principle only if the code evidence clearly supports it.”
• “Drop any lesson that is not visible in the diff.”

Das verbessert die Ausgabe meist schneller als ein komplett neuer, breiter Prompt.

Achte auf diese typischen lesson-learned-Fehlmuster

Schwache Ausgaben erkennt man oft an folgenden Punkten:

• Prinzipien werden ohne Code-Belege benannt
• aus einem Diff werden zu viele Erkenntnisse gezogen
• Defekte aus dem Code Review werden mit Lernpunkten verwechselt
• moralisierende Sprache statt praktischer Trade-offs
• voneinander unabhängige Änderungen werden zu einer einzigen Erkenntnis zusammengezogen

Wenn du das früh erkennst, lässt sich die Iteration meist unkompliziert nachschärfen.

Bester Verbesserungsweg für wiederkehrende Team-Nutzung

Wenn ein Team lesson-learned regelmäßig einsetzen will, sollte es ein Prompt-Template standardisieren mit:

• Scope-Regel
• Vergleichsziel
• maximaler Zahl an Erkenntnissen
• verpflichtendem Belegformat
• optionalem Anti-Pattern-Check

Das reduziert Inkonsistenzen und macht den lesson-learned skill über PRs und Retrospektiven hinweg deutlich verlässlicher.