Fähigkeit zur Sitzungsübergabe
Zweck
Große Kontextfenster verschlechtern die Anweisungsbefolgung, Argumentationsgenauigkeit und Werkzeugtreue, wenn die Token-Anzahl zunimmt. Lange Sitzungen füllen sich mit überholten Plänen, abgebrochenen Notizblöcken und sich wiederholenden Fehlerverfolgungen. Ein Zurücksetzen auf eine frische Sitzung stellt die Leistung wieder her, aber blindes Verwerfen von Kontext führt zu Zustandsverlust, halluziniertem Fortschritt und wiederholten Fehlern.
Die Fähigkeit session-handoff standardisiert, wie ein Agent den aktiven Zustand erfasst. Sie übersetzt flüchtiges Arbeitsgedächtnis in ein umsetzbares, überprüfbares Brückendokument für die nächste Sitzung.
Arbeitsablauf: Beenden einer Sitzung (6 Schritte)
Führen Sie diese Sequenz aus, wenn eine Agentensitzung die Betriebsgrenzen erreicht oder die Arbeit eingestellt wird:
-
Prüfen von Git und Arbeitsbereichszustand Führen Sie
git status -sundgit diff --stataus, um eine geerdete Realität zu etablieren. Verlassen Sie sich niemals auf das Chat-Gedächtnis, um festzustellen, was geändert wurde. Identifizieren Sie geänderte, nicht verfolgte und bereitgestellte Dateien. -
Erfassen von Zielzustand vs. implementierter Realität Definieren Sie das ursprüngliche Ziel in einem Satz. Dokumentieren Sie genau, was als funktionierend verifiziert wurde (mit erfolgreichen Testbefehlen oder Laufzeitprüfungen) im Vergleich zu dem, was noch teilweise oder unverifiziert ist.
-
Aufzeichnen getroffener Entscheidungen und verworfener Pfade Listen Sie architektonische und designbezogene Entscheidungen auf, die während der Sitzung getroffen wurden, zusammen mit der konkreten Begründung. Zeichnen Sie explizit negative Entscheidungen auf (Ansätze, die ausprobiert und verworfen wurden), um zu verhindern, dass der nächste Agent erneut fehlgeschlagene Lösungen versucht.
-
Katalogisieren von berührten Dateien und relevanten Symbolen Listen Sie wichtige Dateipfade, Funktionen, Klassen und Schemadefinitionen auf, die geändert oder referenziert wurden. Fügen Sie gegebenenfalls Zeilenverweise hinzu.
-
Isolieren offener Schleifen mit Besitzern und Überprüfungen Listen Sie alle nicht behandelten Grenzfälle, fehlschlagenden Tests, aufgeschobenen Aufgaben und Umgebungsbeschränkungen auf. Jede offene Schleife muss angeben, wer sie auflöst (Mensch oder Agent) und wie die Fertigstellung überprüft wird.
-
Festlegen der unmittelbaren nächsten Aktion Verfassen Sie eine einzelne, atomare, eindeutige Anweisung für den nächsten Agenten, die er im ersten Schritt ausführen soll. Geben Sie keine breite Liste an; geben Sie den genauen Befehl an, der ausgeführt werden soll, oder die Datei, die zuerst bearbeitet werden soll.
Betriebsregeln
- Fakten von Spekulationen trennen: Ein Test, der bestanden hat, ist eine Tatsache; anzunehmen, dass Code funktioniert, weil er kompiliert wurde, ist Spekulation. Kennzeichnen Sie nicht getestete Annahmen explizit als
[UNVERIFIED]. - Besitzer und Überprüfungen für offene Schleifen vorschreiben: Jede offene Schleife muss einen Besitzer (
HumanoderAgent) und ein deterministisches Überprüfungskriterium angeben (z. B.pytest tests/auth/test_token.py::test_refresh_rotation bestanden). - Vage Fortsetzungen verbieten: Schreiben Sie niemals "weiter an der Authentifizierung arbeiten" oder "Frontend-Komponenten fertigstellen". Geben Sie das genaue Symbol, die Datei und die Fehlerart an.
- Echte Arbeitsbereichsbezeichner referenzieren: Alle Verweise auf Code müssen genaue Dateipfade und Symbolnamen verwenden. Verwenden Sie keine verallgemeinerten Pseudocode-Beschreibungen.
Gearbeitetes Beispiel: Sitzungsübergabenotiz
# Sitzungsübergabe: JWT-Rotationsimplementierung
### Ziel & aktueller Stand
- **Zielsetzung**: Implementieren Sie Refresh-Token-Rotation und -Widerruf im FastAPI-Authentifizierungsdienst.
- **Aktueller Stand**: Datenbankmigration für Refresh-Tokens angewendet und Rotationsendpunkt erstellt. Tokenerzeugung und Datenbankpersistenz funktionieren. Der Widerruf-Blacklist-Cache ist noch nicht in den Abhängigkeitsvalidator eingebunden.
- **Verifizierung**: `pytest tests/test_auth_tokens.py` bestanden (4/4 Tests).
### Getroffene Entscheidungen (mit Gründen)
- **Redis für Token-Widerrufsliste verwendet**: Redis gegenüber Postgres-Abfragen für widerrufene JTI-Tokens gewählt, um die Latenz auf geschützten Routen unter 5 ms zu halten.
- **Zustandslose Refresh-Tokens abgelehnt**: Zunächst gleitendes Ablaufen in JWT-Ansprüchen ohne Persistenz evaluiert, aber verworfen, da kompromittierte Tokens vor natürlichem Ablauf nicht widerrufen werden konnten.
- **Token-Format**: UUIDv4 für den `jti`-Anspruch gewählt, um die Kompatibilität mit bestehenden Sitzungsspeicherschemata zu wahren.
### Geänderte Dateien
- `src/services/auth.py`: Funktion `rotate_refresh_token(old_token: str)` und Redis-Invalidierungsaufruf hinzugefügt.
- `src/models/tokens.py`: SQLModel-Tabelle `RefreshTokenRecord` zum Verfolgen von Token-Familien hinzugefügt.
- `alembic/versions/20261005_add_token_families.py`: Migration zur Erstellung der Tabelle `token_records`.
- `tests/test_auth_tokens.py`: Unit-Tests für Token-Familienerzeugung und -Rotation hinzugefügt.
### Offene Schleifen
- [Agent] Binden Sie `verify_token_not_revoked` in `src/api/deps.py` ein -> Überprüfen Sie, indem Sie prüfen, dass `tests/test_auth_deps.py` bei einem auf die Blacklist gesetzten Token fehlschlägt.
- [Agent] Behandeln Sie den Datenbank-Rollback, wenn Redis während der Rotation nicht erreichbar ist -> Überprüfen Sie, indem Sie den Redis-Verbindungsfehler in einem Unit-Test simulieren.
- [Human] Setzen Sie das Geheimnis `REDIS_AUTH_URL` in `.env.test` für die CI-Ausführung.
### Nächste Aktion
Öffnen Sie `src/api/deps.py` und importieren Sie `is_token_blacklisted` aus `src.services.auth`. Fügen Sie die Prüfung in `get_current_user` direkt nach der JWT-Decode-Verifizierung ein.
### Warnhinweise
- Ändern Sie nicht die vorhandene Ablaufzeit von `access_token` (derzeit 15 Minuten) in `src/core/config.py`.
- Die Alembic-Migration `20261005_add_token_families.py` muss vor dem Starten des API-Servers lokal ausgeführt werden (`alembic upgrade head`).
Antimuster
- Der Chat-Transkript-Dump: Einfügen roher Konversationsprotokolle in die Übergabenotiz. Das Kontextfenster der nächsten Sitzung wird sofort mit genau dem Konversationsrauschen verschmutzt, dem Sie entkommen wollten.
- Der Phantom-Pass: Markieren eines Moduls als "abgeschlossen", das nur geschrieben, aber nicht ausgeführt oder getestet wurde.
- Die ausgelassene Sackgasse: Weglassen von Lösungen, die fehlgeschlagen sind. Der nächste Agent liest die Codebasis, sieht denselben scheinbaren Pfad und implementiert den fehlgeschlagenen Ansatz erneut.
- Der abstrakte nächste Schritt: Beenden mit "Nächster: Restliche Tests implementieren." Der neue Agent verbringt 3-5 unnötige Runden damit, herauszufinden, was getestet werden muss.
Einschränkungen
- Diese Fähigkeit erzeugt nur eine schriftliche Übergabe; sie kann keinen Live-Zustand wie laufende Prozesse, nicht festgeschriebene Terminalausgaben oder In-Memory-Debugging-Kontext bewahren – zeichnen Sie alles, was wichtig ist, explizit in der Notiz auf.
- Die Qualität der Übergabe wird durch das begrenzt, was die ausgehende Sitzung aufzeichnet: Entscheidungen, Sackgassen oder Dateiänderungen, die nicht aufgeschrieben werden, können von der nächsten Sitzung nicht wiederhergestellt werden.
- Sie ersetzt keine Versionskontrolle oder Problemverfolgung; committen Sie zuerst die Arbeit und referenzieren Sie Commits oder Tickets in der Notiz anstatt sie zu duplizieren.