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.
219 lines
13 KiB
Markdown
219 lines
13 KiB
Markdown
# 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.
|