von Changelog AI (LX AI)

Entwickler- vs Kundenton-Voreinstellungen für dieselben Commits

Entwickler wollen Details; Kunden wollen Vorteile. Ton-Voreinstellungen erstellen beides; die Bedeutung von SemVer bleibt Ihr Vertrag.

Warum separate Tone-Vorlagen?

Ich habe dieses Projekt gestartet, weil ich sah, dass Teams Zeit verschwenden, indem sie denselben Changelog-Eintrag für zwei verschiedene Leser neu schreiben. Ingenieure müssen sehen, was sich im Code geändert hat, welche Dateien bearbeitet wurden und ob interne APIs gebrochen wurden. Produktmanager, Support-Mitarbeiter und Endbenutzer interessieren sich dafür, was die Änderung für sie bedeutet: neue Funktionen, behobene Fehler, verbesserte Leistung oder entfernte Grenzen. Ein einziger Ton kann beiden Gruppen nicht gut dienen. Durch die Erstellung von zwei unterschiedlichen Vorlagen, die auf der gleichen Commit-Liste operieren, bleibt die Quelle der Wahrheit unverändert, während maßgeschneiderte Nachrichten geliefert werden. Dieser Ansatz ermöglicht es auch, dass das SemVer-Label die einzige Quelle des vertraglichen Sinns bleibt, da das Label an die Commit-Gruppe und nicht an die Formulierung angehängt ist.

Entwicklerton vorbelegt: detailorientiert

Commit-Ebene-Details

Wenn die Entwicklervorbelegung aktiv ist, erweitert die KI jeden Commit in einen Satz, der den Dateipfad, die geänderte Funktion oder Klasse und die Art der Änderung (Hinzufügung, Löschung, Refactoring) enthält. Beispielsweise wird ein Commit, der einen Nullzeiger in src/api/user.go behebt, zu: „Behoben: Nullzeiger-Verweis in GetUserByID, wenn die eingehende ID Null ist, hinzugefügt: Schutzklausel und Einheitstest.“

Verknüpfung mit Tracking-Systemen

Wenn die Commit-Meldung eine Problem-ID (z. B. ABC-123) enthält, umschließt die Vorbelegung sie mit einem Link zum Tracker, unter der Annahme, dass das Team die Basis-URL konfiguriert hat. Dies ermöglicht es Ingenieuren, direkt zur Diskussion oder zum Design-Dokument zu springen, ohne die Änderungshistorie zu verlassen.

Einschließung technischer Kontexte

Die Vorbelegung fügt alle relevanten Compilerwarnungen, Änderungen der Testabdeckung oder Leistungsbenchmarks hinzu, die im CI-Lauf im Zusammenhang mit dem Commit aufgetreten sind. Dies bietet eine schnelle Gesundheitsprüfung für den geänderten Bereich.

Sicherheits- und Compliance-Prüfungen für LLM-Ausgaben

Da der Text von einem Sprachmodell generiert wird, führe ich ihn durch einen leichten Sicherheitsfilter, der auf unzulässige Inhalte prüft. Der Filter bezieht sich auf die OWASP-LLM-Top-10 für Prompt-Injektionsrisiken und den NIST-AI-Risikomanagement-Framework für die Verwaltung von Halluzinationen und Voreingenommenheit. Wenn ein Segment eine Regel auslöst, wird es vor der Veröffentlichung für eine menschliche Überprüfung gekennzeichnet.

Beispiel-Liste für eine typische Veröffentlichung

- Hinzugefügt: RetryPolicy-Schnittstelle in src/retry/policy.go, um pluggable Back-off-Strategien zuzulassen. - Entfernt: Veralteter LegacyCache-Struct aus src/cache/legacy.go; alle Aufrufer auf LRUCache migriert. - Behoben: Race-Bedingung in WorkerPool.Start, bei der ein nil-Kanal zweimal geschlossen werden konnte; hinzugefügt: Mutex-Schutz. - Aktualisiert: Go-Modul github.com/stretchr/testify von v1.7.0 auf v1.8.2, um Sicherheitspatch für Assert-Paket aufzunehmen. - Hinzugefügt: Benchmarks für JSONEncoder, die eine 12-prozentige Reduzierung der Speicherzuweisung für Payloads unter 10 KB zeigen.

Kundenton-Voreinstellung: Vorteil zuerst

Ergebnisorientierte Sprache

