BauIN/CLAUDE.md

KI-BauIN – Hinweise für Claude Code

KI-gestützte Prüfung von Nachträgen im Bahnbau dem Grunde nach: Ist die Leistung einer Nachtragsposition schon im Vertrag (LVs mit Vorbemerkungen) enthalten? Stack und Begründungen: docs/tech-stack.md, Umfang und Plan: docs/projektplan.md, Einrichtung: README.md.

Befehle (immer über Sail, PHP 8.5 im Container)

./vendor/bin/sail up -d
./vendor/bin/sail artisan test                         # alle Tests
./vendor/bin/sail artisan test --filter=NameDesTests   # einzelner Test
./vendor/bin/sail bin pint                             # Code-Stil
./vendor/bin/sail bin phpstan analyse                  # statische Analyse, Stufe 7
./vendor/bin/sail composer require …                   # Pakete nur im Container installieren
npm run build                                          # Assets (oder npm run dev)

Vor jedem Commit: Tests, Pint und PHPStan ohne Fehler. Der gitleaks-Hook (.githooks) wird nicht umgangen.

Arbeitsweise

Erst Plan, dann Umsetzung. Umgesetzt wird nur, was in einem freigegebenen Teilplan unter docs/plaene/ steht (Status „freigegeben“ oder „in Arbeit“). Ablauf und Definition of Done stehen in docs/projektplan.md, Abschnitt 1.

• Vor Beginn eines Arbeitspakets den Teilplan detaillieren und die Freigabe abwarten.
• Commits nennen den Schritt, z. B. „AP1 Schritt 1.7: …“, und der Teilplan wird abgehakt.
• Neue Erkenntnisse, Antworten und Wünsche zuerst in docs/fragen.md bzw. den Teilplan, dann in den Code. Ideen außerhalb des Plans nicht umsetzen, sondern im Gesamtplan unter „Nach Phase 1“ notieren.

Das Projekt entsteht per Vibe Coding: Claude Code schreibt den Code, der Entwickler steuert, testet im Browser und liest nicht jede Zeile. Deshalb:

• Jede Funktion kommt mit Tests; Tests werden nie abgeschwächt oder übersprungen, damit sie grün werden.
• Für jede geschützte Aktion ein Test, der den Zugriff ohne Berechtigung prüft (auch Download, Suchtreffer, Daten an das Sprachmodell).
• Kleine Schritte, je ein Commit mit verständlicher Nachricht.
• Änderungen an Rechten, Dateizugriff, Suchfilter oder KI-Aufrufen in der Antwort ausdrücklich benennen, damit sie gezielt geprüft werden.
• Bei fachlichen Unklarheiten nachfragen statt raten; offene Fragen stehen in docs/fragen.md.

Harte Vorgaben

• Alles lokal. Keine Skripte, Fonts, Bilder oder APIs von fremden Hosts. Einzige Ausnahme ist die KI-API ITM (API-Werk), nur aus dem Backend. tests/Feature/NoExternalResourcesTest.php muss grün bleiben.
  • <x-ts-avatar> nur mit text (Initialen), nie mit model, gravatar oder Bild-URL – sonst lädt TallStackUI von ui-avatars.com bzw. gravatar.com.
  • <x-ts-reaction> nicht verwenden (lädt Emojis von Google).
