Gardomatic/AGENTS.md

AGENTS.md

Diese Anweisungen gelten für das gesamte Repository. Benutzeranweisungen haben Vorrang. Spezifischere AGENTS.md- oder AGENTS.override.md-Dateien in Unterverzeichnissen dürfen diese Regeln für ihren Bereich ergänzen oder überschreiben.

Projektüberblick

Gardomatic ist eine mobile, mehrbenutzerfähige Gartenverwaltung in Go. Das Repository enthält drei Programme:

• cmd/api: JSON-API; besitzt Authentifizierung, Autorisierung und Fachlogik.
• cmd/web: serverseitig gerenderte Webanwendung; greift ausschließlich über lib/client auf die API zu.
• cmd/cli: Administration über direkten PostgreSQL-Zugriff.

PostgreSQL ist die einzige unterstützte Datenbank. Das Web-Frontend soll in den wesentlichen Abläufen ohne JavaScript funktionieren; htmx ergänzt diese Abläufe.

Arbeitsweise

• Vor Änderungen zuerst den betroffenen Ablauf über alle Schichten verfolgen. Relevante Implementierungen, Helfer und Tests mit rg suchen.
• Änderungen klein und auf den Auftrag begrenzt halten. Keine beiläufigen Umbenennungen, Formatierungen oder Refactorings außerhalb des betroffenen Bereichs durchführen.
• Bestehende, nicht zum Auftrag gehörende Änderungen im Arbeitsverzeichnis erhalten und nicht überschreiben.
• Fachliche Änderungen als vollständigen Vertical Slice umsetzen, soweit betroffen: Migration, Storage-Vertrag, PostgreSQL-Adapter, API, Client, Web und Tests.
• Öffentliche Schnittstellen und persistierte Daten nur bewusst und rückwärtskompatibel ändern. Unvermeidbare Brüche klar dokumentieren.

Struktur und Schichtengrenzen

