From 0e82748223fd7ee36f121a5c32836755d41abe4b Mon Sep 17 00:00:00 2001 From: Dystroyer8 Date: Thu, 30 Jul 2026 16:18:27 +0200 Subject: [PATCH] docs: add tooling and handoff guidance --- AGENTS.md | 3 + CHANGELOG.md | 3 + docs/CHATGPT_HANDOFF.md | 106 ++++++++++++++++++++++ docs/DECISIONS.md | 1 + docs/NEXT_SESSION.md | 3 +- docs/PROJECT_STATUS.md | 5 +- docs/adr/0004-token-efficient-workflow.md | 9 ++ docs/adr/README.md | 1 + 8 files changed, 128 insertions(+), 3 deletions(-) create mode 100644 docs/adr/0004-token-efficient-workflow.md diff --git a/AGENTS.md b/AGENTS.md index 0f344ee..098a917 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -7,7 +7,10 @@ - Lösche oder verschiebe nichts außerhalb dieses Repositorys. - Kein Force-Push und kein Umschreiben bestehender Git-Historie. - Höchstens zwei Unteragenten gleichzeitig; nur ein Agent darf Produktionsdateien schreiben. +- Arbeite tokensparend: gezielte Dateiabschnitte statt wiederholter Vollscans, gebündelte unabhängige Prüfungen und kurze Ergebniszusammenfassungen statt Rohlogs. +- Nutze Unteragenten nur für wirklich trennbare, ausreichend große Aufgaben. Qualitäts-, Sicherheits- und Verifikationsbedarf haben Vorrang vor Tokenersparnis. - Bestehende Obsidian-Notizen nur nach ausdrücklicher Anweisung ändern. `.obsidian` nie verändern. - Rootserver und Ubuntu-Laptop nur nach gesonderter Freigabe verändern. +- Aktualisiere `docs/CHATGPT_HANDOFF.md` nach jedem abgeschlossenen logischen Arbeitspaket mit Ergebnis, Änderungen, Tests, Git-Stand, offenen Punkten und nächstem Schritt. Einzelne Such- oder Prüfkommandos benötigen keinen eigenen Zwischenstand. - Aktualisiere nach wesentlichen Sitzungen `docs/PROJECT_STATUS.md`, `docs/DECISIONS.md`, `docs/NEXT_SESSION.md`, `docs/CHATGPT_HANDOFF.md` und `CHANGELOG.md`. - Behaupte keine fertige Funktion und keinen erfolgreichen Test ohne Nachweis. diff --git a/CHANGELOG.md b/CHANGELOG.md index 169eb1a..a0ff40a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,10 +11,13 @@ Alle wesentlichen Projektänderungen werden hier in verständlicher Form dokumen - Inaktiver Living-Mind-Bereich ohne Demo- oder Fantasiedaten. - Eng begrenzte projektinterne Codex-Agentenrollen. - Abhängigkeitsfreier Strukturprüfer. +- Phasenbezogene Empfehlung für Entwicklungswerkzeuge, VS-Code-Erweiterungen, Obsidian und lokale Modelllaufzeiten. ### Changed - Der historische Verbindungstest aus `READ.ME` wurde in `README.md` übernommen. +- Tokenbewusste Arbeitsweise als dauerhafte Regel ergänzt; Qualität und Sicherheit bleiben vorrangig. +- Laufende Handoff-Aktualisierung nach jedem abgeschlossenen logischen Arbeitspaket festgelegt. ### Security diff --git a/docs/CHATGPT_HANDOFF.md b/docs/CHATGPT_HANDOFF.md index ae6abbd..0dc5f03 100644 --- a/docs/CHATGPT_HANDOFF.md +++ b/docs/CHATGPT_HANDOFF.md @@ -1117,3 +1117,109 @@ Weiterhin nicht implementiert: - kein Living-Mind-Frontend Nach Pascals Abnahme ist `feat/core-chat` der empfohlene nächste Branch. Vor jeder Installation einer Python-Toolchain oder Modelllaufzeit ist weiterhin seine Freigabe erforderlich. + +## 38. Tokenbewusste Arbeitsweise und empfohlene Werkzeuge + +Pascal wünscht ausdrücklich einen möglichst sparsamen Tokenverbrauch, ohne Qualitätsverlust. Für ChatGPT und Codex gelten deshalb: + +- zu Beginn einer neuen großen Projektphase den vollständigen Handoff wie im Masterauftrag gefordert lesen; innerhalb derselben laufenden Phase anschließend mit `docs/PROJECT_STATUS.md`, `docs/NEXT_SESSION.md`, `docs/DECISIONS.md`, Git-Status und gezielten Abschnitten weiterarbeiten, statt den Handoff unnötig erneut vollständig einzulesen +- gezielte Suchen und relevante Dateiausschnitte statt wiederholter Vollscans +- unabhängige lesende Prüfungen sinnvoll bündeln +- Rohlogs begrenzen und Ergebnisse knapp mit konkreten Dateiverweisen zusammenfassen +- vorhandene Prüfergebnisse innerhalb einer Sitzung wiederverwenden +- kleine Aufgaben durch den Hauptagenten erledigen; Unteragenten nur bei klar trennbaren größeren Arbeiten +- maximal zwei Unteragenten gleichzeitig; keine parallelen Schreiber +- keine Dokumentation allein zur Textmenge erzeugen und keine unnötigen Alternativen ausarbeiten +- notwendige Sicherheitsprüfung, Tests, Quellenprüfung und verständliche Erklärung niemals aus Tokenersparnis weglassen +- nach jedem abgeschlossenen logischen Arbeitspaket diesen Handoff aktualisieren: Auftrag, Ergebnis, geänderte Dateien, Tests, Git-Stand, offene Punkte und nächster Schritt +- einzelne Such-, Lese- oder Prüfkommandos nicht als eigene Handoff-Version behandeln; sie werden im Ergebnis des zugehörigen Arbeitspakets zusammengefasst + +### Empfohlene minimale Werkzeuge für Phase 1 + +Noch nichts davon ist installiert oder freigegeben. Vor jeder Installation muss Pascal zustimmen. + +1. **Python-/Projektverwaltung: `uv` von Astral bevorzugt prüfen.** Es ist plattformübergreifend, verwaltet virtuelle Umgebungen und erzeugt einen reproduzierbaren Lockfile. Das passt zum späteren Wechsel zwischen Windows und Ubuntu. Offizielle Dokumentation: `https://docs.astral.sh/uv/` +2. **VS Code: Microsoft Python-Erweiterung mit Pylance und Python Environments.** Das genügt zunächst für Interpreterwahl, IntelliSense, Debugging und Tests. Keine große Python-Erweiterungssammlung installieren. Offizielle Dokumentation: `https://code.visualstudio.com/docs/languages/python` +3. **Ruff.** Als schneller gemeinsamer Linter und Formatter reduziert Ruff mehrere Einzelwerkzeuge. Installation und Konfiguration erst zusammen mit der Python-Toolchain. Offizielle Dokumentation: `https://docs.astral.sh/ruff/` +4. **Tests.** Zunächst das eingebaute `unittest` weiterverwenden. `pytest` erst ergänzen, wenn Fixtures, Parametrisierung oder Plugins einen echten Vorteil bringen. + +### Später und nur bei tatsächlichem Bedarf + +- **VS Code Remote – SSH:** erst beim Aufbau des eingeschränkten Zugangs zum ASUS-Ubuntu-Laptop. Kein Rootzugang und eigener Javis-Schlüssel. Offizielle Dokumentation: `https://code.visualstudio.com/docs/remote/ssh` +- **Lokale Modelllaufzeit:** auf dem Gaming-PC und ASUS-Laptop zunächst `Ollama` und `llama.cpp` gegeneinander benchmarken. Ollama ist einfacher zu bedienen; llama.cpp bietet feiner kontrollierbare GGUF-, Quantisierungs- und CPU/GPU-Offload-Optionen. Keine Vorentscheidung ohne Messwerte. Offizielle Quellen: `https://docs.ollama.com/` und `https://github.com/ggml-org/llama.cpp` +- **Secret-Scan:** vor der ersten echten Provider- oder Serveranbindung ein schlankes Secret-Scanning im Commit-Workflow bewerten. `.gitignore` und Modellisolierung bleiben unabhängig davon Pflicht. +- **Container:** Docker erst für einen konkreten späteren Deploymentbedarf auf dem Ubuntu-Host einführen, nicht für den ersten lokalen Textkern. + +### Obsidian + +- Self-hosted LiveSync bleibt die einzige derzeit notwendige Community-Erweiterung. +- Für die gewünschte Gehirnoptik zunächst Obsidian-Core-Funktionen wie Graph View, Local Graph, Backlinks, Tags und Gruppen verwenden. +- Keine Graph-, Dataview- oder Automations-Erweiterung nur für die Optik installieren. +- Dataview oder ein anderes Plugin erst prüfen, wenn eine konkrete Abfrage nicht sinnvoll mit Markdown, Metadaten und dem Javis-Index lösbar ist. +- Interne Links bleiben fachlich begründet. Obsidian bildet über diese Links bereits ein Wissensnetz; zusätzliche künstliche Kanten sind nicht nötig. Offizielle Dokumentation: `https://obsidian.md/help/plugins/graph` und `https://obsidian.md/help/links` + +### Codex-Skills, Plugins und Connectoren + +- Die vorhandenen projektbezogenen Rollen Scout, Architect, Builder, Verifier und Security Reviewer reichen vorerst aus. +- `openai-docs` nur für aktuelle OpenAI-/Codex-Fragen einsetzen. +- Browser-Steuerung erst bei einer realen lokalen Weboberfläche für Tests verwenden. +- Dokument-, PDF-, Tabellen-, Präsentations- und Bildfunktionen nur bei einer passenden konkreten Aufgabe aktiv nutzen. +- Keinen GitHub-Connector installieren, solange Gitea die Quellcodeverwaltung ist. +- Notion-, Google-Drive-, Slack-, Teams-, Mail- und Kalender-Connectoren zunächst nicht verbinden. Sie erhöhen Berechtigungsfläche und Kontextverbrauch, ohne für Phase 1 benötigt zu werden. +- Keine große Plugin-, Skill- oder Agentensammlung vorsorglich installieren. + +Empfohlener Minimalstand für die nächste Phase: `uv` plus verwaltetes Python, Microsoft Python/Pylance/Python Environments und Ruff. Alles Weitere bleibt bedarfsabhängig. + +### Verbindlicher Kommunikationsrhythmus + +`docs/CHATGPT_HANDOFF.md` ist die gemeinsame Übergabeschnittstelle zwischen Codex und GPT. Codex hält sie nach jedem abgeschlossenen logischen Arbeitspaket aktuell. Ein Arbeitspaket ist beispielsweise eine Dokumentationsänderung, eine implementierte und getestete Funktion, eine abgeschlossene Diagnose oder eine freigegebene Infrastrukturmaßnahme. Der Eintrag nennt knapp: + +1. Auftrag und Ergebnis, +2. tatsächlich geänderte Dateien oder Systeme, +3. ausgeführte Tests und deren Ergebnis, +4. Branch, Commit und Push-Status, +5. offene Entscheidungen oder Fehler, +6. den sicheren nächsten Schritt. + +Damit die Datei nutzbar bleibt, werden keine vollständigen Chats, Rohlogs oder redundanten Wiederholungen angehängt. + +## 39. Arbeitspaket: Werkzeugempfehlungen und Handoff-Rhythmus + +Auftrag und Ergebnis: + +- Pascal bat um sinnvolle Add-on-, Plugin- und Werkzeugempfehlungen sowie möglichst tokensparende Arbeit ohne Qualitätsverlust. +- Die Empfehlungen wurden anhand aktueller offizieller Dokumentation auf einen phasenbezogenen Minimalumfang begrenzt. +- Zusätzlich wurde festgelegt, dass dieser Handoff nach jedem abgeschlossenen logischen Arbeitspaket aktualisiert wird. + +Geänderte Projektdateien: + +- `AGENTS.md` +- `CHANGELOG.md` +- `docs/CHATGPT_HANDOFF.md` +- `docs/DECISIONS.md` +- `docs/NEXT_SESSION.md` +- `docs/PROJECT_STATUS.md` +- `docs/adr/README.md` +- `docs/adr/0004-token-efficient-workflow.md` + +Prüfungen: + +- Repository war vor der Änderung sauber auf `main` bei Grundgerüstcommit `6d04171`. +- UTF-8, Handoff-Struktur und Secret-Muster wurden geprüft. +- Es wurden keine Plugins, Programme, Python-Versionen oder Modelllaufzeiten installiert. +- Obsidian, Rootserver und Ubuntu-Laptop wurden nicht verändert. + +Git-Stand: + +- Branch: `main` +- Basis dieses Arbeitspakets: `6d04171` +- Der Commit, der Abschnitt 39 enthält, ist mit `git log -1 --oneline` zu bestimmen. + +Offen: + +- Pascal muss vor Phase 1 der konkreten Python-/`uv`-Installation zustimmen. +- Modelllaufzeit, Obsidian-Zusatzplugins und Remote-SSH bleiben bis zu ihrem tatsächlichen Bedarf zurückgestellt. + +Nächster sicherer Schritt: + +- diesen aktualisierten Handoff an GPT übergeben oder nach Pascals Freigabe Phase 1 auf `feat/core-chat` beginnen. diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md index 59a9d92..576611b 100644 --- a/docs/DECISIONS.md +++ b/docs/DECISIONS.md @@ -5,6 +5,7 @@ | ADR-0001 | Modularer Monolith statt früher Microservices | angenommen | | ADR-0002 | Secrets bleiben außerhalb von Modellkontext und Git | angenommen | | ADR-0003 | Obsidian-Links benötigen echte inhaltliche Beziehungen | angenommen | +| ADR-0004 | Tokenbewusst arbeiten, ohne Qualität oder Sicherheit zu senken | angenommen | Offen bleiben insbesondere die konkrete lokale Modelllaufzeit, das endgültige Runtime-Secret-System, der genaue Obsidian-Schreibbereich und der Produktname. diff --git a/docs/NEXT_SESSION.md b/docs/NEXT_SESSION.md index 40c5add..84f1566 100644 --- a/docs/NEXT_SESSION.md +++ b/docs/NEXT_SESSION.md @@ -13,8 +13,9 @@ Pascal prüft zuerst das Grundgerüst. Danach kann Phase 1 auf `feat/core-chat` ## Vorgeschlagener Umfang -- zwei bis drei geeignete lokale Python-Installationswege vergleichen +- bevorzugt `uv` und höchstens eine sinnvolle Alternative für Python- und Umgebungsverwaltung vergleichen - Installation nur nach Pascals Freigabe +- Microsoft Python/Pylance/Python Environments sowie Ruff als minimale Entwicklungswerkzeuge prüfen - echte Konfigurationsladefunktion mit Tests - Provider-Protokoll ohne Cloudaufruf - minimale CLI-Struktur ohne fest programmierte KI-Antworten diff --git a/docs/PROJECT_STATUS.md b/docs/PROJECT_STATUS.md index af447cc..35097dd 100644 --- a/docs/PROJECT_STATUS.md +++ b/docs/PROJECT_STATUS.md @@ -10,6 +10,7 @@ Stand: Grundgerüstphase am 30.07.2026. - Obsidian-Linkregel als verbindliche Entscheidung dokumentiert - Living-Mind-Bereich als inaktiver Vertrag vorbereitet - projektinterne Codex-Agentensyntax anhand der aktuellen offiziellen Codex-Dokumentation geprüft +- phasenbezogene Werkzeug- und Plugin-Empfehlungen sowie tokenbewusste Arbeitsregeln dokumentiert ## Nicht implementiert @@ -18,8 +19,8 @@ KI, Chat, Provider, Gedächtnis, Obsidian-Adapter, Tools, Serverzugriff, Sprache ## Git - Branch: `main` -- Ausgangscommit: `49a1dd3` -- Der Commit, der dieses Dokument enthält, ist der Grundgerüstcommit; die konkrete ID ist mit `git log -1` zu ermitteln. +- Grundgerüstcommit: `6d04171` +- Der aktuelle Dokumentationscommit ist mit `git log -1` zu ermitteln. ## Bekannte Einschränkung diff --git a/docs/adr/0004-token-efficient-workflow.md b/docs/adr/0004-token-efficient-workflow.md new file mode 100644 index 0000000..f2b8554 --- /dev/null +++ b/docs/adr/0004-token-efficient-workflow.md @@ -0,0 +1,9 @@ +# ADR-0004: Tokenbewusster Arbeitsablauf + +Status: angenommen. + +Codex soll Kontext und Toolaufrufe sparsam einsetzen: zuerst Status- und Übergabedokumente lesen, anschließend nur relevante Dateiabschnitte öffnen, unabhängige Prüfungen bündeln, Rohlogs begrenzen und Unteragenten nur für klar trennbare größere Aufgaben nutzen. + +Tokenersparnis darf niemals dazu führen, notwendige Prüfungen, Sicherheitsanalyse, Tests oder verständliche Erklärungen wegzulassen. Qualität und Sicherheit haben Vorrang. + +Nach jedem abgeschlossenen logischen Arbeitspaket wird der Handoff als kompakter Delta-Stand aktualisiert. Einzelne Such-, Lese- oder Prüfkommandos erzeugen keinen eigenen Handoff-Eintrag; dadurch bleiben GPT und Codex synchron, ohne unnötige Wiederholungen. diff --git a/docs/adr/README.md b/docs/adr/README.md index b80cc88..2ff0a86 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -3,3 +3,4 @@ - [ADR-0001: Modularer Monolith](0001-modular-monolith.md) - [ADR-0002: Secret-Isolation](0002-secret-isolation.md) - [ADR-0003: Sinnvolle Obsidian-Verknüpfungen](0003-meaningful-obsidian-links.md) +- [ADR-0004: Tokenbewusster Arbeitsablauf](0004-token-efficient-workflow.md)