Was macht shiplog?
Erfasse und durchsuche Entscheidungen, Abwägungen und Erkenntnisse deiner Codebasis direkt in GitHub, um einen klaren und dauerhaften Projektkontext zu bewahren.
Übersicht
Shiplog bietet eine einfache Möglichkeit, wichtige Informationen aus dem Entwicklungsprozess strukturiert abzulegen und später wiederzufinden. Anstatt Kontext nur in Commit-Messages oder flüchtigen Notizen zu hinterlassen, erzeugst du mit Shiplog persistente Einträge als GitHub Issues. Jeder Eintrag kann eine Entscheidung, einen gefundenen Fehler, einen Kompromiss oder eine neue Erkenntnis dokumentieren.
Anwendungsfälle
- Entscheidungen festhalten: Warum wurde ein bestimmter Algorithmus gewählt? Welche Alternativen wurden verworfen?
- Trade-offs dokumentieren: Welche Nachteile wurden in Kauf genommen, um einen Vorteil zu erzielen?
- Entdeckungen teilen: Ein unerwartetes Verhalten einer Bibliothek oder ein Performance-Engpass.
- Projektkontext für KI-Agenten bereitstellen: Claude Code, Cursor oder Codex können über Shiplog auf das gesammelte Wissen zugreifen.
Funktionsweise
Shiplog nutzt normale GitHub Issues mit einem speziellen Label (z. B. shiplog). Die Einträge werden in einem definierten Markdown-Format verfasst, das Titel, Datum, Kategorie und eine ausführliche Beschreibung enthält. Über die Suchfunktion kannst du nach Schlagworten, Labels, Datumsbereichen oder Autoren filtern.
Beispiel eines Eintrags
---
title: „Wechsel von REST zu GraphQL für die API-Schnittstelle“
category: Entscheidung
date: 2024-03-15
---
## Kontext
Die bisherige REST-API führte zu vielen Over-Fetching-Problemen und mehreren Roundtrips pro Ansicht.
## Entscheidung
Wir haben uns für GraphQL entschieden, weil es eine flexible Abfrage der benötigten Felder erlaubt und die Anzahl der Netzwerkanfragen reduziert.
## Alternativen
- REST mit speziellen Endpunkten (verworfen wegen hoher Wartungskosten)
- gRPC (nicht geeignet für unsere heterogenen Clients)
## Konsequenzen
- Erhöhte Komplexität auf dem Server durch Schema-Design
- Deutlich bessere Performance für komplexe Ansichten
Befehle (Beispiele)
shiplog new– Erstelle einen neuen Eintrag (interaktiv)shiplog search <suchbegriff>– Durchsuche vorhandene Einträgeshiplog list --category <kategorie>– Liste nach Kategorie gefiltert aufshiplog show <issue-nummer>– Zeige einen bestimmten Eintrag an
Plattformen
Dieser Skill wurde getestet mit:
- Claude Code
- Cursor
- Codex CLI
Er sollte jedoch mit jedem Tool funktionieren, das auf die GitHub-API zugreifen kann.
Konfiguration
Stelle sicher, dass du in deiner Umgebung ein persönliches GitHub-Token mit den Berechtigungen repo und issues:write gesetzt hast:
export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
export GITHUB_REPOSITORY=dein-username/dein-repo