Brancheneinstufung2/docs/README_dev_session.md

dev_session.py - Notion Development Session Manager

Übersicht

dev_session.py ist ein Kommandozeilen-Tool (CLI), das den Entwicklungs-Workflow durch die Integration mit Notion und Git optimiert. Es dient als Brücke zwischen der interaktiven Gemini CLI-Sitzung und dem Projektmanagement in Notion.

Wichtige Architekturänderung: Das Skript dev_session.py startet die Gemini CLI nicht mehr direkt. Stattdessen durchläuft der Entwickler einen interaktiven Setup-Prozess, an dessen Ende ein Kontext für die Gemini CLI generiert wird. Das übergeordnete start-gemini.sh-Skript fängt diesen Kontext auf und startet die Gemini CLI in einer sauberen, isolierten Docker-Sitzung. Dieser zweistufige Prozess gewährleistet eine stabile und kontextbezogene Entwicklungsumgebung.

Funktionen

• Interaktive Projekt- und Task-Auswahl: Wähle Projekte und Tasks direkt aus deinen Notion-Datenbanken.
• Automatischer Start-Status: Setzt den Status des ausgewählten Tasks beim Start der Sitzung automatisch auf 'Doing'.
• Task-Erstellung: Erstelle neue Tasks direkt über das CLI im Kontext des ausgewählten Projekts.
• Agent-gesteuerte Statusberichte: Ermöglicht dem Gemini-Agenten, nach Abschluss eines Arbeitspakets einen detaillierten Statusbericht an Notion zu senden, Code zu committen und zu pushen.
• Automatisches Commit-Feedback: Ein post-commit Git-Hook sendet jede Commit-Nachricht als kurzen Kommentar an den Notion-Task.
• Kontext-Generierung für Gemini CLI: Erzeugt einen strukturierten Start-Prompt mit allen relevanten Informationen (Projekt, Task, Beschreibung, Git-Branch).
• Vorgeschlagene Git Branch-Benennung: Erstellt einen konsistenten Git-Branch-Namen basierend auf der Task-ID und dem Titel.

Voraussetzungen

• Docker: Das gesamte Setup ist containerisiert.
• Notion Integration Token: Ein Notion API-Token mit Zugriff auf Ihre "Projects"- und "Tasks"-Datenbanken.

Installation und Einrichtung

1. Notion API Key:

   • Stellen Sie sicher, dass Sie einen Notion Integration Token haben.
   • Das Skript fragt beim ersten Start interaktiv nach dem Token. Alternativ kann er als Umgebungsvariable NOTION_API_KEY in einer .env-Datei im Hauptverzeichnis gespeichert werden.
   • Gewähren Sie Ihrer Notion-Integration Zugriff auf die relevanten Datenbanken.

2. Abhängigkeiten: Alle Abhängigkeiten sind im gemini.Dockerfile definiert und werden automatisch im Container installiert.

Der Entwicklungs-Workflow

Der Workflow ist in drei Hauptphasen unterteilt: Sitzung starten, in der Sitzung arbeiten und Ergebnisse zurückmelden.

1. Sitzung starten

Der gesamte Startvorgang wird über das start-gemini.sh-Skript orchestriert.

./start-gemini.sh

Was im Hintergrund passiert:

1. Das Skript führt dev_session.py in einem temporären Docker-Container aus.
2. Sie durchlaufen den interaktiven Auswahlprozess für Ihr Projekt und Ihren Task in Notion.
3. Nach der Auswahl generiert dev_session.py den Kontext, speichert die Session-Informationen (z.B. Task-ID) in .dev_session/SESSION_INFO, installiert die Git-Hooks und gibt den Kontext an die Standardausgabe aus.
4. start-gemini.sh fängt diese Ausgabe ab, extrahiert den Kontext und startet einen neuen, sauberen Docker-Container (gemini-session) mit der Gemini CLI, wobei der Kontext als Start-Prompt übergeben wird.

Dieser Prozess stellt sicher, dass Ihre interaktive Gemini-Sitzung von der Notion-Logik entkoppelt ist und mit allen relevanten Informationen beginnt.

2. Arbeiten in der Gemini CLI

