maboto/CLAUDE.md

CLAUDE.md -- Angebots-Übersicht

Leitfaden für die Entwicklung dieses Projekts mit Claude Code.

Was dieses Projekt ist

Eine sachliche, ortskonkrete Übersicht der wöchentlichen Supermarkt- und Discounter-Angebote, sortiert nach Produktgruppen. Kein Hochglanzprospekt einzelner Händler, sondern eine händlerübergreifende, neutrale Liste: "Was ist diese Woche an Ort X im Angebot, geordnet nach Kategorie."

Das Leitprinzip: der Schnitt

Diese Aufgabe sieht nach einer KI-Aufgabe aus. Sie ist es nur zur Hälfte. Sie zerfällt in zwei grundverschiedene Teilprobleme, die strikt getrennt gehören:

1. Daten holen (ortskonkret, händlerübergreifend) -- das ist deterministisch. Hier wird KI eingespart. Ein HTTP-Abruf / Parser leistet das exakt und reproduzierbar. Ein LLM würde hier nur Preise und Gültigkeiten halluzinieren. Dieser Teil enthält keine LLM-Aufrufe.

2. Kategorisieren (flacher Angebots-Stream → saubere Produktgruppen) -- das ist die echte Ambiguität: "Ist Toffifee Süßwaren? Ist Schwarzwälder Schinken Fleisch/Wurst? Gehört eine Blühpflanze überhaupt in eine Lebensmittel-Übersicht?" Genau hier ist ein LLM das richtige Werkzeug -- und nur hier.

Merksatz: Vor KI muss man erst einmal KI einsparen. Aber dort, wo nur sie passt, muss man sie auch einsetzen. Wer die ganze Aufgabe dem Modell gibt, bekommt Fiktion. Wer sie ganz deterministisch löst, scheitert an der Kategorisierung. Richtig ist die Arbeitsteilung.

Dieser Schnitt ist nicht verhandelbar. Er ist die Architektur des Projekts, nicht eine Stilpräferenz. Vermische die beiden Teile nicht.

Architektur statt Präferenz

Qualitätsregeln werden hier festverdrahtet, nicht "mitgedacht". Eine Regel, die nur als höfliche Bitte im Code steht ("möglichst keine erfundenen Preise"), bricht unter Druck still weg. Eine Regel, die als prüfbare Bedingung im Datenfluss steht, hält.

Konkrete Konsequenzen, die jederzeit gelten:

• Kein Auffüllen. Wenn für eine Produktgruppe keine belegten Angebote vorliegen, wird "keine Daten" ausgegeben -- niemals ein plausibel klingendes Beispiel erfunden.
• Jedes ausgegebene Angebot ist belegt. Preis, Gültigkeit und Händler stammen aus dem abgerufenen Datensatz, nicht aus dem Modell. Wenn ein Feld fehlt, wird es als fehlend markiert, nicht geraten.
• Abbruch statt stiller Drift. Wenn die Datenlage die Anforderung nicht hergibt (z. B. kein Treffer für den Ort), bricht das Programm mit einer klaren Meldung ab und nennt die Ursache und einen Erweiterungsvorschlag. Es liefert kein "irgendwie vollständig aussehendes" Ergebnis.

Diese drei Punkte sind der Grund, warum "die KI soll sagen, wenn sie scheitert" hier funktioniert: nicht weil das Modell Einsicht hätte, sondern weil eine externe, prüfbare Bedingung es erzwingt.

Sichtbarkeit der LLM-Arbeit (Grundregel)

So wie das System sichtbar abbricht, wenn es scheitert, muss es auch sichtbar zeigen, wenn es arbeitet. Jede LLM-Aktion (die Kategorisierung) wird in der Oberfläche als laufende Aktivität dargestellt: erkennbarer Fortschritt (z. B. „LLM kategorisiert … Batch X/Y"), ein animierter Indikator, und das auslösende Bedien-Element im Lade-Zustand. Eine LLM-Aktion darf nie wie ein eingefrorenes, totes UI aussehen.

Der Grund ist derselbe wie beim Abbruch: Transparenz. Der Nutzer muss jederzeit zwischen „arbeitet gerade" und „hängt / ist fertig" unterscheiden können -- sonst wirkt selbst ein korrekt laufender Prozess wie ein Defekt. Das gilt für die Web-UI (animierter Status + Fortschrittsbalken) ebenso wie für die CLI (laufende Status-/Batch-Zeile). Deterministische Schritte (Fetch) dürfen still sein; die LLM-Schritte nicht.

Skills

Das Projekt nutzt zwei Skills (in .claude/skills/), die exakt dem Schnitt folgen:

• angebote-fetch -- deterministischer Datenabruf. Keine LLM-Aufrufe.
• angebote-kategorisieren -- LLM-gestützte Einordnung in Produktgruppen.

Lies die jeweilige SKILL.md, bevor du an dem zugehörigen Teil arbeitest. Die SKILL.md ist die verbindliche Spezifikation für ihren Bereich.

Tech-Kontext

• Sprache: Python (FastAPI-nah).
• Öffentlicher Stack-Bezug, falls relevant: FastAPI, Qdrant, A2A.
• Datenquellen-Kandidaten für den Fetch-Teil: Angebots-Aggregatoren, die nach Ort/PLZ filtern (z. B. marktguru, kaufda, MeinProspekt). Discounter wie Aldi/Lidl liefern oft nicht an Aggregatoren -- das ist ein bekanntes Abdeckungsloch und gehört ehrlich als solches ausgewiesen, nicht kaschiert.

Arbeitsweise mit Claude Code

• Beginne jede Aufgabe damit, den relevanten Teil dieses Dokuments und die passende SKILL.md zu lesen.
• Halte den Schnitt sauber: kein LLM-Aufruf im Fetch-Teil, kein heimliches Daten-"Reparieren" im Kategorisier-Teil.
• Wenn eine Anforderung den Schnitt verletzen würde, benenne den Konflikt, bevor du Code schreibst.
• Schreibe Tests für die Architektur-Regeln (kein Auffüllen, Abbruch bei leerer Datenlage), nicht nur für den Happy Path.