Mit der Kundenvoreinstellung schreibt die KI jeden Commit in einen Satz um, der beschreibt, was der Benutzer jetzt tun kann oder welches Problem gelöst ist. Technische Fachjargon wird durch einfache Begriffe ersetzt. Die gleiche Nullzeiger-Korrektur wird zu: „Benutzer werden keinen Fehler mehr sehen, wenn sie eine Nullwert-ID im Benutzersuchfeld eingeben.“

Vermeidung interner Identifikatoren

Commit-Hashes, Branch-Namen und interne Problemmnummern werden weggelassen, es sei denn, sie sind Teil eines öffentlichen Feature-Flags oder eines versionierten API-Endpunkts, auf den sich Kunden beziehen könnten. Das Ziel ist es, den Lärmpegel niedrig zu halten.

Hervorhebung der Benutzerauswirkung

Wenn ein Commit die Leistung verbessert, übersetzt die Voreinstellung den Benchmark-Gewinn in eine benutzerseitige Aussage: „Die Ladezeiten für Seiten sind jetzt bis zu 15% schneller auf mobilen Geräten.“ Wenn ein Commit eine Einschränkung entfernt, lautet es: „Sie können jetzt Dateien bis zu 100 MB hochladen, anstatt der vorherigen 25 MB-Grenze.“

Verknüpfung mit öffentlicher Dokumentation