Nach dem Start befinden Sie sich in der Gemini CLI. Hier findet die eigentliche Entwicklungsarbeit statt.

• Commits: Wenn Sie oder der Agent git commit ausführen, greift der post-commit-Hook. Er liest die Task-ID aus der Session-Datei und sendet die Commit-Nachricht automatisch als kurzen Kommentar an den verknüpften Notion-Task. Dies sorgt für eine granulare Nachverfolgung des Fortschritts.

3. Fortschritt melden und Änderungen pushen (Agent-gesteuerter Workflow)

Dies ist der primäre Weg, um ein logisches Arbeitspaket abzuschließen und den Fortschritt zu dokumentieren. Anstatt Git-Befehle und Notion-Updates manuell zu koordinieren, geben Sie dem Agenten eine übergeordnete Anweisung.

Beispiel-Anweisung an den Gemini-Agenten:

"Okay, die Implementierung ist abgeschlossen. Fasse die Arbeit zusammen, erstelle einen Statusbericht für Notion, committe alle Änderungen und pushe sie."

Was der Agent im Hintergrund tut:

1. Informationen sammeln: Der Agent führt einen kurzen Dialog mit Ihnen, um den neuen Status (Bereit für Review, Blockiert etc.) und eventuelle offene To-Dos zu erfragen.
2. Git-Änderungen analysieren: Der Agent generiert eine Zusammenfassung der geänderten Dateien und der neuen Commit-Nachrichten.
3. Notion-Update (nicht-interaktiv): Der Agent ruft dev_session.py mit den gesammelten Informationen als Parameter auf.

   python3 dev_session.py --report-status \
     --status "Ready for Review" \
     --todos "- Finale Doku prüfen" \
     --git-changes "..." \
     --commit-messages "..."
   

4. Bericht erstellen: Das Skript formatiert diese Informationen zu einem sauberen Status-Update, postet es als Kommentar an den Notion-Task und aktualisiert gleichzeitig dessen Status-Feld.
5. Git-Operationen: Nachdem Notion aktualisiert wurde, führt der Agent die git add, git commit und git push Befehle aus.

Dieser Prozess stellt sicher, dass der Code-Stand im Repository immer synchron mit dem dokumentierten Fortschritt in Notion ist, ohne dass Sie die Gemini CLI verlassen müssen.

4. Sitzung abschließen

Wenn der gesamte Task abgeschlossen ist, können Sie die Sitzung über den folgenden Befehl vom Host-Terminal aus beenden.

docker exec -it gemini-session python3 dev_session.py --done

Dieser Befehl:

• Setzt den Status des Notion-Tasks auf "Done".
• Löscht die lokale Session-Datei (.dev_session/SESSION_INFO).
• Deinstalliert den post-commit Git-Hook.

Git Branch Benennungs-Konvention

Das Skript schlägt automatisch einen Git-Branch-Namen vor, der dem Muster feature/task-{kurze_task_id}-{task_titel_slug} folgt, um eine direkte Verbindung zwischen Code und Task herzustellen.

Beispiel: feature/task-2f388f42-update-readme-for-reporting

Entwicklung & Troubleshooting des Start-Skripts

Das start-gemini.sh-Skript wurde entwickelt, um mehrere Herausforderungen zu lösen:

• Problem: Fehlende Interaktivität: Frühe Versionen leiteten die Ausgabe von dev_session.py direkt in eine Variable um, was die interaktiven input()-Aufforderungen blockierte.

  • Lösung: Einsatz des tee-Befehls, der die Ausgabe gleichzeitig auf dem Bildschirm anzeigt und in eine temporäre Datei schreibt, aus der der Kontext später gelesen wird.

• Problem: Fehlerhafter Start-Parameter: Die Gemini CLI erwartet den initialen Prompt über --prompt-interactive.

  • Lösung: Korrektur des Arguments im docker run-Befehl.

• Problem: Konflikt durch nicht aufgeräumte Container: Vorzeitig beendete Skripte hinterließen Container, die den nächsten Start blockierten.

  • Lösung: Explizite docker rm -f-Befehle am Anfang des Skripts, um alte Container zu bereinigen.