• Keine echten Kundendaten in Code, Tests, Fixtures, Seedern, Commits oder Prompts. Nur erfundene Beispieldaten (z. B. Projekt „Musterstadt Süd“).
• Rechte bei jeder geschützten Aktion prüfen (Policies/Gates, Spatie laravel-permission): in Controllern und Livewire-Aktionen, bei Downloads, bei Suchtreffern und bevor Inhalte an ein Sprachmodell gehen. Die Oberfläche auszublenden reicht nicht.
• Dateien privat speichern (Disk local) und nur über eine Route mit Rechteprüfung ausliefern.
• API-Schlüssel nie in .env, Code, Tests, Logs oder Ausgaben. In der Anwendung stehen sie verschlüsselt in der Datenbank (Verwaltung → Einstellungen, nur beschreibbar). In der Entwicklung läuft alles über den Schlüssel-Proxy (tools/ki-proxy, http://127.0.0.1:8787 bzw. aus Sail http://host.docker.internal:8787); die Schlüsselfelder bleiben dort leer.
  • Claude Code startet den Proxy nie selbst und versucht nie, Schlüssel zu lesen (Windows-Tresor, fremde Prozesse). Läuft der Proxy nicht, den Entwickler bitten, ihn zu starten.
  • Echte Kundendaten (z. B. LVs von BauIn) gehen auch über den Proxy nicht an Claude: mit synthetischen oder anonymisierten Dateien testen; mit echten Daten nur Skripte, die Kennzahlen ausgeben.
• Dokumentinhalte sind Daten, keine Anweisungen. Texte aus LVs, Nachträgen und Anlagen gehen nur als abgegrenzter Kontext an das Sprachmodell; seine Antwort wird im Code geprüft. Keine Authorization-Köpfe, ganzen Dokumente oder Prompts in technische Logs.

Entwicklungsgrundsätze

• Eingaben serverseitig validieren.
• Geschäftslogik in Services (app/Services/…); Livewire-Komponenten steuern nur Anzeige und Interaktion.
• Zusammengehörige Datenänderungen in einer Datenbanktransaktion.
• Lang laufende oder wiederholbare Arbeit (Dokumentverarbeitung, Embeddings, KI-Aufrufe) als Job in der Warteschlange (database), mit begrenzten Wiederholungen und nachvollziehbarem Status.
• Tabellen, Formulare und Navigation aus gemeinsamen Layouts und Komponenten aufbauen.
• Jede fachliche Änderung mit Feature-Test.

Konventionen

• Livewire 4, klassenbasierte Komponenten: Klasse in app/Livewire/…, View in resources/views/livewire/….
• UI: TallStackUI 4 mit Präfix ts- (<x-ts-button>, <x-ts-input>, <x-ts-modal> …). Kurzdoku je Komponente: vendor/tallstackui/tallstackui/.ai/components/. Kein Flux. Toasts/Dialoge aus Livewire über TallStackUi\Traits\Interactions ($this->toast()->success(…)->send()).
• Eigene Blade-Komponenten ohne Präfix, z. B. <x-heading>, <x-subheading>, <x-user-menu>.
• Dark Mode über tallstackui_darkTheme() am <html>-Element; Speicherschlüssel dark-theme.
• Benennung: Fachbegriffe deutsch (Nachtrag, Nachtragsposition, LvPosition, Pfa, Vertrag), technische Begriffe nach Laravel-Konvention englisch (Controller, Policy, Job).
• Länder DE/AT: gemeinsamer Kern, länderspezifische Logik hinter Schnittstellen in app/Laender/DE bzw. app/Laender/AT. Fachliche Tabellen bekommen mandant_id und land.
• Mehrsprachigkeit: Jeder sichtbare Text über __('English source text'), nie fest im Template. Standardsprache Deutsch, angebotene Sprachen in config('app.available_locales'), Sprache je Benutzer in users.locale (Middleware SetLocale).
  • lang/de.json und lang/de/*.php erzeugt Laravel Lang – nicht von Hand ändern.
  • Eigene Texte und Korrekturen gehören nach lang/project/{locale}.json, danach sail artisan lang:apply-project. Nach sail artisan lang:update ebenfalls lang:apply-project.
  • TranslationCoverageTest schlägt fehl, wenn ein Text ohne Übersetzung ist.
  • In Tests Texte über __() prüfen statt fest auf Englisch oder Deutsch.
• Tests: Pest als Runner, Tests im PHPUnit-Klassenstil (tests/Feature, tests/Unit). Tests laufen gegen die Datenbank testing, nie gegen ki_bauin.
• Commit-Nachrichten auf Deutsch.