Dies ist die Wiki-Browser-Version. Die Originaldatei liegt im Projekt-Root unter CLAUDE.md und wird von KI-Agenten wie Claude direkt gelesen. Änderungen bitte in beide Versionen einpflegen.
CLAUDE.md — Schema des SAP-Joule-Wikis
Dies ist die Betriebsanleitung für KI-Agenten (Claude, Codex u.a.), die dieses Wiki pflegen. Sie beschreibt wie das Wiki strukturiert ist, welche Konventionen gelten und wie Ingest, Query und Lint ablaufen. Menschen lesen dieses Dokument ebenfalls, bevor sie mit einem KI-Agenten am Wiki arbeiten.
Diese Datei wird von Martin und dem Joule-Team bewusst co-evolviert — wer merkt, dass eine Konvention nicht trägt, ändert sie hier und passt die KI-Workflows entsprechend an.
1. Zweck
Das Wiki ist das zentrale, persistente Wissensartefakt des ADVIA/Aequitas-Joule-Teams zu SAP Joule. Es wird inkrementell aus Rohquellen (SAP-News, Produktdokumentation, Projektberichten, Kundengesprächen, Messenotizen) zu einem vernetzten Markdown-Repository verdichtet.
Menschen kuratieren Quellen, stellen Fragen und beurteilen Qualität.
KI-Agenten integrieren neue Quellen, schreiben Seiten, halten Cross-Links konsistent und markieren Widersprüche.
Kunden- und Projekterfahrungen — Use Cases, Lessons Learned, Anti-Patterns.
Weitere Bereiche (Vertrieb, Technik) können später ergänzt werden.
2. Grundprinzipien
Markdown ist die Wahrheit. Quartz, Obsidian oder andere Renderer sind nur Darstellung. Alles, was zählt, steht in .md-Dateien.
raw/ ist unveränderlich. Rohquellen werden nie editiert, nur gelesen und verlinkt.
Die KI schreibt das Wiki, der Mensch kuratiert. Neue Seiten, Updates und Cross-Links entstehen durch KI-Arbeit auf Basis von Ingest-Sessions. Manuelle Edits sind erlaubt, müssen aber im Log vermerkt werden.
Verweise sind Wikilinks ([[seite]]), nicht [Text](pfad.md) — damit Obsidian/Quartz alles automatisch auflösen.
Jede Änderung landet in content/log.md mit Datum und Typ (ingest, query, lint, edit).
Reife macht sichtbar, worauf Verlass ist. Jede Seite hat im Frontmatter ein Feld reife: stub | entwurf | reif | veraltet.
3. Verzeichnisstruktur
/
├── CLAUDE.md ← dieses Schema (gelesen vor jeder KI-Session)
├── README.md ← Einstieg für Menschen
├── content/ ← das eigentliche Wiki
│ ├── index.md ← Startseite mit Einladung zum Mitmachen
│ ├── navigation.md ← inhaltsorientierter Index (Karpathy: index.md)
│ ├── log.md ← chronologisches Protokoll
│ ├── meta/ ← Browser-Spiegel von CLAUDE.md, README.md, raw/README.md
│ ├── produkt/ ← SAP-Joule-Produktwissen
│ ├── projekte/ ← Aequitas-Projekterfahrungen
│ ├── entitaeten/ ← Personen, Kunden, Partner, SAP-Produkte
│ ├── konzepte/ ← Begriffe, Technologien, Patterns
│ └── quellen/ ← Seiten, die je eine Rohquelle zusammenfassen
├── raw/ ← Rohquellen (PDFs, Screenshots, Exporte)
│ ├── README.md
│ ├── .inbox/ ← noch nicht integrierte Dokumente
│ └── assets/ ← Bilder, Diagramme, die in Wiki-Seiten eingebettet werden
└── quartz/ ← Static-Site-Generator (Node-basiert, im Docker-Container)
4. Seitentypen
Jede Wiki-Seite hat YAML-Frontmatter mit mindestens typ, tags, aktualisiert, reife.
Typ
Beschreibung
Ordner
produktseite
Ein Feature, Modul oder Release von SAP Joule
produkt/
projekt
Ein konkretes Aequitas-Kundenprojekt
projekte/
entitaet
Person, Organisation, Produkt (SAP-intern oder extern)
entitaeten/
konzept
Begriff, Pattern, Methode, Technologie
konzepte/
quelle
Zusammenfassung + Metadaten einer Rohquelle
quellen/
index
Navigationsseite einer Kategorie
*/index.md
Frontmatter-Felder
---typ: produktseite # einer der Typen oben (deutsches Feld, für unsere Logik)title: "Joule Agent Builder" # Pflicht, wird von Quartz für den Seitentitel genutzttags: [joule, btp, agents]aktualisiert: 2026-04-17 # YYYY-MM-DD, letzte inhaltliche Änderungreife: entwurf # stub | entwurf | reif | veraltetstand: 2026-03-15 # optional: Datum, auf das sich der Inhalt beziehtquellen: # optional: Pfade zu quellen/*.md - "../quellen/sap-teched-2026-keynote.md"owner: martin.arnold@advia.de # optional---
Hinweis zu title: vs. titel:: Quartz erwartet das englische Feld title: — deshalb nutzen wir genau dieses. Alle anderen Felder sind deutsch (typ, aktualisiert, reife, stand, quellen, owner).
5. Workflows
5.1 Ingest (neue Rohquelle integrieren)
Auslöser: Ein Kollege legt ein Dokument in raw/.inbox/ ab, oder Martin bittet die KI explizit darum.
Rohquelle in raw/.inbox/ lesen. Bei PDFs/Screenshots Text extrahieren; bei Bildern separat betrachten.
Betroffene bestehende Seiten identifizieren. Pro betroffener Seite: inkrementell ergänzen, Widersprüche mit > [!warning]-Callout markieren.
Neue Seiten erstellen für Entitäten/Konzepte, die in der Quelle prominent vorkommen, aber noch keine eigene Seite haben.
Wikilinks in beide Richtungen sicherstellen (neue Seite → bestehende + umgekehrt).
navigation.md und ggf. produkt/index.md (o.ä.) mit Link zur neuen Seite ergänzen.
Eintrag in content/log.md.
Rohdatei von raw/.inbox/ in passenden Unterordner von raw/ verschieben (z.B. raw/presse/, raw/kundenprojekte/).
5.1.1 Kuratierung statt Voll-Ingest — wann eine Quelle keine eigene Quelle-Seite bekommt
Nicht jede Datei, die in raw/.inbox/ landet, rechtfertigt eine eigene content/quellen/*.md. Die KI prüft vor Schritt 2 des Ingest-Workflows:
Wiederkehrende Formate (Tages-/Wochen-Briefings, regelmäßige Newsletter, wiederkehrende Reportings): Nur die erste Ausgabe bekommt eine Quelle-Seite, die das Format dokumentiert. Folgeausgaben fließen als kuratierte Extrakte direkt in bestehende Wiki-Seiten (z.B. adoptionslage.md) und werden nur im log.md als Ingest-Eintrag vermerkt — ohne eigene Quelle-Seite.
Überwiegend Joule-fremde Inhalte: Wenn weniger als ~20 % der Quelle Joule-Bezug haben, wird nicht die ganze Quelle ins Wiki übernommen, sondern nur die Joule-relevanten Fakten in bestehende Seiten eingepflegt. In diesem Fall dokumentiert die Quelle-Seite explizit, was ausgelassen wurde und warum.
Vertrauliche Inhalte: Quelle-Seiten zu ADVIA-internen oder kundenspezifisch vertraulichen Dokumenten bekommen am Kopf einen > [!warning] Vertraulich-Callout.
Wenn unklar ist, ob eine neue Quelle ein eigenes Blatt verdient, fragt die KI Martin vor Schritt 2 nach — es ist besser, einmal zu viel zu fragen als 90 redundante Quelle-Seiten zu erzeugen.
5.2 Query (Frage beantworten)
Zuerst content/navigation.md konsultieren.
Relevante Seiten volltextlich lesen (Obsidian-Suche bzw. grep).
Antwort synthetisieren, dabei Wikilinks als Zitate nutzen: „Joule nutzt intern Grounding …“.
Wenn die Antwort substanziell ist (mehr als ein Satz): als neue Seite ablegen, Typ passend wählen (meist konzept oder projekt), und in log.md unter query protokollieren.
5.3 Lint (Gesundheitscheck)
Empfohlen monatlich oder auf Zuruf:
Widersprüche zwischen Seiten aufspüren und mit > [!warning] markieren.
Wann gilt §5.4? Wenn ein Ingest nicht in einer interaktiven Claude-Session läuft (mit menschlicher Aufsicht im Chat), sondern aus dem Wiki-Backend heraus (FastAPI + Claude Agent SDK), ausgelöst durch Upload oder URL-Einreichung. §5.4 ergänzt §5.1/§5.1.1, ersetzt sie aber nicht — die inhaltlichen Regeln bleiben gleich, es kommen Sicherheitsklammern hinzu, weil niemand mitliest.
5.4.1 Atomarität — ein Auto-Ingest = ein Commit
Jeder Auto-Ingest läuft in einem einzigen, atomaren Git-Commit. Wenn die Pipeline mittendrin abbricht: kein partieller Commit, kein dirtied Working Tree — entweder ganz oder gar nicht.
Commit-Prefix: ingest-auto: (statt ingest: für manuelle/interaktive Ingests). So sind Auto-Ingests in git log --oneline | grep ^…ingest-auto: sofort erkennbar — Voraussetzung für §5.4.5 (Undo).
Beispiel: ingest-auto: SAP Community - <Originaltitel> (<URL-Hash>).
5.4.2 Schreibrechte — Whitelist statt Blacklist
Ein Auto-Ingest darf nur in folgende Pfade schreiben:
content/quellen/*.md (neu oder Update)
content/konzepte/*.md, content/entitaeten/*.md, content/projekte/*.md (neu oder Update)
raw/ (das hochgeladene Original — kein Edit, nur Move aus .inbox/ heraus)
Alles andere ist tabu: insbesondere CLAUDE.md, content/meta/*, README.md, docker-compose.yml, der Quartz-Build, ingest-app/. Wenn die Pipeline glaubt, dort schreiben zu müssen, bricht sie ab und legt einen Eintrag in content/log.md als auto-ingest-blocked ab.
5.4.3 Reife-Deckel und Schreibschutz für reife: reif
Eine Auto-Ingest-Seite darf im Frontmatter maximal reife: entwurf tragen. reife: reif setzt nur ein Mensch.
Bestehende Seiten mit reife: reif werden nicht überschrieben. Auto-Ingest darf an solche Seiten höchstens anhängen — und zwar in einem deutlich gekennzeichneten Block:
> [!note] Auto-Ingest 2026-MM-DD> <Beobachtung aus der neuen Quelle, kurz, mit Wikilink auf die neue quellen/*.md>
Mehr nicht. Inhalt der reife: reif-Seite bleibt wortgleich.
Bestehende Seiten mit reife: entwurf darf der Auto-Ingest erweitern, aber nicht löschen — nur append-only auf Abschnittsebene.
5.4.4 Pflicht-Frontmatter und Pflicht-Log-Eintrag
Jede neue Seite, die ein Auto-Ingest erzeugt, hat im Frontmatter zusätzlich:
ingest: auto # Pflicht für Auto-Ingest-Erzeugnisseingest_run_id: 2026-04-30T14-23-05Z # ISO-Zeitstempel des Pipeline-Laufs
Damit ist jede Auto-Ingest-Seite eindeutig identifizierbar. Bei manueller Pflege später entfernt man ingest: auto (oder setzt auf ingest: manuell-überarbeitet); danach gilt §5.4.3 für diese Seite nicht mehr.
Pro Auto-Ingest-Lauf entsteht immer ein Eintrag in content/log.md mit Typ ingest-auto, der die ingest_run_id, die berührten Dateien und die Source-URL/-Datei nennt. Auch wenn der Lauf nichts geändert hat: dann steht da ingest-auto: skipped — <Grund>.
5.4.5 Undo des jüngsten Auto-Ingests
Es gibt einen Undo-Endpoint im Backend (POST /api/ingest-auto/undo), der den letzteningest-auto:-Commit zurücknimmt — technisch via git revert HEAD --no-edit && git push.
Der Endpoint funktioniert nur, wenn git log -1 --format=%s mit ingest-auto: beginnt. Sonst: 409 Conflict, Hinweis im Wiki-Widget („Letzter Commit war kein Auto-Ingest — bitte manuell entscheiden, was zurückgenommen werden soll”).
Mehrstufiges Undo (zwei Auto-Ingests zurück) ist bewusst nicht im Self-Service. Dafür ist ein Mensch da.
Der Undo wird im Log als ingest-auto-undo mit Hinweis auf den zurückgenommenen Commit-Hash protokolliert.
5.4.6 Duplikat-Schutz
Bevor der Auto-Ingest eine neue quellen/*.md schreibt, prüft er:
Existiert bereits eine Seite mit identischer quelle_url im Frontmatter? → kein neues Quelle-Blatt, stattdessen Update-Pfad oder log.md-Eintrag „skipped — Duplikat von “.
Existiert eine Seite mit auffallend ähnlichem Titel + Datum? → Pipeline bricht ab und fragt nach (Backend-Status: awaiting-human), statt zu raten.
5.4.7 Kuratierung nach §5.1.1 — wann der Auto-Ingest passt
§5.1.1 (Kuratierung statt Voll-Ingest) bleibt unverändert. Der Auto-Ingest wendet die §5.1.1-Kriterien selbst an, muss aber in genau diesen Fällen abbrechen und Martin fragen:
Quelle wirkt wie ein wiederkehrendes Format, das im Wiki noch nicht etabliert ist (kein Format-Stub als Quelle vorhanden).
Joule-Bezug der Quelle liegt zwischen 15 % und 25 % (Grauzone der 20-%-Heuristik).
Quelle enthält Hinweise auf Vertraulichkeit (interner Schriftzug, ADVIA-Logo auf Folien, „strictly confidential” o.ä.).
In allen drei Fällen schreibt der Auto-Ingest nichts ins Wiki, sondern legt nur den log.md-Eintrag auto-ingest-blocked an (mit kurzer Begründung) und benachrichtigt das Backend, dass eine menschliche Entscheidung nötig ist.
5.4.8 Was der Auto-Ingest niemals tut
Pakete installieren / Kommandos außerhalb der erlaubten Tool-Schicht ausführen.
git push --force, git reset --hard, git rebase — nie.
raw/ editieren (nur lesen + verschieben aus .inbox/).
Frontmatter-Felder wie reife, owner, quellen an bestehenden Seiten runterstufen oder löschen.
Externe HTTP-Requests an andere Domains als die der einzureichenden Quelle stellen (Ausnahme: Anthropic API für die Modell-Antwort).
6. Namens- und Stilkonventionen
Dateinamen: kebab-case, deutsch, ohne Umlaute (was-ist-joule.md, projekt-kunde-mueller-ag.md).
Überschriften in Title Case auf Deutsch.
Wikilinks ohne Pfad: [[was-ist-joule]]. Alias mit Pipe: [[was-ist-joule|SAP Joule erklärt]].
Fachbegriffe: Beim ersten Vorkommen pro Seite wikilinken, danach nicht mehr.
Quellenangaben am Seitenende unter ## Quellen als Bulletliste mit Wikilinks auf quellen/*.md.
Sprache: Deutsch. Originalzitate aus SAP-Quellen bleiben Englisch (in Blockquote), Zusammenfassungen auf Deutsch.
7. Wie mit Menschen kommuniziert wird
Die KI schlägt Änderungen vor, bevor sie große Umbauten macht, und wartet Bestätigung ab — es sei denn, der Mensch sagt ausdrücklich „mach einfach”.
Nach jeder Ingest-Session: Kurz zusammenfassen, welche Seiten berührt wurden, und konkrete Folgefragen stellen.
Bei Lint-Durchgängen: Handlungsempfehlungen priorisiert auflisten, nicht alles auf einmal reparieren.
8. Erweiterungen (Roadmap dieses Schemas)
Verbindliche Tags-Taxonomie für Joule-Module
Template-Dateien für häufige Seitentypen
Berechtigungsmodell, sobald das Wiki auf dem Aequitas-Server liegt
Review-Prozess (Pull-Request-basiert) für externe Beiträge