AGENTS.md – Leitfaden fuer KI-Agenten & Beitragende

Kurzanleitung, um in diesem Repo sicher und konsistent zu arbeiten.

Was ist das hier?

ETL-Pipeline fuer LLM/RAG: holt Wissen aus Confluence, Webseiten und PDFs, klassifiziert es nach Scope (intern/extern/allgemein) und Domaene/Tool, filtert vertrauliche Inhalte und gibt nur geprueftes Wissen frei.

Verbindliche Architektur & Wissensfluss: .kiro/steering/architecture.md (bei Aenderungen am Fluss dort die Diagramme mitpflegen).

Projektstruktur

config/tools.yaml      Tool-Katalog (manuell gepflegt; Strategien/Scopes/Optionen)
config/general.yaml    Allgemeines, tool-uebergreifendes Wissen (scope: allgemein)
config/filter_rules.json  Blacklist + Redaction
src/connectors/        Extract: confluence, web_crawler (crawler+sitemap), pdf_parser
src/transformers/      md_converter, tagger, content_filter
src/review/            Review-Gate (Routing approved/pending)
src/main.py            Orchestrator
src/site.py            GitLab-Pages-Seite -> public/ (Uebersicht, Hilfe, Chatbot, Wissensquellen)
scripts/bootstrap_tools.py  EINMALIG: Tool-Katalog aus Support-Seite erzeugen
tests/                 pytest (offline, kein Netz)

Lokale Workflows

source .venv/bin/activate
ruff check src tests scripts        # Lint (muss gruen sein)
python -m pytest -q                 # Tests (muss gruen sein)
python -m src.main --config config/tools.yaml --data output --staging staging   # ETL-Lauf
python -m src.site --data output --staging staging --out public   # Pages-Vorschau (lokal)

Confluence braucht CONFLUENCE_URL + CONFLUENCE_TOKEN (PAT, Bearer) als Env.

Goldene Regeln (MUST)

Keine Secrets in Git/Code. Tokens nur als Env-/CI-Variablen. gitleaks in CI.
Nur freigegebenes Wissen verlaesst die Pipeline (review_status: approved).
scope ist Pflicht an jedem Dokument; im Zweifel intern (restriktiv).
Output-Struktur ist output/processed/<scope>/<domaene>[/<tool>] – nicht aendern, ohne architecture.md, README und Tests anzupassen.
config/tools.yaml wird manuell gepflegt (Bootstrap nur einmalig).
Nach Codeaenderungen: ruff + pytest gruen, dann erst committen.

Scope-Klassifikation (intern vs. extern)

Keine Trennung innerhalb einer Seite. Klassifiziert wird pro Tool/Quelle.
Tool-scope in tools.yaml: intern | extern | allgemein | mixed (mixed = Quellen mit unterschiedlichem Scope; im Zweifel zwei Seiten).
Source-scope: intern | extern | allgemein | "intern,extern" (letzteres nutzt die ganze Seite fuer beide Scopes, dupliziert).
Quellen ohne eigenen Scope erben den Tool-Scope (mixed => intern).
Allgemeines Wissen steht in config/general.yaml.

Vorsicht bei Confluence-Schreibzugriffen

Das Skript-Muster kann Confluence-Seiten anlegen/aendern (z.B. Option-A-Template). Solche Schreibzugriffe sind additiv oder versioniert/revertierbar zu halten und vorher anzukuendigen. Niemals Inhalte ungefragt loeschen.

3.0 KiB Raw Permalink Blame History Unescape Escape