ChristophandClaude Opus 5.5
2143f4e955
- docs/projektplan.md neu gegliedert: Arbeitsweise mit Freigaben, Zuständigkeiten, Meilensteine mit Abnahmekriterien, Arbeitspakete mit Status, Zeitplan, Entscheidungen - docs/plaene/: Teilplan je Arbeitspaket (detailliert für AP0, AP1, AP2, AP3, AP5, AP11, AP13; grob für AP4, AP6–AP10, AP12, Optionen) und Vorlage - docs/fragen.md: alle offenen Fragen mit Status, Empfänger und betroffenem Teilplan - CLAUDE.md: Umsetzung nur nach freigegebenem Teilplan Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
106 lines
6.7 KiB
Markdown
106 lines
6.7 KiB
Markdown
# 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)
|
||
|
||
```bash
|
||
./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.
|