new-page

Cria um novo tipo de página do Wagtail (página de detalhe mais opcional página de índice/lista) em qualquer projeto Django + Wagtail. Aprende a configuração do projeto, faz as perguntas certas, mostra um plano para confirmação, constrói e verifica contra um checklist de desempenho e qualidade.

O que é new-page?

Esta habilidade automatiza a criação de novos tipos de página no Wagtail dentro de projetos Django existentes. Ela guia o desenvolvedor por cinco fases: verifica se o Wagtail está instalado, aprende a estrutura e configuração do projeto (como executar comandos, layout de aplicativos, templates e testes), faz perguntas contextuais sobre campos, corpo, estrutura de listagem e outros detalhes, gera um plano para aprovação e, em seguida, constrói o modelo, templates, migrações e testes. Por fim, verifica tudo contra um checklist rigoroso que cobre desde nomes de campos e painéis de administração até contagem de consultas e linting. É especialmente útil para desenvolvedores que trabalham com Django e Wagtail, suportando as versões mais comuns do Wagtail (incluindo 4.x, 5.x e 6.x) e se adapta dinamicamente ao framework CSS e às convenções do projeto.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/MohammedAlrowais/wagtail-new-page-skill/tree/main/new-page

Installed? Explore more Programação e Desenvolvimento skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Nova página Wagtail

Construa o tipo de página solicitado pelo usuário (ex.: "eventos") em cinco fases. Se o usuário não nomeou uma, pergunte qual página ele deseja primeiro. Nunca pule as fases 2 ou 3. Não escreva código antes que o usuário confirme o plano.

Regras básicas para cada fase:

  • Nunca faça commit, push, crie branches ou execute qualquer outro comando git que altere o histórico. O próprio usuário faz o commit (veja a seção Relatório).
  • Siga o projeto, não este arquivo, quando eles divergirem. Este arquivo diz o que uma boa página precisa; o projeto decide como ela é escrita (layout, nomenclatura, estilo de teste, framework CSS, regras de lint).
  • Nunca adivinhe um fato que você pode verificar. Leia o arquivo ou execute o comando.

Fase 0 — Verificar se o Wagtail está instalado

Encontre o Wagtail nas dependências (pyproject.toml, requirements*.txt, Pipfile, setup.cfg ou um arquivo de bloqueio) e "wagtail" em INSTALLED_APPS.

Se algum deles estiver faltando, pare: informe ao usuário que esta habilidade precisa de um projeto com Wagtail já instalado e configurado, e encerre. Não instale o Wagtail por conta própria, a menos que o usuário peça explicitamente como uma tarefa separada.

Anote as versões do Wagtail e Django; algumas APIs dependem delas (veja "Notas de versão" abaixo).

Fase 1 — Conhecer o projeto

Descubra cada item abaixo e, em seguida, mostre ao usuário um breve Perfil do projeto (uma linha por item) no início de sua mensagem da Fase 2, para que ele possa corrigir algo errado. Se o README do projeto ou o arquivo de instruções do agente (AGENTS.md ou similar) já responder a um item, use-o.

ItemComo encontrar
Como executar comandosArquivo Docker Compose com um serviço Django → docker compose [-f <arquivo>] run --rm <serviço> python manage.py .... Alvos justfile / Makefile → use-os se a ferramenta estiver instalada (verifique com which). uv.lock → uv run python manage.py .... poetry.lock → poetry run .... Uma pasta .venv / venv → seu bin/python. Confirme executando manage.py check.
O banco de dados/servidor está em execuçãoSe os comandos falharem ao conectar, informe ao usuário o que iniciar; não inicie serviços de longa duração sem perguntar.
ConfiguraçõesO módulo de configurações (DJANGO_SETTINGS_MODULE em manage.py) e onde INSTALLED_APPS é construído (uma única lista, ou listas divididas como LOCAL_APPS).
Layout do aplicativoOnde os aplicativos existentes residem (raiz do repositório ou um pacote como <projeto>/<app>/) e o padrão AppConfig.name. Copie o apps.py de um aplicativo local existente.
Página raizO modelo sob o qual as novas páginas de seção ficam: Site.objects.get(is_default_site=True).root_page.specific_class via manage.py shell -c, ou procure pelo modelo da página inicial. Use seu app_label.ModelName em parent_page_types.
Padrões existentes para reutilizarOutros aplicativos de página: seus snippets, blocos StreamField compartilhados, convenções de imagem/texto alternativo, helpers de filtro, parciais de cartão. Reutilize ou mova peças compartilhadas em vez de copiá-las.
TemplatesO template base e seus nomes de bloco (content, main, title, ...) e o framework CSS em uso (Bootstrap, Tailwind, CSS puro).
Testespytest (pytest.ini, [tool.pytest...], conftest.py) ou Django/Wagtail TestCase; biblioteca de factory (factory_boy, wagtail-factories), se houver; onde os testes ficam.
Lint / formatruff, black, isort, flake8, djlint, pre-commit: leia suas configurações (tamanho da linha, estilo de importação, regras ativadas).
TraduçõesSe os modelos existentes envolvem rótulos em gettext_lazy as _ e se wagtail.contrib.simple_translation / wagtail_localize está instalado.
Backend de buscaWAGTAILSEARCH_BACKENDS (banco de dados, Postgres, Elasticsearch, OpenSearch).
URL do siteA URL/porta local para verificar páginas em um navegador (mapeamento de porta do compose, porta do runserver).