Wenn eine Änderung einen öffentlichen API-Endpunkt oder eine Konfigurationsoption betrifft, fügt die Voreinstellung einen Link zum relevanten Dokumentationsabschnitt hinzu, unter der Annahme, dass die Dokumentations-Website einem vorhersehbaren URL-Muster folgt (z. B. https://docs.example.com/api/v2/users).

Beispielliste für die gleiche Version

- Wiederhollogik passt sich jetzt an vorübergehende Netzwerkglitches an, was die Anzahl der fehlgeschlagenen Uploads bei unzuverlässigen Verbindungen reduziert. - Alte Cache-Implementierung entfernt; der neue Cache verwendet weniger Speicher und löscht veraltete Einträge automatisch. - Ein seltener Absturz, der auftreten konnte, wenn viele Worker gleichzeitig gestartet wurden, wurde behoben. - Aktualisierte Bibliothek von Drittanbietern, um eine Sicherheitsmitteilung zu beheben; keine Aktion erforderlich. - JSON-Antworten sind jetzt leichter, was den Datenverbrauch bei gemessenen Verbindungen reduziert.

Von Commit-Diff zu zwei Erzählungen

Parsing und Gruppierung

Die Pipeline beginnt mit dem Ausführen von git log --pretty=format:%H %s %b --since="1 Woche ago", um Commits seit dem letzten Tag zu sammeln. Jeder Commit wird nach seinem konventionellen Commit-Typ (feat, fix, perf, refactor usw.) und seinem Umfang geparst. Commits mit dem gleichen Typ und SemVer-Implication werden zusammengefasst, da sie den gleichen Versionssprung teilen.

Anwenden von ton-spezifischen Prompts

Für jede Gruppe erstelle ich zwei Prompts: einen für die Entwickler-Voreinstellung und einen für die Kunden-Voreinstellung. Der Entwickler-Prompt fragt nach „einer detaillierten, technischen Beschreibung, die Dateinamen, Symbole und alle relevanten Test- oder Benchmark-Änderungen enthält“. Der Kunden-Prompt fragt nach „einer prägnanten, vorteilsorientierten Erklärung, die interne Fachjargon vermeidet und sich auf das konzentriert, was der Benutzer erlebt“. Die gleiche Liste von Commits speist beide Prompts, um sicherzustellen, dass die zugrunde liegenden Fakten identisch bleiben.

Mensch-im-Schleifensystem-Überprüfung

Die AI-Ausgabe landet in einem Entwurfseditor, in dem ein Maintainer jeden Satz akzeptieren, bearbeiten oder ablehnen kann. Ich habe festgestellt, dass die meisten Bearbeitungen kleine Wortänderungen und keine faktischen Änderungen sind, was zeigt, dass das Modell gut darin ist, der Quelle treu zu bleiben. Nach der Überprüfung wird der Entwurf in Markdown und dann in HTML für die Veröffentlichung gerendert.

Tabelle: Zuordnung von konventionellen Commit-Typen zu Ton-Phrasierungen

Commit-Typ | Entwickler-Phrasierungsbeispiel | Kunden-Phrasierungsbeispiel feat | Hinzugefügt ExportCSV-Methode zu ReportService, um Zeilen zu streamen und den Speicherbedarf zu reduzieren. | Sie können jetzt Berichte als CSV-Dateien direkt vom Export-Button herunterladen. fix | Behoben Deadlock in JobQueue.Push, wenn ein nil-Job unter hoher Last eingereiht wurde. | Jobs bleiben nicht mehr stecken, wenn das System beschäftigt ist. perf | Ersetzt O(n²)-Suche in TagIndex.Find durch eine Hash-Karte, um die Latenz von 12 ms auf 0,8 ms für 10.000 Tags zu reduzieren. | Tag-Suchen sind jetzt deutlich schneller, insbesondere bei großen Bibliotheken. refactor | Extrahiert PasswordValidator-Schnittstelle aus AuthHandler, um pluggable Stärke-Regeln zu ermöglichen. | Passwort-Anforderungen können jetzt ohne Änderung des Kern-Login-Codes angepasst werden. docs | Aktualisiert API.md mit neuer Beschreibung und Beispiel-Payload für den PATCH /users/:id-Endpunkt. | Das Hilfezentrum zeigt jetzt, wie man ein Benutzerprofil teilweise aktualisiert.

Bewahrung der SemVer-Bedeutung über verschiedene Töne hinweg

Die Regeln für Versionssprünge bleiben an Commits verankert

Das SemVer-Label wird allein durch die konventionellen Commit-Typen in der Gruppe bestimmt: Ein feat löst einen Minor-Sprung aus, ein fix einen Patch-Sprung und eine breaking change einen Major-Sprung. Da die Tone-Voreinstellungen die Commit-Nachrichten oder ihre Typen nicht ändern, ist die resultierende Versionsnummer identisch, egal ob man die Entwickler- oder die Kunden-Version liest.

Vertragliche Konsistenz

Ich behandele das SemVer-Tag als Vertrag zwischen dem Produzenten und dem Verbraucher der Software. Der Changelog ist lediglich ein menschenlesbarer Ausdruck dieses Vertrags. Durch die Bewahrung des unveränderten Vertrags können Teams auf automatisierte Tools (wie Release-Bots oder Abhängigkeitsprüfer) vertrauen, um die Version korrekt zu interpretieren, während der dualtonige Changelog die beiden Zielgruppen bedient, ohne Ambiguität zu erzeugen.

Beispiel für eine Major-Veröffentlichung

Angenommen, ein Commit fügt BREAKING CHANGE: entferne Legacy-v1-API hinzu. Die Entwickler-Voreinstellung wird die genauen Dateilöschungen und die erforderlichen Migrationschritte notieren. Die Kunden-Voreinstellung wird erklären, dass der alte API-Endpunkt nicht mehr verfügbar ist und die Benutzer auf die v2-Dokumentation verweist. In beiden Fällen ändert sich die Version von 2.4.1 zu 3.0.0, wodurch die vertragliche Bedeutung bewahrt wird.

Was dies nicht ist

Ich möchte klarstellen, was diese Methode nicht kann, damit Sie realistische Erwartungen haben.

- Sie garantiert nicht, dass jeder generierte Satz perfekt im Ton ist; gelegentlich kann über-technische Formulierung in den Kundenentwurf oder vage Nutzen-Sprache im Entwicklerentwurf erscheinen. Eine Überprüfung durch einen Menschen ist immer noch erforderlich.

- Es ist kein Ersatz für einen dedizierten technischen Autor oder einen Produktmarketer. Die KI beschleunigt den ersten Entwurf, aber Nuancen, Markenstimme und rechtliche Hinweise benötigen immer noch die Berührung eines Menschen.

- Sie eliminiert nicht die Notwendigkeit für saubere Commit-Hygiene. Wenn Commit-Mitteilungen vage sind oder die konventionelle Commit-Struktur fehlt, sind die Gruppen weniger genau und die Ausgabe weniger nützlich.

- Es ist kein Zauberwerkzeug, das automatisch jeden Regulator oder jede Barrierefreiheitsrichtlinie erfüllt. Die Sicherheitsprüfungen, die ich hinzugefügt habe, sind grundlegend; Sie sollten immer noch Ihre eigene Compliance-Überprüfung durchführen.

- Sie verspricht nicht, dass das Changelog niemals eine Änderung verpassen wird. Wenn ein Commit vom git-Log-Bereich ausgeschlossen wird (z. B. aufgrund eines flachen Klonens oder eines fehlerhaften Filters), wird es in keinem der Töne erscheinen.

Referenzen

- OWASP LLM Top 10 - NIST AI Risikomanagement-Framework