Files
Speech/AGENTS.md
T
Eugenius Naumenko 16cceae28a Muttersprache koppeln und russischen A1-Kurs ergänzen
GUI und neue Erklärungen verwenden gemeinsam native_language. Deutsch und
Russisch sind die beiden Muttersprachen; Englisch bleibt die Lernsprache.
Kompatibilitätsfelder werden atomar gekoppelt, widersprüchliche Eingaben
abgewiesen und bestehende Profile sowie eingefrorene Inhalte erhalten.

Ergänzt vollständige russische GUI-Kataloge und 840 geprüfte Aufgabenansichten
in sieben Modulen einschließlich A1-Test, mit getrennten Sprachrollen für
Ausgangs- und Lernmaterial. Äquivalente Ansichten teilen ihre Nachweisidentität.
Stabile API-Fehlercodes, neue deterministische Hilfen und Trainingsbegründungen
berücksichtigen die Muttersprache. Dokumentiert das Sprachmodell in AGENTS.md.

Validierung: Go-Race-Suite mit eigener lokaler PostgreSQL-Testdatenbank, go vet,
Web-Build, Offline-Bank-/Variantenaudit, Diff-Prüfung sowie lokale Browser-Smokes
für Sprachen, Kurs, Administration, Aussprache und Aufnahme. Keine Live-Anbieter,
Produktionsprofile, Deployment-Schritte oder historischen Neubewertungen.
2026-11-07 17:02:17 +00:00

14 KiB

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.

Verbindliches Sprachmodell

  • Es gibt genau zwei Sprachrollen: Muttersprache und Lernsprache.
  • Die Muttersprache bestimmt gemeinsam die gesamte GUI, Aufgabenanweisungen, Erklärungen, Hilfen und neue Rückmeldungen. GUI- und Erklärungssprache dürfen weder unabhängig wählbar sein noch auseinanderlaufen. Im Produkt heißen sie einheitlich „Muttersprache“, nicht GUI-/Oberflächen-/Erklärungssprache.
  • Unterstützte Muttersprachen sind Deutsch (de-DE) und Russisch (ru-RU). Englisch (en-US) ist die bisherige Lernsprache, keine dritte Muttersprache.
  • Neue Nutzer haben eine gemeinsame Muttersprache. Ein Wechsel aktualisiert diese atomar und erhält Lernsprache, Niveau, Tagesziel und Lernstand.
  • Die kanonische Präferenz heißt native_language. Historische/API-kompatible Felder ui_language und instruction_language dürfen lediglich denselben Wert abbilden; widersprüchliche Eingaben werden abgelehnt.
  • Zielsprache und Speech-Locale richten sich nach der Lernsprache des jeweiligen Lerninhalts. Englische Lerntexte, Antwortwörter und Aufnahmen werden nicht durch eine Übersetzung der Muttersprache ersetzt.
  • Übersetzte Aufgaben behalten eindeutige Lösungsschlüssel und sichtbare, gleichwertige Anforderungen. Russische Wortbedeutungen und Ausgangssätze brauchen eine fachliche Prüfung; keine pauschale Textübersetzung.
  • Bereits zugewiesene Aufgaben, alte Rückmeldungen, Bewertungen und Messungen behalten ihren eingefrorenen Inhalt und ihre damalige Sprache. Neue Aufgaben und Aufträge speichern ihre Muttersprache und Inhaltsrevision. Ein Wechsel der Muttersprache ist keine Neubewertung und kein zusätzlicher Lernnachweis.

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:

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:

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.