• cmd/* bleibt schlank und enthält nur Konfiguration, Verdrahtung und Startcode.
• Datenbankzugriffe gehören hinter die Verträge in internal/storage; konkrete PostgreSQL-Implementierungen liegen in internal/storage/postgres.
• HTTP- und Berechtigungslogik der JSON-API gehört in internal/api.
• Wiederverwendbare API-Aufrufe des Web-Clients gehören in lib/client.
• internal/web greift nicht direkt auf PostgreSQL oder Storage-Modelle zu.
• Browserpfade werden zentral in internal/web/paths.go gepflegt; keine verstreuten Pfad-Literale einführen.
• Templates, statische Dateien und Mailvorlagen in ihren bestehenden Verzeichnissen ablegen und die vorhandenen Einbettungsmechanismen beibehalten.
• Neue Pakete nur bilden, wenn sie eine klare Verantwortung besitzen. Keine Sammelpakete wie utils, common oder helpers neu einführen.

Idiomatischer Go-Code

• Die in go.mod festgelegte Go-Version und Standardbibliothek bevorzugen.
• Geänderte Go-Dateien mit gofmt formatieren. Code muss go vet und staticcheck bestehen.
• Kleine, fokussierte Funktionen, frühe Rückgaben und verständliche Namen bevorzugen. Kommentare erklären das Warum, nicht den offensichtlichen Ablauf.
• Fehler mit hilfreichem Kontext und %w weiterreichen, wenn Aufrufer die Ursache noch untersuchen sollen. Erwartbare Domänenfehler mit errors.Is/errors.As behandeln.
• context.Context entlang bestehender Request- und Storage-Grenzen weitergeben; keine neuen Hintergrundkontexte mitten in einem Request-Ablauf erzeugen.
• Abhängigkeiten explizit verdrahten. Globale veränderliche Zustände vermeiden.
• Neue Produktionsabhängigkeiten nur bei klarem Mehrwert einführen. Vorhandene Standardbibliotheks- oder Projektlösungen bevorzugen und neue Abhängigkeiten in der Übergabe begründen.

Keine Codeduplizierung

• Vor dem Anlegen neuer Typen, Validatoren, Abfragen, Handler-Helfer, Clientmethoden oder Template-Teile nach gleichartigem Code suchen.
• Gemeinsame fachliche Regeln an einer Stelle implementieren und von den aufrufenden Schichten wiederverwenden. API und Web dürfen dieselbe Fachregel nicht unabhängig voneinander nachbilden.
• Wiederholte SQL-Fragmente, Filter- und Paginglogik über die bereits vorhandenen Storage-Helfer konsolidieren, sofern Semantik und Sicherheitsgrenzen identisch sind.
• Ähnliche, aber fachlich unterschiedliche Abläufe nicht vorschnell abstrahieren. Eine Abstraktion muss Namen, Verantwortung und Fehlerverhalten klarer machen.
• Beim Entfernen einer Duplikation alle Aufrufer migrieren und das alte Konstrukt löschen, sobald es nicht mehr benötigt wird.

Fachliche und sicherheitsrelevante Regeln

• Ein Garten ist eine abgeschlossene Daten- und Berechtigungsgrenze. Jede gartenbezogene Abfrage muss die Garten-ID berücksichtigen.
• Fremde oder nicht sichtbare Garten-IDs liefern 404; verbotene Aktionen in einem sichtbaren Garten liefern 403.
• Authentifizierung und Autorisierung verbleiben in der API. Das Web leitet das Session-Cookie über einen request-spezifischen API-Client weiter.
• Rollen und Berechtigungen nicht durch reine UI-Prüfungen absichern.
• Artenstammdaten und konkrete Pflanzen getrennt halten; Pflanzen dürfen ohne Art existieren.
• Automatisch erzeugte Aufgaben müssen idempotent bleiben. Fälligkeitsfenster und Zeiträume über Jahresgrenzen hinweg korrekt behandeln.
• Nutzereingaben an der zuständigen Systemgrenze validieren. HTML-Ausgabe über html/template escapen und bestehende CSRF-, Cookie- und Security-Header- Mechanismen nicht umgehen.
• Keine Zugangsdaten, Tokens, echte personenbezogene Daten oder lokale .env- und .envrc-Inhalte committen oder in Logs und Tests ausgeben.

Datenbank und Migrationen

• Schemaänderungen ausschließlich als neues, fortlaufend nummeriertes Paar aus .up.sql und .down.sql in internal/storage/postgres/migrations hinzufügen.
• Bereits eingecheckte Migrationen nicht nachträglich ändern, außer der Benutzer fordert dies ausdrücklich und die Migration wurde nachweislich noch nirgends angewendet.
• Migrationen müssen auf einer leeren Datenbank vorwärts laufen. Die Down-Migration muss die Änderung soweit sinnvoll und sicher rückgängig machen.
• SQL parametrieren, Transaktionsgrenzen bewusst wählen und konkurrierende Zugriffe berücksichtigen.
• Neue oder geänderte Abfragen durch PostgreSQL-Integrationstests abdecken, wenn Verhalten nicht sinnvoll mit einem Unit-Test geprüft werden kann.

Tests

• Jede Verhaltensänderung erhält passende Tests, sofern technisch möglich. Fehler- und Berechtigungspfade gehören ebenso dazu wie der Erfolgsfall.

• Fehlerbehebungen möglichst zuerst mit einem Regressionstest reproduzieren.

• Tests nahe am getesteten Paket ablegen und vorhandene Testhelfer wiederverwenden. Tabellengetriebene Tests nutzen, wenn mehrere gleichartige Fälle dadurch klarer werden.

• Tests müssen deterministisch und voneinander unabhängig sein. Keine echten Netzwerkdienste, Uhrzeit oder Zufallswerte unkontrolliert voraussetzen.

• Bestehende Tests nicht löschen, abschwächen oder überspringen, nur um einen Build grün zu bekommen.

• Zuerst die direkt betroffenen Pakete testen, anschließend standardmäßig:

  go test ./...
  

• Vor Abschluss einer größeren oder sicherheitsrelevanten Änderung zusätzlich ausführen:

  make audit
  

• PostgreSQL-Integrationstests nur mit einer ausdrücklich dafür vorgesehenen Datenbank ausführen:

  GARDOMATIC_TEST_DB_DSN="$TEST_DATABASE_URL" go test -count=1 ./internal/storage/postgres
  

  make test/integration migriert die in GARDOMATIC_DB_DSN konfigurierte Datenbank. Niemals versehentlich gegen Produktion ausführen.

Dokumentation und Abschluss

• README, Konfigurationsbeispiele und weiterführende Dokumentation aktualisieren, wenn sich Setup, Befehle, Umgebungsvariablen oder Nutzerverhalten ändern.
• Für Beiträge Dritter gelten CONTRIBUTING.md und CLA.md. Die CLA-Checkbox oder Zustimmung niemals stellvertretend für eine beitragende Person setzen.
• Den CLA-Workflow nicht umgehen, abschwächen oder auf einen grünen Status setzen, wenn die nachweisbare Zustimmung der beitragenden Person fehlt.
• Kein Fremdmaterial übernehmen, dessen Herkunft, Lizenz oder Vereinbarkeit mit der Projektlizenz und der CLA unklar ist.
• Rechtstexte (LICENSE und CLA.md) nur auf ausdrücklichen Auftrag ändern.
• Vor der Übergabe den Diff auf unnötige Änderungen, Duplikationen, Geheimnisse und fehlende Tests prüfen.
• In der Übergabe geänderte Bereiche, ausgeführte Prüfungen und verbleibende Risiken knapp nennen. Übersprungene Prüfungen mit Grund aufführen.