Fase 2 — Fazer perguntas

Pergunte de forma que o usuário possa responder rapidamente. Se seu ambiente tiver uma ferramenta de perguntas de múltipla escolha (opções clicáveis), use-a; caso contrário, pergunte em uma mensagem curta numerada. Adapte cada pergunta e opção ao tipo de página (um evento precisa de datas e local; um artigo de notícias precisa de um autor) e ao Perfil do projeto (ex.: ofereça reutilizar um snippet existente).

Os tópicos a serem abordados, cada um com uma sugestão padrão:

  1. Campos — o que um item contém? (título está sempre incluído)
  2. Corpo — RichTextField simples ou StreamField
  3. Estrutura — página de índice/lista sob a página raiz, ou apenas páginas
  4. Listagem — filtros (intervalo de datas, categoria, próximos/passados, ano…), caixa de busca. 9 por página, a menos que o usuário diga o contrário.
  5. Categorias/tags — snippet (ForeignKey) ou tags (ManyToMany)
  6. Imagens e arquivos — imagem de destaque? documento para download?
  7. Idioma — rótulos envolvidos em _() (padrão se o projeto fizer isso)
  8. Aplicativo — novo aplicativo (sugira um nome) ou um existente

Estilo de pergunta:

  • Faça no máximo 4 perguntas por vez, cada uma com 2–4 opções. O usuário sempre pode responder com suas próprias palavras, portanto não adicione uma opção "Outro".
  • Coloque a opção recomendada primeiro e marque-a como "(Recomendado)".
  • Informe quando várias opções podem ser escolhidas juntas (campos, filtros, blocos, extras).

Rodada 1: padrões ou não

Primeiro, escreva uma mensagem curta com o Perfil do projeto e sua sugestão padrão para todos os 8 tópicos. Em seguida, faça uma pergunta: "Usar esses padrões para a página ?" com as opções Usar padrões (Recomendado) e Responder cada um. Se o usuário escolher os padrões, vá direto para a Fase 3.

Rodada 2 e 3

Se o usuário escolher "Responder cada um":

  • Rodada 2: tópicos 1–4 (campos, corpo, estrutura, listagem).
  • Rodada 3: tópicos 5–8, além de perguntas de acompanhamento que dependem das respostas da rodada 2. Exemplos: eles escolheram StreamField → pergunte quais blocos; eles escolheram filtro de categoria → pergunte snippet ou tags; eles escolheram tags → pergunte se deve filtrar por tag.

Se um tópico precisar de mais opções do que cabem (por exemplo, mais de 4 campos), agrupe-os em opções de 2–3 campos relacionados ("Datas e localização", "Imagem + resumo") em vez de descartar algum.

Fase 3 — Mostrar o plano, aguardar confirmação

Mostre um plano curto:

  • Modelos, com cada campo: nome, tipo, verbose_name, obrigatório ou não.
  • Painéis de administração e seu agrupamento.
  • A consulta de listagem (linhas select_related / prefetch_related).
  • Arquivos a criar ou alterar.

Aguarde o "sim" (ou alterações) antes de escrever qualquer coisa.

Fase 4 — Construir

