Skip to content

AGENTS.md

Latest commit

 

History

History
105 lines (74 loc) · 4.08 KB

AGENTS.md

File metadata and controls

105 lines (74 loc) · 4.08 KB
Raw

Agent-Instruktionen für dieses Repository

Grundprinzip: Knowledge Graph zuerst

Dieses Repository enthält einen RDF Knowledge Graph (Turtle-Dateien), der die Fachdomäne des Shops strukturiert und maschinenlesbar dokumentiert.

Wenn der Nutzer eine inhaltliche Frage stellt – z. B. zu Versandregeln, Exportbeschränkungen, Produktkategorien, Preisregeln, Stakeholdern oder anderen Fachthemen – gilt immer:

🔍 Zuerst den Knowledge Graph per SPARQL abfragen, dann antworten.

Niemals aus dem Gedächtnis/Trainingsdaten raten. Der Graph ist die Wahrheitsquelle.

⚠️ Keine Schlussfolgerungen als Graphfakten ausgeben. Jede Aussage über Zusammenhänge muss durch einen konkreten Triple im Graphen belegt sein. Inhaltliche Interpretationen aus Textdefinitionen oder LLM-Weltwissen sind explizit als Interpretation zu kennzeichnen – niemals als Tatsache aus dem Graphen darstellen.

TTL-Dateien im Workspace

Der Knowledge Graph wächst dynamisch. Nie einzelne Dateien hardcoden. Stattdessen vor jeder Abfrage alle vorhandenen TTL/RDF-Dateien ermitteln:

find graph -name "*.ttl" -o -name "*.rdf" -o -name "*.n3"

Alle gefundenen Dateien sind gleichwertige Teile des Knowledge Graphs und müssen bei inhaltlichen Fragen berücksichtigt werden. Neue Fachmodule landen ebenfalls in graph/ – deshalb immer dynamisch suchen, nie Pfade hardcoden.

SPARQL-Abfragen ausführen

Skill: sparql-query (bereits installiert unter .agents/skills/sparql-query/) - vor Durchführung von Queries einlesen.

# Abhängigkeiten (einmalig):
cd .agents/skills/sparql-query && npm install

# Abfrage ausführen:
node .agents/skills/sparql-query/scripts/query.js \
  --file graph/<modul>.ttl \
  --sparql "SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 20"

Wichtige Prefixe

Diese Prefixe sind projektspezifisch. Nach dem Namespace-Setup anpassen. Standard-Vokabular (skos, owl, rdfs, dct, xsd, schema) bleibt immer gleich.

PREFIX skos:   <http://www.w3.org/2004/02/skos/core#>
PREFIX owl:    <http://www.w3.org/2002/07/owl#>
PREFIX rdfs:   <http://www.w3.org/2000/01/rdf-schema#>
PREFIX dct:    <http://purl.org/dc/terms/>
PREFIX xsd:    <http://www.w3.org/2001/XMLSchema#>
PREFIX schema: <https://schema.org/>
PREFIX sh:     <http://www.w3.org/ns/shacl#>
# Domänenspezifische Prefixe hier ergänzen, z. B.:
# PREFIX :  <https://example.org/domain#>

Validierung nach jeder Änderung am Graph

Nach jeder Änderung an .ttl- oder .rq-Dateien muss validiert werden. Nur die tatsächlich geänderten Dateien übergeben:

# Eine oder mehrere konkrete Dateien prüfen (bevorzugt):
node .agents/skills/sparql-query/scripts/validate.js graph/<modul>.ttl queries/<modul>/<query>.rq

# Alle Dateien prüfen (nur wenn viele Dateien auf einmal geändert wurden):
npm run validate

Bei Exit-Code 1 den Fehler beheben, bevor die Antwort an den Nutzer geht.

Workflow für jede inhaltliche Nutzerfrage

  1. Skill-Dokumentation lesen: cat .agents/skills/sparql-query/SKILL.md
  2. Alle TTL-Dateien ermitteln: find graph -name "*.ttl" -o -name "*.rdf" -o -name "*.n3"
  3. Vorhandene Queries prüfen: find queries -name "*.rq" – passende .rq-Datei direkt ausführen
  4. SPARQL-Abfrage semantisch formulieren (Typen und Instanzen, kein Textfilter auf URIs)
  5. Triple-Verifikation: Jede inhaltliche Aussage in der Antwort muss durch einen konkreten abgefragten Triple gedeckt sein. Schlussfolgerungen, die nur aus Textdefinitionen oder LLM-Weltwissen stammen, explizit als Interpretation (nicht im Graph modelliert) kennzeichnen.
  6. Ergebnis in natürlicher Sprache erklären – mit klarer Trennung zwischen:
    • ✅ Im Graph modelliert: direkt durch Tripel belegte Aussagen
    • 💡 Interpretation: plausible Schlussfolgerungen, die nicht als Tripel im Graph existieren

Hinweis zur Dateiauswahl

Da der Graph dynamisch wächst, gibt es keine feste Zuordnung von Themen zu Dateien. Im Zweifelsfall alle gefundenen TTL-Dateien abfragen oder zunächst mit einem breiten SELECT ?s ?p ?o die Inhalte sondieren.