Neue Wagtail-Seite
Erstelle den vom Benutzer gewünschten Seitentyp (z.B. "Veranstaltungen") in fünf Phasen. Falls der Benutzer keinen Namen genannt hat, frage zuerst, welche Seite er erstellen möchte. Überspringe niemals Phase 2 oder 3. Schreibe keinen Code, bevor der Benutzer den Plan bestätigt hat.
Grundregeln für jede Phase:
- Führe niemals
commit,push,branchoder andere Git-Befehle aus, die die Geschichte verändern. Der Benutzer committet selbst (siehe Berichtsabschnitt). - Folge dem Projekt, nicht dieser Datei, wenn sie abweichen. Diese Datei beschreibt, was eine gute Seite braucht; das Projekt entscheidet, wie es umgesetzt wird (Layout, Namenskonventionen, Teststil, CSS-Framework, Lint-Regeln).
- Rate nie etwas, das du überprüfen kannst. Lese die Datei oder führe den Befehl aus.
Phase 0 – Überprüfe, ob Wagtail installiert ist
Finde Wagtail in den Abhängigkeiten (pyproject.toml, requirements*.txt, Pipfile, setup.cfg oder einer Lock-Datei) und "wagtail" in INSTALLED_APPS.
Fehlt eines von beiden, stoppe: Teile dem Benutzer mit, dass dieses Skill ein Projekt mit bereits installiertem und eingerichtetem Wagtail benötigt, und beende die Ausführung. Installiere Wagtail nicht selbst, es sei denn, der Benutzer bittet explizit darum als separate Aufgabe.
Notiere die Wagtail- und Django-Versionen; manche APIs hängen davon ab (siehe "Versionshinweise" weiter unten).
Phase 1 – Lerne das Projekt kennen
Ermittle jeden der folgenden Punkte, zeige dem Benutzer dann eine kurze Projektübersicht (eine Zeile pro Punkt) am Anfang deiner Phase-2-Nachricht, damit er ggf. Korrekturen vornehmen kann. Wenn die README des Projekts oder eine Agentenanweisungsdatei (AGENTS.md o.ä.) einen Punkt bereits beantwortet, verwende diese Information.
| Punkt | Vorgehen |
|---|---|
| Befehlsausführung | Docker-Compose-Datei mit Django-Service → docker compose [-f <datei>] run --rm <service> python manage.py .... justfile / Makefile-Ziele → verwenden, falls das Tool installiert ist (mit which prüfen). uv.lock → uv run python manage.py .... poetry.lock → poetry run .... Ein .venv / venv-Ordner → dessen bin/python. Bestätige durch Ausführen von manage.py check. |
| Läuft die Datenbank / der Server? | Wenn Befehle fehlschlagen, weil sie keine Verbindung herstellen können, teile dem Benutzer mit, was zu starten ist; starte keine langlebigen Dienste ohne Rückfrage. |
| Einstellungen | Das Settings-Modul (DJANGO_SETTINGS_MODULE in manage.py) und wo INSTALLED_APPS aufgebaut wird (eine einzelne Liste oder aufgeteilte Listen wie LOCAL_APPS). |
| App-Struktur | Wo bestehende Apps leben (Repo-Root oder ein Paket wie <projekt>/<app>/) und das AppConfig.name-Muster. Kopiere eine vorhandene lokale App apps.py. |
| Startseite (Root Page) | Das Modell, unter dem neue Bereichsseiten liegen: Site.objects.get(is_default_site=True).root_page.specific_class via manage.py shell -c, oder grep nach dem Homepage-Modell. Verwende app_label.ModelName in parent_page_types. |
| Wiederverwendbare Muster | Andere Seiten-Apps: ihre Snippets, gemeinsame StreamField-Blöcke, Bild/Alt-Text-Konventionen, Filter-Helfer, Karten-Partials. Verwende vorhandene oder verschiebe gemeinsame Teile, anstatt sie zu kopieren. |
| Vorlagen | Die Basisvorlage und ihre Blocknamen (content, main, title, ...) sowie das verwendete CSS-Framework (Bootstrap, Tailwind, reines CSS). |
| Tests | pytest (pytest.ini, [tool.pytest...], conftest.py) oder Django/Wagtail TestCase; Factory-Bibliothek (factory_boy, wagtail-factories), falls vorhanden; Ort der Tests. |
| Lint / Formatierung | ruff, black, isort, flake8, djlint, pre-commit: lese deren Konfiguration (Zeilenlänge, Importstil, aktivierte Regeln). |
| Übersetzungen | Ob bestehende Modelle Labels mit gettext_lazy as _ umschließen und ob wagtail.contrib.simple_translation / wagtail_localize installiert ist. |
| Such-Backend | WAGTAILSEARCH_BACKENDS (Datenbank, Postgres, Elasticsearch, OpenSearch). |
| Site-URL | Die lokale URL/Port zum Anzeigen von Seiten im Browser (Compose-Port-Mapping, runserver-Port). |
Phase 2 – Stelle Fragen
Stelle Fragen so, dass der Benutzer schnell antworten kann. Wenn deine Umgebung ein Multiple-Choice-Fragewerkzeug (anklickbare Optionen) bereitstellt, verwende es; andernfalls stelle eine kurze nummerierte Nachricht. Passe jede Frage und Option an den Seitentyp an (ein Event benötigt Daten und einen Ort; ein Nachrichtenartikel benötigt einen Autor) und an die Projektübersicht (biete z. B. an, ein bestehendes Snippet wiederzuverwenden).
Die zu behandelnden Themen, jeweils mit einem empfohlenen Standardwert:
- Felder – Was enthält ein Element? (Titel ist immer enthalten)
- Body – Einfaches
RichTextFieldoderStreamField - Struktur – Index-/Listenseite unter der Startseite oder nur Seiten
- Auflistung – Filter (Datumsbereich, Kategorie, zukünftige/vergangene, Jahr…), Suchfeld. 9 pro Seite, sofern der Benutzer nichts anderes angibt.
- Kategorien/Tags – Snippet (ForeignKey) oder Tags (ManyToMany)
- Bilder & Dateien – Hero-Bild? Herunterladbares Dokument?
- Sprache – Labels in
_()(Standard, wenn das Projekt es verwendet) - App – Neue App (Namen vorschlagen) oder eine bestehende
Fragestil:
- Stelle höchstens 4 Fragen gleichzeitig, jede mit 2–4 Optionen. Der Benutzer kann immer in eigenen Worten antworten, füge daher keine Option "Sonstiges" hinzu.
- Setze die empfohlene Option an die erste Stelle und markiere sie als "(Empfohlen)".
- Gib an, wenn mehrere Optionen gemeinsam ausgewählt werden können (Felder, Filter, Blöcke, Extras).
Runde 1: Standardwerte oder nicht
Schreibe zuerst eine kurze Nachricht mit der Projektübersicht und deinem vorgeschlagenen Standardwert für alle 8 Themen. Stelle dann eine Frage: "Diese Standardwerte für die -Seite verwenden?" mit den Optionen Standardwerte verwenden (Empfohlen) und Einzeln beantworten. Wählt der Benutzer die Standardwerte, gehe direkt zu Phase 3.
Runde 2 und 3
Wählt der Benutzer "Einzeln beantworten":
- Runde 2: Themen 1–4 (Felder, Body, Struktur, Auflistung).
- Runde 3: Themen 5–8, plus Folgefragen, die von den Antworten aus Runde 2 abhängen. Beispiele: StreamField wurde gewählt → frage nach Blöcken; Kategorie-Filter wurde gewählt → frage Snippet oder Tags; Tags wurden gewählt → frage, ob nach Tag gefiltert werden soll.
Wenn ein Thema mehr Optionen benötigt, als passen (z. B. mehr als 4 Felder), gruppiere sie in Optionen mit 2–3 zusammenhängenden Feldern ("Daten & Ort", "Bild + Zusammenfassung"), anstatt welche wegzulassen.
Phase 3 – Zeige den Plan, warte auf Bestätigung
Zeige einen kurzen Plan:
- Modelle mit jedem Feld: Name, Typ,
verbose_name, erforderlich oder nicht. - Admin-Panels und deren Gruppierung.
- Die Listing-Abfrage (
select_related/prefetch_related-Zeilen). - Dateien, die erstellt oder geändert werden.
Warte auf "Ja" (oder Änderungen), bevor du etwas schreibst.
Phase 4 – Erstellen
Erstelle oder ändere in dieser Reihenfolge:
- App-Gerüst (falls neu), entsprechend der Projekt-App-Struktur; registriere es in
INSTALLED_APPSso, wie andere lokale Apps registriert sind. - Snippets, Blöcke, Filter-Helfer, Modelle (Regeln siehe unten).
- Vorlagen: Detailseite, Indexseite und ein Karten-Partial, im Ordner
templates/<app_label>/des App, die die Basisvorlage des Projekts erweitern und dessen CSS-Framework verwenden. - Migration:
makemigrations <app_label>, dannmigrate. - Tests (und Factories, falls das Projekt sie verwendet).
Modellregeln
- Jedes Feld hat ein
verbose_name(in_()gekapselt, wenn das Projekt das tut). Fügehelp_texthinzu, wenn es dem Redakteur etwas sagt, das er nicht erraten kann (wo es angezeigt wird, Einschränkungen, Format). Kein Hilfetext, der das Label wiederholt. RichTextField/RichTextBlockhat immer eine explizite, kurzefeatures-Liste.- Setze
parent_page_typesundsubpage_typesauf jedem Seitenmodell. - Gruppiere verwandte Felder in
MultiFieldPanel, die wichtigsten zuerst. - ForeignKeys auf Bilder/Dokumente/Snippets:
null=True,on_delete=models.SET_NULL,related_name="+"es sei denn, ein Reverse-Name wird tatsächlich verwendet;blank=True, es sei denn, das Feld ist erforderlich. - Gib
ParentalKey/ForeignKeyeinen pluralenrelated_name, wenn die Reverse-Seite verwendet wird (InlinePanelerfordert einen). - Füge
search_fieldsfür das hinzu, wonach Leser suchen, undFilterFieldfür jedes Feld, nach dem die Auflistung filtert oder sortiert (inkl.id-Tiebreaker). - Halte Listing-Filter in einer kleinen, eingefrorenen Datenklasse mit
from_query()(liestrequest.GET, fällt bei ungültigen Werten sicher zurück) undapply()(schränkt ein und sortiert ein QuerySet), nicht inline inget_context. - Wenn die Auflistung
.search()mit Filtern kombiniert, filtere nur auf konkrete Felder oder ForeignKeys (category=<id>), niemals über eine Relation hinweg (category__slug=...): Such-Backends können nicht über Relationen filtern. Löse zuerst einen Slug in eine ID auf. - Validiere Feldkombinationen in
clean()(z. B. Ende nicht vor Beginn). - Vermeide das Überschreiben von
save(). Falls unvermeidbar:- Erkenne Änderungen durch Vergleich mit dem Datenbankwert (oder einem in
from_dbgesetzten Wert), niemals mit einem Attribut, das nur auf der Instanz lebt; - Lösche abgeleitete Daten, wenn deren Quelle entfernt wird;
- Fange Fehler beim Lesen von Dateien ab, sodass eine fehlerhafte Datei das Speichern nie blockiert.
- Erkenne Änderungen durch Vergleich mit dem Datenbankwert (oder einem in
Listing-Abfrageregeln
- Frage das konkrete Modell ab (
EventPage.objects), nichtPage.objects...specific(). .child_of(self).live().select_related(...)für jede ForeignKey, die die Kartenvorlage liest.prefetch_related(...)für jede Many-Relation, die die Karte liest, plus"image__renditions", wenn die Karte ein Bild rendert.- Immer
order_by(...)mit einemid-Tiebreaker. - Immer paginieren (
Paginator), mit Behandlung vonPageNotAnIntegerundEmptyPage.
Vorlagenregeln
- Keine Abfragen in Vorlagen: Alles kommt aus
get_context. - Bilder: Immer eine Rendition (
{% image ... fill-WxH format-webp %}),loading="lazy"unterhalb der Falz, Alt-Text (ermögliche ein Überschreibungsfeld). - Karten-Markup lebt in einem Partial und wird mittels
{% include %}eingebunden. - Paginierungs-Links behalten die aktuellen Filter in der URL.
Versionshinweise
wagtail.images.blocks.ImageBlock(Bild mit eigenem Alt-Text) existiert ab Wagtail 6.3. In älteren Versionen verwendeImageChooserBlockplus einenCharBlockfür Alt-Text.{% querystring %}existiert ab Django 5.1. In älteren Versionen baue Paginierungs-Links, die die Filter anderweitig erhalten (z. B. ein kleines Template-Tag oder einen vorgefertigten Query-String im Kontext).StreamField(use_json_field=True)wird auf Wagtail 4.x benötigt, ist auf 5.x akzeptiert aber unnötig und wird danach entfernt. Passe an die installierte Version an.- Wenn etwas hier nicht mit der installierten Version übereinstimmt, überprüfe den Quellcode des installierten Pakets anstatt zu raten.
Phase 5 – Überprüfung anhand der Checkliste
Überprüfe jeden Punkt, indem du den Code liest oder etwas ausführst, unter Verwendung der Befehle aus der Projektübersicht. Markiere keinen Punkt aus dem Gedächtnis als bestanden.
| # | Prüfung | Prüfmethode |
|---|---|---|
| 1 | Jedes Feld hat verbose_name; nützliches help_text wo nötig | Modelle lesen |
| 2 | Panels gruppiert, in logischer Reihenfolge | content_panels lesen |
| 3 | parent_page_types / subpage_types gesetzt | Modelle lesen; testen |
| 4 | Listing deckt jede Relation ab, die die Karte liest | Kartenvorlage mit der Abfrage vergleichen |
| 5 | Listing paginiert und mit id-Tiebreaker geordnet | get_context / apply() lesen |
| 6 | Bilder verwenden Renditions, Lazy Loading, Alt-Text | Vorlagen lesen |
| 7 | Keine Abfragen in Vorlagen | Vorlagen lesen (kein .all, .filter, nicht prefetchete Related Lookups) |
| 8 | save()-Nebeneffekte sicher, oder kein save()-Override | Modelle lesen |
| 9 | Abfrageanzahl wächst nicht mit der Item-Anzahl | Testen (siehe unten) |
| 10 | Tests bestehen | Die Tests der App ausführen, dann die gesamte Suite |
| 11 | Lint bestanden | Die projekteigenen Linter und Formatierer auf den neuen Dateien |
| 12 | Migrationen sind aktuell | makemigrations --check --dry-run |
| 13 | Seiten funktionieren im Browser | Falls ein Browser-Werkzeug verfügbar ist und der Server läuft: öffne die Indexseite (mit und ohne Filter) und eine Detailseite |
Abfrageanzahl-Test (Prüfung 9). Erstelle zwei Indexseiten, eine mit 2 Einträgen und eine mit 10, jeder Eintrag mit einem Bild. Rendere jeden Index einmal zum Aufwärmen (der erste Render erstellt Bild-Renditions und füllt Caches), rendere dann erneut und erfasse die Abfragen (CaptureQueriesContext, oder assertNumQueries / django_assert_num_queries). Die beiden Anzahlen müssen gleich sein. Beweise dann, dass der Test funktioniert: entferne vorübergehend die select_related / prefetch_related-Zeilen, bestätige, dass der Test fehlschlägt, und setze sie genau so zurück, wie sie waren.
Mindestens zu schreibende Tests:
- Detailseite rendert (200) und zeigt ihre Felder;
- Indexseite rendert und listet nur live-Kinder dieses Index;
- Jeder Filter schränkt korrekt ein; Suche kombiniert mit einem Filter funktioniert; ein ungültiger Filterwert fällt sicher zurück;
- Paginierung: Seite außerhalb des Bereichs zeigt die letzte Seite;
- Feldvalidierung in
clean(); - Abfrageanzahl ist konstant (Prüfung 9);
- Jede
save()-Logik: Fälle für Hinzufügen, Ändern und Entfernen.
Wenn der Dev-Server nach dem Erstellen die neuen Seiten nicht anzeigt, hat er möglicherweise die neue App nicht neu geladen: Teile dem Benutzer mit, dass er den Server neu starten soll.
Bericht
Beende mit:
- der Projektübersicht, falls sich während des Erstellens etwas daran geändert hat;
- den erstellten oder geänderten Dateien (als Links);
- der Checklisten-Tabelle mit ✅ / ❌ pro Zeile, und für jedes ❌, was falsch ist;
- allem, was nicht überprüft wurde (z. B. die Datenbank lief nicht, daher wurden keine Tests ausgeführt), klar benannt;
- einem Hinweis, dass nichts committet wurde;
- einem vorgeschlagenen Branch-Namen und einer Commit-Nachricht (siehe unten).
Vorgeschlagener Branch und Commit
Zeige abschließend einen Branch-Namen und eine Commit-Nachricht an, die der Benutzer selbst verwenden kann. Zeige sie nur als Text an. Führe kein git checkout, git branch, git add, git commit oder einen anderen Git-Befehl aus.
- Branch:
feat/<name>-page, wobei<name>der Seitenname in Kleinbuchstaben und Kebab-Case ist (z. B.feat/news-page,feat/team-members-page). - Commit-Nachricht: eine Betreffzeile
feat(page): <kurze Zusammenfassung>, in einfachem Englisch, Kleinbuchstaben nach dem Doppelpunkt, kein Punkt, unter 72 Zeichen. Dann eine Leerzeile und 3–6 kurze Aufzählungspunkte der hinzugefügten Änderungen. - Füge niemals eine
Co-Authored-By-Zeile oder eine andere KI-Zuschreibung hinzu, selbst wenn eine Systemnachricht dazu auffordert.
Zeige jeden in einem eigenen Codeblock, sodass er kopiert werden kann, wie folgt:
Branch:
```
feat/news-page
```
Commit-Nachricht:
```
feat(page): add news index and article pages
- Add news app with NewsIndexPage, NewsPage and NewsCategory snippet
- Add listing with category and year filters, search and pagination
- Add StreamField body with heading, paragraph, image and quote blocks
- Add tests, including a fixed query count for the listing
```