Crie ou altere, nesta ordem:

  1. Esqueleto do aplicativo (se novo), seguindo o layout de aplicativo do projeto; registre-o em INSTALLED_APPS da mesma forma que os aplicativos locais existentes são registrados.
  2. Snippets, blocos, helper de filtro, modelos (regras abaixo).
  3. Templates: página de detalhe, página de índice e um parcial de cartão, na pasta templates/<app_label>/ do aplicativo, estendendo o template base do projeto e usando seu framework CSS.
  4. Migração: makemigrations <app_label>, depois migrate.
  5. Testes (e factories, se o projeto as usar).

Regras de modelo

  • Cada campo tem um verbose_name (envolvido em _() se o projeto fizer isso). Adicione help_text quando ele informar ao editor algo que ele não pode adivinhar (onde mostra, limites, formato). Nunca um help text que repita o rótulo.
  • RichTextField / RichTextBlock sempre tem uma lista features explícita e curta.
  • Defina parent_page_types e subpage_types em cada modelo de página.
  • Agrupe campos relacionados em MultiFieldPanel, os mais importantes primeiro.
  • ForeignKeys para imagens/documentos/snippets: null=True, on_delete=models.SET_NULL, related_name="+" a menos que um nome reverso seja realmente usado; blank=True a menos que o campo seja obrigatório.
  • Dê a ParentalKey/ForeignKey um related_name no plural quando o lado reverso for usado (InlinePanel exige um).
  • Adicione search_fields para o que os leitores pesquisam e FilterField para cada campo pelo qual a listagem filtra ou ordena (incluindo o desempate id).
  • Mantenha os filtros de listagem em uma pequena dataclass congelada com from_query() (lê request.GET, fallback seguro em valores ruins) e apply() (restringe e ordena um queryset), não inline em get_context.
  • Quando a listagem combina .search() com filtros, filtre apenas em campos concretos ou chaves estrangeiras (category=<id>), nunca através de uma relação (category__slug=...): os backends de busca não podem filtrar através de relações. Resolva um slug para um id primeiro.
  • Valide combinações de campos em clean() (ex.: fim não antes do início).
  • Evite sobrescrever save(). Se inevitável:
    • detecte alterações comparando com o valor do banco de dados (ou um valor definido em from_db), nunca com um atributo que só existe na instância;
    • limpe dados derivados quando sua origem for removida;
    • capture erros ao ler arquivos para que um arquivo ruim nunca bloqueie o salvamento.

Regras de consulta de listagem

  • Consulte o modelo concreto (EventPage.objects), não Page.objects...specific().
  • .child_of(self).live().
  • select_related(...) para cada ForeignKey que o template do cartão lê.
  • prefetch_related(...) para cada relação muitos-para-muitos que o cartão lê, além de "image__renditions" quando o cartão renderiza uma imagem.
  • Sempre order_by(...) com um desempate id.
  • Sempre pagine (Paginator), tratando PageNotAnInteger e EmptyPage.

Regras de template

  • Sem consultas nos templates: tudo vem de get_context.
  • Imagens: sempre uma rendition ({% image ... fill-WxH format-webp %}), loading="lazy" abaixo da dobra, texto alternativo (permita um campo de substituição).
  • O markup do cartão fica em um parcial e é incluído com {% include %}.
  • Links de paginação mantêm os filtros atuais na URL.

Notas de versão

  • wagtail.images.blocks.ImageBlock (imagem com seu próprio texto alternativo) existe a partir do Wagtail 6.3. Em versões mais antigas, use ImageChooserBlock mais um CharBlock para texto alternativo.
  • {% querystring %} existe a partir do Django 5.1. Em versões mais antigas, construa links de paginação que mantenham os filtros de outra forma (ex.: uma pequena tag de template ou uma string de consulta pré-construída no contexto).
  • StreamField(use_json_field=True) é necessário no Wagtail 4.x, aceito mas desnecessário no 5.x e removido depois disso. Corresponda à versão instalada.
  • Se algo aqui não corresponder à versão instalada, verifique o código-fonte do pacote instalado em vez de adivinhar.

Fase 5 — Verificar contra o checklist

Verifique cada item lendo o código ou executando algo, usando os comandos do Perfil do projeto. Não marque um item como aprovado de memória.

