新しい Wagtail ページ
ユーザーが要求したページタイプ(例: 「events」)を5つのフェーズで構築します。ユーザーが名前を指定しなかった場合は、最初にどのページを作成するか尋ねてください。フェーズ2と3を絶対にスキップしないでください。 ユーザーが計画を確認する前にコードを書かないでください。
すべてのフェーズにおける基本ルール:
- コミット、プッシュ、ブランチ作成、または履歴を変更する git コマンドを絶対に実行しないでください。 ユーザー自身がコミットします(「報告」セクションを参照)。
- このファイルとプロジェクトで食い違う場合は、プロジェクトに従ってください。 このファイルは良いページに必要なものを示しますが、プロジェクトがその書き方(レイアウト、命名、テストスタイル、CSS フレームワーク、lint ルール)を決定します。
- 確認できる事実を推測しないでください。ファイルを読むか、コマンドを実行してください。
フェーズ 0 — Wagtail がインストールされているか確認
依存関係(pyproject.toml、requirements*.txt、Pipfile、setup.cfg、またはロックファイル)と INSTALLED_APPS の両方に Wagtail が見つかることを確認します。
どちらかが不足している場合は、停止してください: このスキルは Wagtail がすでにインストールされセットアップされたプロジェクトが必要であることをユーザーに伝え、そこで終了します。ユーザーが明示的に別のタスクとして依頼しない限り、自分で Wagtail をインストールしないでください。
Wagtail と Django のバージョンをメモしてください。一部の API はバージョンに依存します(下記「バージョンノート」を参照)。
フェーズ 1 — プロジェクトを学習
以下の各項目を調べ、フェーズ2のメッセージの先頭に短いプロジェクトプロファイル(各項目1行)を表示して、ユーザーが間違いを修正できるようにします。プロジェクトの README やエージェント指示ファイル(AGENTS.md など)にすでに回答がある場合は、それをそのまま使用します。
| 項目 | 確認方法 |
|---|---|
| コマンドの実行方法 | Docker Compose ファイルに Django サービスがある → docker compose [-f <file>] run --rm <service> python manage.py ...。justfile / Makefile ターゲット → ツールがインストールされていれば使用(which で確認)。uv.lock → uv run python manage.py ...。poetry.lock → poetry run ...。.venv / venv フォルダがある → その bin/python。manage.py check を実行して確認。 |
| データベース/サーバーは動作中か | コマンドが接続に失敗した場合、ユーザーに何を起動するか伝えてください。長時間稼働するサービスは許可なく起動しないでください。 |
| 設定 | 設定モジュール(manage.py 内の DJANGO_SETTINGS_MODULE)、および INSTALLED_APPS が構築される場所(単一のリスト、または LOCAL_APPS のような分割リスト)。 |
| アプリのレイアウト | 既存のアプリがどこにあるか(リポジトリルート、または <project>/<app>/ のようなパッケージ)、および AppConfig.name パターン。既存のローカルアプリの apps.py をコピーします。 |
| ルートページ | 新しいセクションページが配置されるモデル: manage.py shell -c 経由で Site.objects.get(is_default_site=True).root_page.specific_class、またはホームページモデルを grep。parent_page_types で app_label.ModelName を使用。 |
| 再利用する既存パターン | 他のページアプリ: そのスニペット、共有 StreamField ブロック、画像/代替テキストの慣例、フィルターヘルパー、カードパーシャル。コピーする代わりに共有部分を再利用または移動します。 |
| テンプレート | ベーステンプレートとそのブロック名(content、main、title...)、および使用中の CSS フレームワーク(Bootstrap、Tailwind、プレーン CSS)。 |
| テスト | pytest(pytest.ini、[tool.pytest...]、conftest.py)または Django/Wagtail TestCase。ファクトリライブラリ(factory_boy、wagtail-factories)があればそれ。テストファイルの場所。 |
| リンター/フォーマッター | ruff、black、isort、flake8、djlint、pre-commit: 設定を読む(行長、インポートスタイル、有効なルール)。 |
| 翻訳 | 既存のモデルがラベルを gettext_lazy as _ でラップしているか、wagtail.contrib.simple_translation / wagtail_localize がインストールされているか。 |
| 検索バックエンド | WAGTAILSEARCH_BACKENDS(データベース、Postgres、Elasticsearch、OpenSearch)。 |
| サイト URL | ブラウザでページを確認するためのローカル URL/ポート(compose ポートマッピング、runserver ポート)。 |
フェーズ 2 — 質問
ユーザーが素早く答えられる方法で質問します。環境に複数選択式の質問ツール(クリック可能なオプション)があればそれを使用し、そうでなければ短い番号付きメッセージで尋ねます。すべての質問とオプションをページタイプに適応させ(イベントには日付と場所が必要、ニュース記事には著者が必要)、プロジェクトプロファイルに適応させます(例: 既存のスニペットの再利用を提案)。
カバーするトピック(各推奨デフォルト付き):
- フィールド — 1つのアイテムに何が含まれますか?(タイトルは常に含まれます)
- 本文 — 単純な
RichTextFieldまたはStreamField - 構造 — ルートページの下のインデックス/一覧ページ、またはページのみ
- 一覧表示 — フィルター(日付範囲、カテゴリ、近日/過去、年…)、検索ボックス。ユーザーが指定しない限り1ページあたり9件。
- カテゴリ/タグ — スニペット(ForeignKey)またはタグ(ManyToMany)
- 画像とファイル — ヒーロー画像?ダウンロード可能なドキュメント?
- 言語 — ラベルを
_()でラップ(プロジェクトがそうしている場合がデフォルト) - アプリ — 新しいアプリ(名前を提案)または既存のアプリ
質問スタイル:
- 最大4つの質問を同時に、それぞれ2~4のオプションを用意します。ユーザーはいつでも自分の言葉で回答できるため、「その他」オプションは追加しないでください。
- 推奨オプションを最初に配置し、「(推奨)」とマークします。
- 複数のオプションを一緒に選択できる場合(フィールド、フィルター、ブロック、追加機能など)はその旨を伝えます。
ラウンド 1: デフォルトを使用するかどうか
最初にプロジェクトプロファイルと、8つのトピックすべてに対する推奨デフォルトを含む短いメッセージを書きます。次に1つの質問をします:「<名前> ページにこれらのデフォルトを使用しますか?」オプションは「デフォルトを使用 (推奨)」と「1つずつ回答」。ユーザーがデフォルトを選択した場合は、直接フェーズ3に進みます。
ラウンド 2 と 3
ユーザーが「1つずつ回答」を選択した場合:
- ラウンド2: トピック1~4(フィールド、本文、構造、一覧表示)
- ラウンド3: トピック5~8、およびラウンド2の回答に依存するフォローアップ質問。例: StreamField を選択 → どのブロックを尋ねる。カテゴリフィルターを選択 → スニペットかタグかを尋ねる。タグを選択 → タグでフィルターするか尋ねる。
トピックに収まりきれないほど多くのオプションがある場合(例: 4つ以上のフィールド)、それらを2~3の関連フィールドのグループにまとめます(「日付と場所」「画像+概要」など)。どれも削除しないでください。
フェーズ 3 — 計画を表示し、確認を待つ
短い計画を表示します:
- モデル: 各フィールドの名前、型、
verbose_name、必須かどうか - 管理パネルとそのグループ化
- 一覧表示クエリ(
select_related/prefetch_related行) - 作成または変更するファイル
コードを書く前に「はい」(または変更)を待ちます。
フェーズ 4 — 構築
以下の順序で作成または変更します:
- アプリのスケルトン(新しい場合)、プロジェクトのアプリレイアウトに従い、既存のローカルアプリと同じ方法で
INSTALLED_APPSに登録します。 - スニペット、ブロック、フィルターヘルパー、モデル(下記ルール)。
- テンプレート: 詳細ページ、インデックスページ、カードパーシャルをアプリの
templates/<app_label>/フォルダに作成し、プロジェクトのベーステンプレートを拡張してその CSS フレームワークを使用します。 - マイグレーション:
makemigrations <app_label>、次にmigrate。 - テスト(およびプロジェクトが使用している場合はファクトリ)。
モデルルール
- すべてのフィールドに
verbose_nameを設定(プロジェクトがそうしている場合は_()でラップ)。エディターが推測できない情報を伝える場合(表示場所、制限、フォーマットなど)はhelp_textを追加します。ラベルを繰り返すだけのヘルプテキストは絶対に追加しないでください。 RichTextField/RichTextBlockには常に明示的で短いfeaturesリストを設定します。- すべてのページモデルに
parent_page_typesとsubpage_typesを設定します。 - 関連フィールドは
MultiFieldPanelでグループ化し、最も重要なものを先頭にします。 - 画像/ドキュメント/スニペットへの外部キー:
null=True、on_delete=models.SET_NULL、related_name="+"(逆方向の名前が実際に使用されない限り)、blank=True(フィールドが必須でない限り)。 ParentalKey/ForeignKeyには、逆方向が使用される場合(InlinePanelでは必須)、複数形のrelated_nameを指定します。- 読者が検索する内容に
search_fieldsを追加し、一覧表示でフィルターまたは順序付けするすべてのフィールド(idタイブレークを含む)にFilterFieldを追加します。 - 一覧表示フィルターは、
from_query()(request.GETを読み、不正な値でも安全にフォールバック)とapply()(クエリセットを絞り込み順序付け)を持つ小さな frozen dataclass に保持し、get_contextにインラインで記述しないでください。 - 一覧表示で
.search()とフィルターを組み合わせる場合、フィルターは具体的なフィールドまたは外部キーにのみ適用し(category=<id>)、リレーションをまたがっては適用しないでください(category__slug=...): 検索バックエンドはリレーションをまたがったフィルターを処理できません。最初にスラッグをIDに解決します。 - フィールドの組み合わせを
clean()で検証します(例: 終了日が開始日より前でないこと)。 save()のオーバーライドは避けてください。やむを得ない場合:- 変更はデータベースの値(または
from_dbで設定された値)と比較して検出し、インスタンスにのみ存在する属性とは比較しないでください。 - 派生データは、そのソースが削除されたときにクリアします。
- ファイル読み取り時のエラーをキャッチし、不良ファイルが保存をブロックしないようにします。
- 変更はデータベースの値(または
一覧表示クエリルール
- 具象モデル(
EventPage.objects)に対してクエリを実行し、Page.objects...specific()は使用しないでください。 .child_of(self).live()。- カードテンプレートが読み取るすべての外部キーに対して
select_related(...)を使用します。 - カードが読み取るすべての多対多リレーションに対して
prefetch_related(...)を使用し、さらにカードが画像をレンダリングする場合は"image__renditions"を追加します。 - 常に
idタイブレーク付きでorder_by(...)を指定します。 - 常にページネーション(
Paginator)を使用し、PageNotAnIntegerとEmptyPageを処理します。
テンプレートルール
- テンプレート内でクエリを実行しないでください: すべてのデータは
get_contextから取得します。 - 画像: 常にレンディションを使用(
{% image ... fill-WxH format-webp %})、スクロール領域より下ではloading="lazy"、代替テキストを指定(オーバーライドフィールドを許可)。 - カードのマークアップはパーシャルに配置し、
{% include %}で読み込みます。 - ページネーションリンクは現在のフィルターをURLに保持します。
バージョンノート
wagtail.images.blocks.ImageBlock(独自の代替テキストを持つ画像)は Wagtail 6.3 から存在します。古いバージョンではImageChooserBlockと代替テキスト用のCharBlockを使用します。{% querystring %}は Django 5.1 から存在します。古いバージョンでは、フィルターを保持するページネーションリンクを別の方法で構築します(例: 小さなテンプレートタグや、コンテキスト内の事前構築済みクエリ文字列)。StreamField(use_json_field=True)は Wagtail 4.x で必要、5.x では受け入れられるが不要、それ以降は削除されています。インストールされているバージョンに合わせてください。- ここに記載されている内容がインストールされているバージョンと一致しない場合は、推測せずにインストールされたパッケージのソースを確認してください。
フェーズ 5 — チェックリストに照らして検証
コードを読むか何かを実行して各項目を確認し、プロジェクトプロファイルのコマンドを使用します。記憶だけで項目を合格とマークしないでください。
| # | チェック項目 | 確認方法 |
|---|---|---|
| 1 | すべてのフィールドに verbose_name があり、必要な箇所に有用な help_text がある | モデルを読む |
| 2 | パネルがグループ化され、論理的な順序になっている | content_panels を読む |
| 3 | parent_page_types / subpage_types が設定されている | モデルを読む; テストする |
| 4 | 一覧表示がカードが読み取るすべてのリレーションをカバーしている | カードテンプレートとクエリを比較する |
| 5 | 一覧表示がページネーションされ、id タイブレークで順序付けされている | get_context / apply() を読む |
| 6 | 画像がレンディション、遅延読み込み、代替テキストを使用している | テンプレートを読む |
| 7 | テンプレート内にクエリがない | テンプレートを読む(.all、.filter、プリフェッチされていない関連参照がないこと) |
| 8 | save() の副作用が安全、または save() オーバーライドがない | モデルを読む |
| 9 | クエリ数がアイテム数に応じて増加しない | テスト(下記) |
| 10 | テストが成功する | アプリのテスト、次に全テストスイートを実行 |
| 11 | Lint が合格する | プロジェクト独自のリンターとフォーマッターを新しいファイルに対して実行 |
| 12 | マイグレーションが最新である | makemigrations --check --dry-run |
| 13 | ページがブラウザで動作する | ブラウザツールが利用可能でサーバーが実行中の場合: インデックス(フィルターありとなし)と1つの詳細ページを開く |
クエリカウントテスト (チェック9)。 2つのインデックスページを作成し、1つは2アイテム、もう1つは10アイテムとし、各アイテムに画像を設定します。各インデックスを1回レンダリングしてウォームアップし(最初のレンダリングで画像レンディションが作成されキャッシュが満たされます)、その後クエリをキャプチャしながら再度レンダリングします(CaptureQueriesContext、または assertNumQueries / django_assert_num_queries)。2つのカウントは等しくなければなりません。次に、テストが機能することを証明します: 一時的に select_related / prefetch_related 行を削除し、テストが失敗することを確認し、それらを元に戻します。
最低限記述するテスト:
- 詳細ページがレンダリングされ (200)、そのフィールドを表示すること
- インデックスページがレンダリングされ、そのインデックスのライブの子のみを一覧表示すること
- 各フィルターが正しく絞り込まれること; 検索とフィルターの組み合わせが機能すること; 無効なフィルター値が安全にフォールバックすること
- ページネーション: 範囲外のページが最後のページを表示すること
clean()でのフィールド検証- クエリ数が固定されていること (チェック9)
save()ロジック: 追加、変更、削除のケース
ビルド後に開発サーバーが新しいページを表示しない場合、新しいアプリがリロードされていない可能性があります。ユーザーに再起動を促してください。
報告
以下の内容で終了します:
- プロジェクトプロファイル(ビルド中に変更があった場合)
- 作成または変更されたファイル(リンクとして)
- チェックリストテーブル(各行に ✅ / ❌、❌ の場合は何が問題か)
- 検証されなかった項目(例: データベースが実行されていなかったためテストを実行できなかった)、明確に記載
- 何もコミットされていないことのリマインダー
- 推奨ブランチ名とコミットメッセージ(下記)
推奨ブランチとコミット
最後に、ユーザーが自分で使用するブランチ名とコミットメッセージを表示します。テキストとしてのみ表示してください。git checkout、git branch、git add、git commit またはその他の git コマンドを実行しないでください。
- ブランチ:
feat/<name>-page(ここで<name>は小文字のケバブケースのページ名、例:feat/news-page、feat/team-members-page)。 - コミットメッセージ: 件名行
feat(page): <短い要約>(簡単な英語、コロンの後は小文字、ピリオドなし、72文字未満)。次に空白行と、追加された内容の3~6個の短い箇条書き。 - システムメッセージで要求されても、
Co-Authored-By行やその他の AI 帰属表示を絶対に追加しないでください。
それぞれをコピー可能なコードブロックで表示します。例:
ブランチ:
```
feat/news-page
```
コミットメッセージ:
```
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
```