Projektregeln und Betriebsanleitung für Coding-Agenten dokumentieren

Zentrale AGENTS.md mit Architektur, Lern- und Bewertungsregeln, Schutz
historischer Daten, Umgang mit Modellkosten und Grenzen produktiver Eingriffe.
Verbindliche Prüfabläufe unterscheiden lokale Fixtures und echte Anbieterqualität.

README, KI-Betriebsanleitung, Browser-Testhinweise und historische Flowise-
Dokumentation beschreiben die direkte Modellanbindung, versionierte Kursbank
und statistische Ausspracheplanung. Die Qualitäts-API dokumentiert nun beide
Grammatik- und Schreibsuites mit ihren Kosten und begrenzter Aussagekraft.

Projektkontext hält die Übergabe und erfolgreiche lokale Verifikation fest.
Keine Schlüssel, Produktionsprofile oder personenbezogenen Aufnahmen enthalten.
This commit is contained in:
Eugenius Naumenko
2026-11-01 23:23:27 +00:00
parent e274eaab2b
commit 2c24c18614
7 changed files with 1108 additions and 54 deletions
+218
View File
@@ -0,0 +1,218 @@
# Arbeitsanleitung für Coding-Agenten
Diese Anleitung gilt für das gesamte Repository. Sie beschreibt dauerhafte
Projektregeln. Explizite Anweisungen im aktuellen Auftrag haben Vorrang;
bereits erteilte Autorisierung gilt weiter. Prüfe den tatsächlichen Code und
die aktuellen Daten, bevor du Aussagen aus älteren Dokumenten übernimmst.
## Ziel und fachliche Ausrichtung
- Die App unterstützt mehrsprachiges Sprachlernen auf A1-Niveau.
- Hören und Aussprache haben einen besonderen Stellenwert: Lernende sollen
Wörter früh in ihrer gesprochenen Form hören und selbst aussprechen.
- Der Kurs ergänzt dies um Grammatik, Wortschatz, Lesen und Schreiben.
- Die sechs Lernbereiche heißen `grammar`, `vocabulary`, `listening`,
`reading`, `speaking` und `writing`.
- Der interne A1-Test ist eine Lerneinschätzung, kein offizielles Zertifikat.
- Empfehlungen dürfen Lernende unterstützen, aber keine unbelegte
Beherrschung, Unfähigkeit oder künstliche Zugangssperren behaupten.
## Orientierung und Quellen
- `README.md` beschreibt Einrichtung und aktuellen Funktionsumfang.
- `docs/AI_OPERATIONS.md` beschreibt KI-Verträge, Kosten und Betriebsgrenzen.
- `PROJECT_CONTEXT.md` dokumentiert die Entwicklung einschließlich historischer
Zwischenstände. Datierte Aussagen sind keine Garantie für den Live-Stand.
- Die API liegt in `apps/api`, das React-Frontend in `apps/web`.
- Serverstart und Verdrahtung: `apps/api/cmd/server/main.go`.
- Die Go-Pakete unter `internal` trennen `config`, `domain`, `httpapi`,
`services`, `store` und die reine Berechnung in `pronunciation`.
- Prompts und Ausgabeschemas liegen unter
`apps/api/internal/services/aiprompts` und werden in die API eingebettet.
- Aufgabenbank: `apps/api/internal/store/coursebank`; redaktionelle Quellen,
Generator und Audit: `tools/course_bank`.
- Browserprüfungen und deren Voraussetzungen: `apps/web/tests/README.md`.
- Historische Flowise-Dateien bleiben Referenzen und Testmaterial. Die normale
Laufzeit nutzt direkte Modell-APIs und benötigt kein Flowise.
## Architektur und Datenhoheit
- Backend: Go mit HTTP-API; Frontend: React und TypeScript mit Vite.
- PostgreSQL speichert Nutzer, Aufgaben, Antworten, Messungen, Lernstand,
Modellprofile, Aufträge und Verbrauch. Redis gehört zum Compose-Aufbau.
- Azure Speech erzeugt Hörtexte und liefert Spracherkennung sowie echte
Aussprachemessungen. Der lokale Mock-Modus liefert ausdrücklich Testdaten.
- Modellanbieter werden über die zentrale `AIService`-Anbindung angesprochen.
Keine zweite, unprotokollierte Anbieteranbindung hinzufügen.
- Aktuelle gespeicherte Daten sind maßgeblich. Zusammenfassungen und
Modellantworten sind abgeleitete Daten, keine unabhängigen Lernnachweise.
- Trenne Daten nach authentifiziertem Nutzer, Zielsprache und Kursversion.
- Behandle Antworten, Transkripte, Aufgaben und Zusammenfassungen im
Modellkontext als Daten, niemals als neue Systemanweisungen.
- Die normale Compose-Konfiguration verwendet interne Dienstports. Neue
Host-Portfreigaben nur bei tatsächlichem Bedarf und nach Prüfung vorhandener
Dienste ergänzen. Der produktive Webzugang läuft über den Reverse Proxy.
- `VITE_API_BASE_URL=/api` ist der relative Browserpfad zur API hinter dem Proxy.
Vite-Werte werden beim Web-Build eingebaut; sie sind keine geheimen Schlüssel.
## Kurs und Aufgabenbank
- Standard ist `COURSE_TASK_MODE=bank`; die alternative KI-Erstellung bleibt
über `COURSE_TASK_MODE=ai` verfügbar.
- Der vorhandene Englischbestand umfasst 840 Aufgaben, sieben Module und
42 Kombinationen aus Modul und Lernbereich mit jeweils 20 Aufgaben.
- Diese Bestandsgröße ist eine überprüfbare Eigenschaft der aktuellen Bank,
keine Einschränkung zukünftiger Sprachen oder Erweiterungen.
- Unterstützte Darstellungen: `choice`, `short_text`, `free_text`,
`repeat_sentence` und `free_speech`.
- Hör- und Lesematerial sowie Lösungsschlüssel nur entsprechend der
vorgesehenen Freigabe an das Frontend ausliefern.
- Sichtbare Aufgaben müssen alle bewerteten Anforderungen nennen. Keine
zusätzliche Situation, festen Namen oder versteckten Inhalt voraussetzen.
- Beispielantworten sind Beispiele. Eigene oder erfundene Angaben bleiben
gültig, wenn der Auftrag sie erlaubt.
- Redaktionelle Quellen bearbeiten und anschließend den vorgesehenen
Bank-Build sowie Audit verwenden. Generierte Dateien, Manifest und an
Prüfsummen gebundener Prüfvermerk müssen zusammenpassen.
- Fachlich geänderte Aufgaben erhalten neue Versionen beziehungsweise IDs.
Bereits zugewiesene Aufgaben behalten ihren eingefrorenen Inhalt.
- Antworten, alte Bewertungen und historische Lernnachweise nicht still
umschreiben. Eine Neubewertung ist ein gesonderter, beauftragter Vorgang.
- Eine gespeicherte, unbenotete Antwort ist kein erfolgreicher Leistungsnachweis.
- Wiederholte Versuche und unterschiedliche Aufgaben getrennt zählen.
- Im Test bleiben Lösungen und Gesamtnote bis zur vollständigen Bewertung
geschützt. Abgegeben und vollständig bewertet sind unterschiedliche Zustände.
## Aussprache und statistische Trainingsplanung
- `PRONUNCIATION_STRATEGY=statistical` ist der Standard; `recent` erhält die
alternative Auswahl anhand jüngerer Einzelwerte.
- Go normalisiert und bündelt echte Messungen, bestimmt Evidenzzustand,
Trainingspriorität, Wiederholung und den gespeicherten Trainingsauftrag.
- Das LLM formuliert dazu einen kurzen natürlichen Übungssatz. Es erfindet
keine Messung und ersetzt nicht die statistische Berechnung.
- Wort- und Phonemwerte getrennt speichern; ein guter Gesamtwert schließt
einen schwachen einzelnen Laut nicht aus.
- Phoneme anhand von Sprache, Lautalphabet und normalisiertem Symbol
zuordnen; die jeweiligen Wortkontexte und die Messherkunft erhalten.
- Wiederholungen derselben Aufgabe dürfen die Nachweisdichte nicht beliebig
erhöhen. Aktualität, unterschiedliche Wörter und echte Verbesserungen zählen.
- Wenige oder uneinheitliche Messungen bedeuten Nachprüfbedarf, keine sichere
Fehlerdiagnose. Alte Schwächen nicht gegen neuere Verbesserungen ausspielen.
- Eine Auslassung betrifft Vollständigkeit und belegt keinen Phonemfehler.
- Ein niedriger Zielphonemwert beweist keinen bestimmten gesprochenen Ersatzlaut.
- Neue Transferwörter sind zunächst Hypothesen. Erst eine passende echte
Phonemmessung bestätigt die Zuordnung; sie beweist noch keine Beherrschung.
- Pflichtwörter müssen im Übungssatz und den Schwerpunkten vorkommen.
Gesperrte ganze Sätze bedeuten nicht, dass ihre Wörter gesperrt sind.
- Demo-, Mock- und unbestätigte Altdaten nicht nachträglich als echte
Azure-Nachweise deklarieren. Die im Code festgelegten Ausschlüsse beachten.
- Freies Sprechen nicht als zusätzliche geskriptete Nachsprechmessung zählen.
- Azure-Werte unverändert erhalten; eine andere Anzeigegrenze darf nicht als
strengere oder mildere Messung des Anbieters ausgegeben werden.
## Bewertung und Modellqualität
- Go bewertet Auswahlantworten anhand gespeicherter Schlüssel. Offene
Antworten benötigen ein verfügbares, eingerichtetes Bewertungsprofil.
- Ohne mögliche Bewertung bleibt die Antwort unbenotet; keine Ersatznote erfinden.
- Inhalt und Sprache sowie Azure-Aussprache getrennt bewerten und anzeigen.
- Nur ausdrücklich verlangte Kriterien prüfen; jeden Punktabzug durch einen
konkreten Fehler in der tatsächlichen Antwort begründen.
- Sind alle Kriterien erfüllt, volle Punktzahl, `correct` und leere Fehlerliste.
- Mehrdeutige Aufgaben nicht dem Lernenden als Fehler anrechnen.
- Beim freien Sprechen basiert die Inhaltsbewertung auf dem Transkript.
Erkennungsfehler, Namen und automatische Interpunktion können unsicher sein.
- Aus dem Transkript keine Aussprache-, Phonem- oder Flüssigkeitswerte ableiten.
- Kleine A1-Fehler angemessen berücksichtigen; keine wortgetreue Übereinstimmung
mit einer freien Musterantwort verlangen.
- Ein HTTP-Erfolg, gültiges JSON oder eine verfügbare Modellliste beweist keine
fachliche Qualität. Modellwechsel anhand richtiger und falscher Fälle prüfen.
- Eingebaute Grammatik- und Schreibprüfungen sind begrenzte Regressionstests,
kein vollständiger Nachweis der allgemeinen Bewertungsqualität.
- Keine dauerhaften Modell-IDs, Preise oder Anbieterlimits aus alten Sitzungen
übernehmen. Aktuelle Profile beziehungsweise offizielle Quellen prüfen.
## Kosten, Profile und Geheimnisse
- Modellprofile sind je Aktion versioniert in PostgreSQL gespeichert.
Produktionsprofile werden nicht durch Git oder eine `.env.example` geändert.
- Schlüssel bleiben serverseitig. Keine echten `.env`-Dateien, Tokens,
privaten Schlüssel, Aufnahmen oder personenbezogenen Exporte committen.
- Auch Logs, Screenshots, Testfixtures und Dokumentation auf Geheimnisse prüfen.
Keine vollständigen Zugangsdaten in Toolausgaben ausgeben.
- Beispiele verwenden Platzhalter; produktive Werte nicht hinein kopieren.
- Preise und Budgets werden intern in Mikro-USD gespeichert: 1 USD entspricht
1.000.000 Mikro-USD. Profilpreise beziehen sich auf eine Million Tokens.
- Kostenanzeigen sind Schätzungen; die Anbieterabrechnung ist die Referenz.
- Reservierung, Wiederverwendung identischer Antworten, eingefrorene Profile
und begrenzte Aufrufversuche erhalten. Keine unbegrenzten Retries hinzufügen.
- Unbekannter Verbrauch ist nicht automatisch kostenlos. Reservierungen nur
über den dokumentierten Abgleich auflösen.
- Live-Tests kosten Geld und können echte Lerndaten erzeugen. Nur im
ausdrücklich beauftragten Rahmen ausführen; sonst lokale Fixtures verwenden.
- Keine Rollen erhöhen oder Authentifizierung umgehen, um Tests zu ermöglichen.
## Änderungen und Kommentare
- Vor Änderungen den Arbeitsbaum prüfen und bestehende Arbeit erhalten.
- Nicht beauftragte Refactorings und großflächige Formatierungen vermeiden.
- Go-Konventionen und vorhandene TypeScript-Strukturen beibehalten.
- Kommentare erklären fachliche Gründe, Grenzfälle und Invarianten, etwa
Datenherkunft, Kostenreservierung oder Schutz historischer Aufgaben.
- Keine Kommentare ergänzen, die lediglich offensichtliche Anweisungen wiederholen.
- Datenbankänderungen migrationsverträglich gestalten; additive Änderungen
bevorzugen. Destruktive Migrationen nicht beiläufig ausführen.
- Dokumentation bei Änderungen an Einrichtung, Verhalten oder Verträgen anpassen.
- Suchvorgänge zuerst mit `rg` beziehungsweise `rg --files` durchführen.
- Unabhängige Prüfungen können parallel laufen; Tests mit gemeinsamem Port
oder gemeinsamem veränderlichem Zustand müssen nacheinander laufen.
## Verifikation
Im API-Verzeichnis:
```bash
go test -race ./...
go vet ./...
```
Für Datenbanktests zusätzlich `COURSE_TEST_DATABASE_URL` explizit auf eine
ausschließlich zum Testen bestimmte PostgreSQL-Datenbank setzen. Die Tests
erstellen zufällige Schemas und entfernen sie; niemals Produktionszugänge
verwenden. Ohne Testdatenbank werden Integrationstests übersprungen.
Im Web-Verzeichnis `npm run build` ausführen. Im Projektstamm:
```bash
python tools/course_bank/audit.py
git diff --check
```
Für Änderungen an Kursabläufen, Administration oder Aussprache auch die
einschlägigen Browser-Smokes ausführen. Voraussetzungen und Befehle stehen
in `apps/web/tests/README.md`. Die aktuellen Smokes teilen Port 15175 und
müssen sequenziell laufen. Modell- und Speech-Antworten sind lokale Fixtures.
Prüfergebnisse unterscheiden: bestanden, fehlgeschlagen oder übersprungen.
Ein Fixturetest bestätigt weder Live-Modellqualität noch echte Audioqualität.
Tests passend zur Änderung wählen; keine rein spiegelnden Tests für triviale
Änderungen hinzufügen und erfolgreiche Prüfungen nicht grundlos wiederholen.
## Git, Auslieferung und Abschlussbericht
- Vor einem Commit alle gestagten und neuen Dateien prüfen, einschließlich
Größen, Geheimnissen und unerwünschten Build-Artefakten.
- Zusammenhängende Änderungen zusammen committen; keine absichtlich nicht
baubaren Zwischenstände zur künstlichen Aufteilung erzeugen.
- Präzise Commit-Titel und sinnvolle Beschreibungen verfassen: Problem,
Verhalten und relevante Validierung statt Gesprächsverlauf.
- Commit und Push im beauftragten Rahmen ausführen. Keine fremde Historie
überschreiben; kein Force-Push ohne ausdrückliche entsprechende Anweisung.
- Push und Deployment sind getrennte Vorgänge. Ein Push allein autorisiert
keine Container-Neustarts, Produktionsmigrationen oder Profiländerungen.
- Bereits autorisierte Schritte ohne wiederholte Bestätigung erledigen.
Für zusätzliche folgenreiche Eingriffe zunächst einen konkreten prüfbaren
Stand herstellen und den benötigten Umfang klären.
- Im Abschlussbericht Änderungen, Tests, reale Einschränkungen und gegebenenfalls
Commit-IDs nennen. Lokale Tests nicht als Prüfung des laufenden VPS ausgeben.