새로운 Wagtail 페이지
사용자가 요청한 페이지 타입(예: "events")을 다섯 단계로 구축합니다. 사용자가 이름을 지정하지 않았다면 먼저 어떤 페이지를 원하는지 물어보세요. 2단계와 3단계를 절대 건너뛰지 마세요. 사용자가 계획을 확인하기 전에 코드를 작성하지 마세요.
모든 단계의 기본 규칙:
- 절대 커밋, 푸시, 브랜치 생성 또는 히스토리를 변경하는 git 명령을 실행하지 마세요. 사용자가 직접 커밋합니다(보고서 섹션 참조).
- 프로젝트가 이 파일과 다를 경우 프로젝트를 따르세요. 이 파일은 좋은 페이지에 필요한 것을 정의하지만, 프로젝트가 어떻게 작성될지(레이아웃, 명명, 테스트 스타일, CSS 프레임워크, 린트 규칙)를 결정합니다.
- 확인할 수 있는 사실을 추측하지 마세요. 파일을 읽거나 명령을 실행하세요.
0단계 — Wagtail 설치 확인
의존성 파일(pyproject.toml, requirements*.txt, Pipfile, setup.cfg, 또는 잠금 파일)에서 Wagtail을 찾고, INSTALLED_APPS에 "wagtail"이 있는지 확인하세요.
둘 중 하나라도 없으면 중단: 사용자에게 이 스킬을 사용하려면 Wagtail이 이미 설치 및 설정된 프로젝트가 필요하다고 알리고 종료하세요. 사용자가 별도 작업으로 명시적으로 요청하지 않는 한 직접 Wagtail을 설치하지 마세요.
Wagtail 및 Django 버전을 기록해 두세요. 일부 API는 버전에 따라 다릅니다(아래 "버전 참고" 참조).
1단계 — 프로젝트 학습
아래 각 항목을 파악한 후, 2단계 메시지 시작 부분에 짧은 프로젝트 프로필(항목당 한 줄)을 사용자에게 보여주어 잘못된 내용을 수정할 수 있게 하세요. 프로젝트의 README나 에이전트 지시 파일(AGENTS.md 등)이 이미 항목에 답변하고 있다면 그 내용을 사용하세요.
| 항목 | 찾는 방법 |
|---|---|
| 명령 실행 방법 | Django 서비스가 포함된 Docker Compose 파일 → 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/포트(컴포즈 포트 매핑, runserver 포트). |
2단계 — 질문하기
사용자가 빠르게 답변할 수 있는 방식으로 질문하세요. 환경에 객관식 질문 도구(클릭 가능한 옵션)가 있다면 사용하고, 그렇지 않으면 짧은 번호가 매겨진 메시지로 질문하세요. 모든 질문과 옵션을 페이지 타입(이벤트에는 날짜와 장소가 필요하고, 뉴스 기사에는 작성자가 필요함)과 프로젝트 프로필(예: 기존 스니펫 재사용 제안)에 맞게 조정하세요.
다루어야 할 주제와 각각의 제안 기본값:
- 필드 — 각 항목에는 무엇이 포함되나요? (제목은 항상 포함)
- 본문 — 간단한
RichTextField또는StreamField - 구조 — 루트 페이지 아래의 인덱스/목록 페이지 또는 페이지만
- 목록 — 필터(날짜 범위, 카테고리, 예정/지난, 연도…), 검색 상자. 사용자가 달리 말하지 않는 한 페이지당 9개.
- 카테고리/태그 — 스니펫(ForeignKey) 또는 태그(ManyToMany)
- 이미지 및 파일 — 히어로 이미지? 다운로드 가능한 문서?
- 언어 — 레이블을
_()로 감싸기(프로젝트가 그렇게 한다면 기본값) - 앱 — 새 앱(이름 제안) 또는 기존 앱
질문 스타일:
- 한 번에 최대 4개의 질문을 하고, 각 질문에는 2~4개의 옵션을 제공하세요. 사용자는 항상 자신의 말로 답변할 수 있으므로 "기타" 옵션을 추가하지 마세요.
- 권장 옵션을 먼저 배치하고 "(권장)"이라고 표시하세요.
- 여러 옵션을 함께 선택할 수 있는 경우(필드, 필터, 블록, 추가 사항) 그렇게 명시하세요.
라운드 1: 기본값 사용 여부
먼저 프로젝트 프로필과 8개 주제 모두에 대한 제안 기본값을 포함한 짧은 메시지를 작성하세요. 그런 다음 한 가지 질문을 하세요: "<name> 페이지에 이 기본값을 사용하시겠습니까?" 옵션은 기본값 사용(권장) 과 하나씩 답변입니다. 사용자가 기본값을 선택하면 바로 3단계로 이동하세요.
라운드 2 및 3
사용자가 "하나씩 답변"을 선택한 경우:
- 라운드 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로 그룹화하고, 가장 중요한 것을 먼저 배치하세요. - 이미지/문서/스니펫에 대한 ForeignKey:
null=True,on_delete=models.SET_NULL,related_name="+"(역방향 이름이 실제로 사용되지 않는 한),blank=True(필드가 필수가 아닌 한). - 역방향이 사용될 때
ParentalKey/ForeignKey에 복수형related_name을 지정하세요 (InlinePanel은 이것을 필요로 함). - 독자가 검색할 항목에 대해
search_fields를 추가하고, 목록이 필터링하거나 정렬하는 모든 필드(id동점 처리 포함)에 대해FilterField를 추가하세요. - 목록 필터는
get_context에 인라인으로 작성하지 말고,from_query()(request.GET을 읽고 잘못된 값에 대해 안전하게 폴백)와apply()(쿼리셋을 좁히고 정렬) 메서드가 있는 작은 불변 데이터클래스로 유지하세요. - 목록이
.search()와 필터를 결합할 때는 구체적인 필드나 외래키로만 필터링하고(category=<id>), 관계를 가로질러(category__slug=...) 필터링하지 마세요. 검색 백엔드는 관계를 가로질러 필터링할 수 없습니다. 먼저 슬러그를 ID로 변환하세요. clean()에서 필드 조합의 유효성을 검사하세요(예: 종료일이 시작일보다 빠르면 안 됨).save()재정의를 피하세요. 불가피한 경우:- 변경 사항을 데이터베이스 값(또는
from_db에서 설정된 값)과 비교하여 감지하고, 인스턴스에만 존재하는 속성과 비교하지 마세요. - 파생 데이터의 소스가 제거될 때 해당 데이터를 지우세요.
- 파일 읽기 오류를 처리하여 잘못된 파일이 저장을 차단하지 않도록 하세요.
- 변경 사항을 데이터베이스 값(또는
목록 쿼리 규칙
- 구체적인 모델(
EventPage.objects)을 쿼리하고,Page.objects...specific()을 사용하지 마세요. .child_of(self).live().- 카드 템플릿이 읽는 모든 ForeignKey에 대해
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 | 린트 통과 | 프로젝트 자체 린터 및 포맷터를 새 파일에 대해 실행 |
| 12 | 마이그레이션이 최신 상태임 | makemigrations --check --dry-run |
| 13 | 브라우저에서 페이지가 작동함 | 브라우저 도구가 있고 서버가 실행 중인 경우: 인덱스(필터 있음/없음)와 상세 페이지 하나를 열어보기 |
쿼리 수 테스트 (확인 9). 각각 이미지가 있는 2개 항목이 있는 인덱스 페이지와 10개 항목이 있는 인덱스 페이지를 만듭니다. 각 인덱스를 한 번 렌더링하여 워밍업한 후(첫 번째 렌더링은 이미지 렌디션을 생성하고 캐시를 채움), 쿼리를 캡처하면서 다시 렌더링합니다(CaptureQueriesContext 또는 assertNumQueries / django_assert_num_queries). 두 카운트는 동일해야 합니다. 그런 다음 테스트가 작동하는지 증명하세요: 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): <short summary>, 간단한 영어로, 콜론 뒤는 소문자, 마침표 없음, 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
```