KantSites/AGENTS.md

Projektregeln – Eigenes CMS

Ziel und Kontext

Entwickle für Umut ein selbst betreibbares CMS für Kundenwebsites. Der visuelle Editor soll das vertraute Bedienprinzip des Flatsome UX Builders aufgreifen. Prioritäten: gutes Bearbeiten, schnelle öffentliche Ausgabe, integriertes SEO, zugängliche Inhalte für KI-Systeme, Templates, Plugins und zuverlässiger Betrieb.

Der Entwicklungsplan steht in ENTWICKLUNGSPLAN.md. Produktname und Stack sind noch nicht festgelegt. Diese Datei ist eine vorbereitete Projektanweisung; sie gehört beim Einrichten in den Repository-Stamm.

Vorrangige Qualitätsziele

• Leistung, Barrierefreiheit, Best Practices, SEO und agentisches Browsing haben ab dem ersten Prototyp höchste Priorität. Details und Messbedingungen stehen im Entwicklungsplan.
• Öffentliche Referenzseiten: Lighthouse-Leistung mindestens 95 mobil und Desktop, 100 anstreben; Barrierefreiheit, Best Practices und SEO jeweils 100 als automatische Testziele. Alle anwendbaren Agentic-Browsing-Prüfungen der dokumentierten Toolversion bestehen.
• Reale Inhalte, Produktionsbuild und reproduzierbare Messbedingungen verwenden. Keine Scores für beliebige Kundenseiten garantieren und keine leeren Demos als Leistungsnachweis verwenden.
• Manuelle Barrierefreiheits- und Bedienprüfungen ergänzen automatische Audits. Agentisches Browsing und GEO getrennt überprüfen.
• Core Web Vitals: LCP <= 2,5 s, INP <= 200 ms, CLS <= 0,1 am 75. Perzentil als Feldziele. Fehlende Felddaten nicht als bestanden markieren; INP nicht aus einem normalen Lighthouse-Ladelauf ableiten.
• Änderungen an Templates, Blöcken und Plugins dürfen diese Grundlagen nicht unbemerkt verschlechtern. Qualitätsprüfungen beginnen mit der ersten ausführbaren öffentlichen Seite, nicht erst in Phase 5.

Vor jeder Aufgabe

• Lies ENTWICKLUNGSPLAN.md und, sobald vorhanden, docs/STATUS.md sowie relevante Entscheidungen in docs/ARCHITECTURE.md.
• Prüfe den tatsächlichen Repositoryzustand; erfinde keine vorhandenen Dateien, Startbefehle oder Testergebnisse.
• Wähle den nächsten umsetzbaren Schritt im beauftragten Umfang und führe ihn bis zu einem prüfbaren Ergebnis durch.
• Benenne nur solche offenen Fragen als Blocker, deren Antwort die konkrete Umsetzung wesentlich verändert.

Architektur

• Öffentliche Seiten liefern den Hauptinhalt im HTML. Editorcode gehört nicht in das öffentliche Standardpaket.
• Inhalte als validierten, versionierten Blockbaum mit stabilen IDs speichern; keine neuen proprietären Shortcodes als Datenbasis.
• Inhalte, Layout und Designwerte getrennt halten. Vorschau und Veröffentlichung nutzen gemeinsame Blockverträge.
• Änderungen am Dokumentschema, an Plugin-APIs oder Datenbankstrukturen benötigen einen dokumentierten Migrationsweg.
• Entwürfe und veröffentlichte Inhalte trennen. Veraltete Schreibzugriffe erkennen; Fehler nicht durch stilles Überschreiben verdecken.
• Plugins über definierte Schnittstellen anbinden. Serverseitigen Erweiterungscode nicht ohne implementierte Isolation als sandboxed bezeichnen.
• Für Authentifizierung und andere Standardfunktionen gepflegte Bibliotheken verwenden; Frameworkwahl in Phase 0 begründen.

Editor und Qualität

• Tastaturbedienung, responsive Verhalten, Undo/Redo, Speicherstatus und Fehlerzustände bei den betroffenen Funktionen mitliefern.
• Tests auf konkrete Risiken ausrichten: Speichern/Laden, Undo/Redo, Berechtigungen, Migrationen und Cacheerneuerung nach Publizieren.
• Visuelle Änderungen in einer Browser-Vorschau prüfen, sobald eine ausführbare Anwendung existiert.
• Nur tatsächlich ausgeführte Prüfungen als bestanden melden. Fehlende Zugriffe oder nicht ausführbare Prüfungen klar festhalten.
• Keine garantierten SEO-Rankings oder KI-Zitierungen versprechen.

Zusammenarbeit und Übergabe

• Mit Umut auf Deutsch, klar und direkt kommunizieren.
• Bestehende Nutzeränderungen erhalten. Geheimnisse nicht in Code oder Dokumentation eintragen.
• Den beauftragten Umfang selbstständig abschließen; neue externe Veröffentlichungen und irreversible Änderungen anhand des konkreten Nutzerauftrags behandeln.
• Nach einem abgeschlossenen Arbeitsschritt docs/STATUS.md aktualisieren: erledigt, geprüft, bekannte Fehler, nächster Schritt.
• Bedeutende Entscheidungen mit Gründen und Folgen in docs/ARCHITECTURE.md festhalten.
• Beim initialen Setup diese beiden Dokumente anlegen und reale Start-, Build- und Prüfkommandos in README.md dokumentieren.
• Projektgedächtnis in Dateien pflegen; kein automatisches vollständiges Erinnern über neue Chats hinweg voraussetzen.