tooling: make .junie/.gemini docs-first (remove legacy guidelines)
This commit is contained in:
@@ -0,0 +1,19 @@
|
||||
# Playbook: Documentation & Knowledge Curator
|
||||
|
||||
## Zweck
|
||||
Der Curator sorgt dafür, dass Wissen **auffindbar, konsistent und versioniert** bleibt. Er ist die „letzte Rolle“ jeder Session.
|
||||
|
||||
## Kernregeln
|
||||
* `docs/` ist die **Wahrheit**.
|
||||
* Jede Session endet mit **genau einem** Artefakt (ADR/Reference/How-to/Journal).
|
||||
* Links/Verweise setzen (auf relevante Code-Stellen, Dateien, ADRs).
|
||||
|
||||
## Ablauf (leichtgewichtig)
|
||||
1. Thema der Session in 1 Satz festhalten.
|
||||
2. Ergebnis-Typ wählen (welches Artefakt passt?).
|
||||
3. Artefakt erstellen/aktualisieren.
|
||||
4. Offene Fragen in den passenden „Parking Lot“ übernehmen.
|
||||
5. Optional: kurzes Journal-Update, wenn das Artefakt nicht selbsterklärend ist.
|
||||
|
||||
## Parking Lots
|
||||
* Technisch/Architektur: `docs/01_Architecture/questions.md` (falls benötigt)
|
||||
@@ -0,0 +1,21 @@
|
||||
# Playbook: Gemini (parallel/extern)
|
||||
|
||||
## Zweck
|
||||
Gemini wird genutzt für **Konzeptarbeit**: Varianten vergleichen, Argumente/Trade-offs schärfen, Formulierungen für ADRs/Doku liefern, Review von Entwürfen.
|
||||
|
||||
## Startpunkt
|
||||
1. `docs/README.md`
|
||||
2. `docs/03_Agents/README.md` (Artefakt-Vertrag)
|
||||
3. Je nach Thema: Architektur (`docs/01_Architecture/`), Backend (`docs/04_Backend/`), Frontend (`docs/05_Frontend/`), Infrastruktur (`docs/06_Infrastructure/`)
|
||||
|
||||
## Do
|
||||
* Immer 2–4 Optionen mit Vor-/Nachteilen liefern.
|
||||
* Offene Fragen explizit als Liste zurückgeben.
|
||||
* Formuliere Outputs so, dass sie **direkt** in ein `docs/*` Artefakt übernommen werden können.
|
||||
|
||||
## Don’t
|
||||
* Keine Annahmen als Fakten verkaufen.
|
||||
* Keine Repo-spezifischen Behauptungen ohne Quelle (Dateipfad/Link).
|
||||
|
||||
## Abschluss (Pflicht)
|
||||
Der Output wird durch den `Curator` als genau **ein** Artefakt in `docs/` verankert (ADR/Reference/How-to/Journal).
|
||||
@@ -0,0 +1,21 @@
|
||||
# Playbook: Junie (IDE)
|
||||
|
||||
## Zweck
|
||||
Junie wird genutzt für **Repo-nahe Arbeit**: Code lesen, reale Pfade/Module finden, konkrete Änderungen vorschlagen und umsetzen.
|
||||
|
||||
## Startpunkt
|
||||
1. `docs/README.md`
|
||||
2. Relevanter Bereich (z.B. `docs/01_Architecture/`, `docs/04_Backend/`, `docs/05_Frontend/`)
|
||||
3. Bei Rollen/Prozessfragen: `docs/03_Agents/README.md`
|
||||
|
||||
## Do
|
||||
* Immer mit **konkreten Dateipfaden** arbeiten.
|
||||
* Bei Unklarheit: gezielte Rückfragen stellen und Annahmen explizit machen.
|
||||
* Änderungen so klein wie möglich halten und den passenden Doku-Output erzeugen.
|
||||
|
||||
## Don’t
|
||||
* Keine „zweite Wahrheit“ in `.junie/guidelines/*` etablieren.
|
||||
* Keine Entscheidungen „im Chat verlieren“ – am Ende muss ein Artefakt in `docs/` stehen.
|
||||
|
||||
## Abschluss (Pflicht)
|
||||
Am Ende der Session genau **ein** Artefakt gemäß `docs/03_Agents/README.md` erzeugen (oder aktualisieren).
|
||||
@@ -0,0 +1,34 @@
|
||||
# Agent Operating Model (AOM)
|
||||
|
||||
Dieses Verzeichnis definiert, **wie** KI-Unterstützung im Projekt eingesetzt wird:
|
||||
Rollen/Playbooks, Ablageorte und der minimale Prozess, damit Wissen nicht verloren geht.
|
||||
|
||||
## Governance (Konfliktregel)
|
||||
|
||||
* **Single Source of Truth:** `docs/`
|
||||
* **Tooling/Automatisierung:** `.junie/` (Scripts, Checks, optional Archiv – keine zweite „Wahrheit“)
|
||||
* **Personas-Übersicht:** `AGENTS.md` (Repo-Root)
|
||||
|
||||
Wenn Aussagen in `.junie/*` und `docs/*` widersprechen, gilt **`docs/*`**.
|
||||
|
||||
## Artefakt-Vertrag (Anti-Wissensverlust)
|
||||
|
||||
Jede KI-Session endet mit **genau einem** Artefakt in `docs/`:
|
||||
|
||||
1. **ADR** (`docs/01_Architecture/adr/`) – Entscheidung/Optionen/Trade-offs (Status `proposed` ist erlaubt)
|
||||
2. **Reference** (passender Bereich) – Fakten/Ist-Zustand/Inventar
|
||||
3. **How-to / Runbook** (passender Bereich) – konkrete Schritte (Setup/Betrieb/Recovery)
|
||||
4. **Journal Entry** (`docs/99_Journal/`) – Kurzprotokoll, wenn nichts „fertig“ wird
|
||||
|
||||
## Tool-Rollen (keine Doppelarbeit)
|
||||
|
||||
* **Junie (IDE-nah):** Code/Repo-Wahrheit (Dateien, konkrete Implementierung, Refactors)
|
||||
* **Gemini (parallel/extern):** Variantenraum (Optionen, Argumentation, Formulierungen, Gegenentwurf)
|
||||
|
||||
„Wahr“ wird es erst, wenn es im passenden `docs/*` Artefakt verankert ist.
|
||||
|
||||
## Playbooks
|
||||
|
||||
* `Playbooks/Junie.md`
|
||||
* `Playbooks/Gemini.md`
|
||||
* `Playbooks/Curator.md`
|
||||
@@ -0,0 +1,13 @@
|
||||
# Ping-Service
|
||||
|
||||
Diese Seite beschreibt den **aktuellen technischen Stand** des `Ping-Service`.
|
||||
Sie ist der **stabile Einstiegspunkt** ("technische Wahrheit") für diesen Service.
|
||||
|
||||
## Einstieg
|
||||
|
||||
* Implementierungs-Report (Historie/Detailanalyse): `docs/90_Reports/Ping-Service_Impl_01-2026.md`
|
||||
|
||||
## Ablage-Regel (pro System)
|
||||
|
||||
* Pro Service gibt es eine stabile Datei unter `docs/04_Backend/Services/`.
|
||||
* Zeitlich datierte Analysen/Status-Reports liegen unter `docs/90_Reports/`.
|
||||
@@ -0,0 +1,10 @@
|
||||
# Journal 2026-01
|
||||
|
||||
## Vorlage
|
||||
|
||||
### YYYY-MM-DD – Thema
|
||||
* **Kontext:** …
|
||||
* **Rollen genutzt:** …
|
||||
* **Ergebnis:** … (Link auf ADR/Note/How-to/Reference)
|
||||
* **Offen:** … (Link auf `docs/00_Domain/questions.md` oder andere Parking Lots)
|
||||
* **Next:** …
|
||||
@@ -0,0 +1,13 @@
|
||||
# Journal
|
||||
|
||||
Kurze Session-Protokolle, damit Entscheidungen/Erkenntnisse nicht „im Chat“ verloren gehen.
|
||||
|
||||
## Regeln
|
||||
|
||||
* Pro Session 5–15 Zeilen.
|
||||
* Linke auf relevante Artefakte (ADR/Domain Note/How-to/Reference) und – wenn sinnvoll – auf Code-Pfade.
|
||||
* Wenn eine Session keine klare Entscheidung erzeugt: trotzdem ein Journal-Eintrag.
|
||||
|
||||
## Dateien
|
||||
|
||||
* `2026-01.md` (Monatsjournal)
|
||||
+17
-8
@@ -6,14 +6,14 @@ Die Dokumentation wird nach dem **"Docs-as-Code"**-Prinzip gepflegt: Sie liegt n
|
||||
|
||||
## Struktur der Dokumentation
|
||||
|
||||
* **/01_Architecture**: Enthält **Architecture Decision Records (ADRs)**. Jede wichtige Architekturentscheidung (z.B. "Warum nutzen wir ein API-Gateway?") wird hier in einer eigenen Datei festgehalten.
|
||||
* **/02_Onboarding**: Anleitungen für den schnellen Einstieg in das Projekt. Enthält `Getting_Started.md` für das lokale Setup.
|
||||
* **/03_Agents**: Definitionen und spezifische Anleitungen für die im Projekt eingesetzten KI-Agenten.
|
||||
* `AGENTS.md`: Definiert die Rollen, Verantwortlichkeiten und Regeln für jeden Agenten.
|
||||
* `Gemini/`, `Junie/`: Ablageorte für finalisierte Berichte und Analysen der jeweiligen KI-Assistenten.
|
||||
* **/04_Backend**: Dokumentation, die sich speziell auf die Backend-Services bezieht.
|
||||
* **/05_Frontend**: Dokumentation für das KMP-Frontend ("Meldestelle Portal").
|
||||
* **/06_Infrastructure**: Anleitungen und Konfigurationsdetails zur Infrastruktur (Docker, Keycloak, Consul, etc.).
|
||||
* **/01_Architecture**: Architektur (ADRs, C4/Diagramme, Architektur-Referenzen).
|
||||
* **/02_Onboarding**: Einstieg & Entwickler-Workflow (lokales Setup, PR-Workflow, Style-Guides).
|
||||
* **/03_Agents**: Agent Operating Model (AOM) + Playbooks für Junie/Gemini und weitere KI-Unterstützungen.
|
||||
* **/04_Backend**: Backend-spezifische Dokumentation (Services, Datenmodelle, Integrationen).
|
||||
* **/05_Frontend**: Frontend-spezifische Dokumentation (KMP/Compose, Offline/Synchronisierung).
|
||||
* **/06_Infrastructure**: Betrieb & Infrastruktur (Docker, Keycloak, Observability, Ports/URLs, Runbooks).
|
||||
* **/90_Reports**: Berichte/Analysen/Status-Reports (zeitlich geordnet, nicht zwingend „verbindliche Regeln“).
|
||||
* **/99_Journal**: Kurzprotokolle pro Session (Anti-Wissensverlust, Nachvollziehbarkeit).
|
||||
|
||||
## Wie man diese Dokumentation pflegt
|
||||
|
||||
@@ -24,3 +24,12 @@ Jeder Entwickler und jeder KI-Agent ist dafür verantwortlich, die Dokumentation
|
||||
* **Bei Änderungen am Setup:** Passe die Anleitungen im `Onboarding`- oder `Infrastructure`-Verzeichnis an.
|
||||
|
||||
Änderungen an der Dokumentation sollten Teil derselben Pull Request/Commit sein wie die zugehörigen Code-Änderungen.
|
||||
|
||||
### Wichtigste Einstiege
|
||||
|
||||
* Agenten/Arbeitsmodus: `docs/03_Agents/`
|
||||
* Lokales Setup/Workflow: `docs/02_Onboarding/`
|
||||
* Architekturentscheidungen: `docs/01_Architecture/adr/`
|
||||
* Backend (pro Service): `docs/04_Backend/Services/`
|
||||
* Ping-Service (Startpunkt): `docs/04_Backend/Services/ping-service.md`
|
||||
* Ping-Service Implementierungs-Report (Historie): `docs/90_Reports/Ping-Service_Impl_01-2026.md`
|
||||
|
||||
Reference in New Issue
Block a user