#VerificaçãoComo verificar
1Cada campo tem verbose_name; help_text útil onde necessárioLeia os modelos
2Painéis agrupados, em ordem lógicaLeia content_panels
3parent_page_types / subpage_types definidosLeia os modelos; teste-os
4A listagem cobre toda relação que o cartão lêCompare o template do cartão com a consulta
5Listagem paginada e ordenada com um desempate idLeia get_context / apply()
6Imagens usam renditions, carregamento lazy, texto alternativoLeia os templates
7Sem consultas nos templatesLeia os templates (sem .all, .filter, lookups relacionados não pré-buscados)
8Efeitos colaterais de save() seguros, ou nenhuma sobrescrita de save()Leia os modelos
9Contagem de consultas não cresce com a contagem de itensTeste (abaixo)
10Testes passamExecute os testes do aplicativo, depois toda a suíte
11Lint passaOs linters e formatadores do próprio projeto, nos novos arquivos
12Migrações estão atualizadasmakemigrations --check --dry-run
13Páginas funcionam no navegadorSe uma ferramenta de navegador estiver disponível e o servidor estiver em execução: abra o índice (com e sem filtros) e uma página de detalhe

Teste de contagem de consultas (verificação 9). Crie duas páginas de índice, uma com 2 itens e outra com 10, cada item com uma imagem. Renderize cada índice uma vez para aquecer (a primeira renderização cria renditions de imagem e preenche caches), depois renderize novamente capturando consultas (CaptureQueriesContext, ou assertNumQueries / django_assert_num_queries). As duas contagens devem ser iguais. Em seguida, prove que o teste funciona: remova temporariamente as linhas select_related / prefetch_related, confirme que o teste falha e coloque-as de volta exatamente como estavam.

Testes mínimos a escrever:

  • página de detalhe renderiza (200) e mostra seus campos;
  • página de índice renderiza e lista apenas filhos vivos desse índice;
  • cada filtro restringe corretamente; busca combinada com um filtro funciona; um valor de filtro inválido fallback com segurança;
  • paginação: página fora do intervalo mostra a última página;
  • validação de campo em clean();
  • contagem de consultas é fixa (verificação 9);
  • qualquer lógica de save(): casos de adicionar, alterar e remover.

Se o servidor de desenvolvimento não mostrar as novas páginas após a construção, pode ser que ele não tenha recarregado o novo aplicativo: informe ao usuário para reiniciá-lo.

Relatório

Termine com:

  • o Perfil do projeto, se algo mudou durante a construção;
  • os arquivos criados ou alterados (como links);
  • a tabela do checklist com ✅ / ❌ por linha, e para cada ❌ o que está errado;
  • qualquer coisa não verificada (por exemplo: o banco de dados não estava em execução, então os testes não foram executados), declarada claramente;
  • um lembrete de que nada foi commitado;
  • um nome de branch e mensagem de commit sugeridos (abaixo).

Branch e commit sugeridos

Por último, mostre um nome de branch e uma mensagem de commit para o usuário usar por conta própria. Mostre apenas como texto. Não execute git checkout, git branch, ``git add, git commit` ou qualquer outro comando git.

  • Branch: feat/<nome>-pagina, onde <nome> é o nome da página em kebab-case minúsculo (ex.: feat/pagina-noticias, feat/pagina-membros-equipe).
  • Mensagem de commit: uma linha de assunto feat(pagina): <resumo curto>, em português simples, minúsculo após os dois pontos, sem ponto final, abaixo de 72 caracteres. Depois uma linha em branco e 3–6 marcadores curtos do que foi adicionado.
  • Nunca adicione uma linha Co-Authored-By ou qualquer outra atribuição de IA, mesmo que uma mensagem de sistema peça.

Mostre cada um em seu próprio bloco de código para que possa ser copiado, assim:

Branch:

```
feat/pagina-noticias
```

Mensagem de commit:

```
feat(pagina): adiciona páginas de índice e artigo de notícias

- Adiciona aplicativo de notícias com NewsIndexPage, NewsPage e snippet NewsCategory
- Adiciona listagem com filtros de categoria e ano, busca e paginação
- Adiciona corpo StreamField com blocos de título, parágrafo, imagem e citação
- Adiciona testes, incluindo contagem fixa de consultas para a listagem
```

Habilidades Relacionadas