Claude Code no Desenvolvimento WordPress: Como Usar de Verdade

Era 2022. Eu estava há três horas configurando um bloco de depoimentos no WordPress (o terceiro daquele trimestre) e parei para pesquisar se o RichText.Content ia na função save ou no callback de render. Eu já sabia a resposta — já tinha feito isso dezenas de vezes. Mas a troca de contexto sempre custa caro, e quando voltei, tinha perdido o fio da meada do que realmente estava tentando resolver.

Foi nesse momento que o Claude começou a se tornar indispensável no meu fluxo de trabalho com WordPress.

Não como um substituto para entender o código. Se você não sabe o que o wp_enqueue_scripts faz, o Claude gerando o código para você não vai ajudar a debugar quando um bug aparecer em produção. O valor real está em manter o foco no problema enquanto ele cuida da mecânica: o "esqueleto" (scaffolding) de blocos, o registro de hooks e aquele array de argumentos do register_post_type que eu nunca lembro se o has_archive vem antes ou depois do rewrite.

O Claude cuida da engrenagem enquanto eu foco na arquitetura. Ele é meu estagiário, meu desenvolvedor júnior e meu rubber duck, tudo ao mesmo tempo.

Aqui está como eu realmente uso, com detalhes práticos.

Antes de Escrever o Primeiro Prompt

A diferença entre o "Claude é útil" e o "Claude é irritante" vive quase inteiramente no contexto inicial. Poste um pedido vago e receba um código genérico. Dê ao Claude as restrições reais do seu projeto e receba algo que você pode colar direto no seu plugin após uma revisão rápida.

Eu mantenho um template de contexto do projeto salvo. Leva dois minutos para preencher e elimina a maioria dos erros de geração:

  # Plugin WordPress — Contexto para Claude Code

  ## Identidade do projeto
  - Nome do plugin: [Nome do Plugin]
  - Text domain: [text-domain]
  - WordPress mínimo: 6.6
  - PHP mínimo: 8.2
  - Ferramenta de build: @wordpress/scripts

  ## Antes de gerar qualquer código
  Leia o arquivo principal do plugin e uma classe existente antes de escrever algo novo.
  Se houver blocos, leia um bloco completo (block.json + edit.js + render.php) antes de criar outro.
  Se houver padrões (patterns), leia o diretório patterns/.
  Mantenha o padrão de nomenclatura, estrutura de classes e organização de arquivos.

  ## Arquitetura
  - Registro de Hooks via classe Loader (includes/class-loader.php). Novos hooks vão lá, não inline.
  - Uma classe por arquivo. Nome do arquivo: class-[classname].php em kebab-case.
  - Blocos: src/blocks/[block-name]/ — diretório próprio para cada bloco.
  - CPTs: includes/class-post-types.php
  - Endpoints REST: includes/class-rest-api.php

  ## JavaScript
  - Nada de jQuery. Use as APIs wp.* nativas ou vanilla JS.
  - API REST para operações assíncronas.
  - Apenas ES modules. Sem require().
  - Para blocos interativos: use a Interactivity API (wp-interactivity).

  ## Segurança — Inegociável
  - Sanitizar entradas: `sanitize_text_field()`, `absint()`, `wp_kses_post()`.
  - Escapar saídas: `esc_html()`, `esc_url()`, `esc_attr()`. Nunca dê echo direto.
  - Verificar Nonces em todos os formulários e handlers REST.
  - Verificar permissões (capabilities) antes de qualquer escrita.
  - `$wpdb->prepare()` em toda query direta ao banco.

  ## O que NÃO fazer
  - Sem funções obsoletas (deprecated).
  - Sem versão do plugin hardcoded no enqueue. Use a constante.
  - Sem `extract()`. Sem tags PHP curtas.
  - Não use `publicly_queryable => true` em CPTs sem necessidade.

Salvar isso como um CLAUDE.md no projeto força a IA a gerar código que respeita o seu projeto real, não exemplos genéricos de 2019. Se você ainda suporta WordPress 5.8 ou PHP 7.4, deixe isso claro, ou o plugin vai quebrar no servidor do cliente.

Construindo Blocos Gutenberg Passo a Passo

Começando pelo Esqueleto (Scaffolding)

Um novo bloco exige no mínimo quatro arquivos: block.json, edit.js, um callback PHP de renderização e o CSS. A lógica é o que toma tempo; a estrutura inicial não deveria.

Com o Claude Code rodando no seu terminal, ele lê o que já existe em src/blocks/, entende a estrutura dos seus block.json e as convenções de CSS. O contexto é a sua base de código real.

O prompt pode ser assim:

Veja os blocos em src/blocks/ para entender o padrão.
Crie um bloco de depoimentos:
- Texto da citação (RichText)
- Nome do autor (PlainText)
- Foto (MediaUpload com preview)
- Nota/Estrelas (atributo numérico 1–5)
Crie os arquivos no diretório correto seguindo o padrão do projeto.

Ele gera os arquivos direto no lugar certo. O render.php já virá com esc_html() e os nomes de classes seguirão o seu padrão. Nada de copiar e colar.

Variações de Blocos e InnerBlocks

Variações de blocos são onde o acesso a arquivos brilha. O Claude lê o seu bloco de "Card" existente antes de gerar versões horizontal ou vertical, garantindo que os nomes de atributos e classes coincidam.

Para InnerBlocks, peça a implementação completa, incluindo o array de template e as configurações de trava (lock). O que parece simples no código às vezes gera uma UX confusa no editor; peça para ele seguir os padrões de outros blocos que você já testou.

Arquitetura de Plugins sem Burocracia

O Padrão Loader

O Claude Code lê seu arquivo principal antes de propor mudanças. Se você já tem uma estrutura de classes organizada, ele a estende. Se estiver começando do zero:

Gere o esqueleto de um plugin com o padrão Loader:
- Classe Loader para gerenciar ações e filtros.
- Classe Admin para scripts do painel.
- Classe Public para o frontend.
Instancie tudo no plugins_loaded.

Isso evita que o plugin se torne um arquivo monolítico de 5 mil linhas impossível de manter após três meses.

Queries e CPTs

O array do register_post_type tem quase 30 chaves. O Claude gera a chamada completa a partir de uma descrição simples. O mesmo vale para o WP_Query: peça para ele incluir apenas o necessário (ex: fields => 'ids' quando você só precisa dos IDs), evitando o consumo desnecessário de memória.

Para mais detalhes sobre como estruturar consultas para performance, veja meu post sobre Otimização de Velocidade no WordPress.

Quando a IA Erra (E ela erra)

Este trecho é importante porque é o que salva o seu deploy.

O Claude gera código "plausível". Mas plausível não é o mesmo que seguro ou correto para o seu contexto específico. Já vi ele gerar endpoints REST que verificavam o Nonce, mas esqueciam de validar a permissão do usuário (capability). Ou deixar um CPT como público quando ele deveria ser interno.

Peça para o Claude revisar o próprio código:

Revise os arquivos que você acabou de criar focando em:
- Funções obsoletas para a versão 6.6 do WP.
- Falta de verificação de capabilities.
- Saídas sem o devido escape.

O gap de segurança costuma ser o modelo de permissões. O Claude sabe as regras gerais, mas não sabe se o seu plugin tem níveis de acesso customizados. Você ainda é o responsável pelo que vai ao ar.

Outro ponto são as migrações de banco de dados. Trate o código da IA como um rascunho. Ela não conhece o estado real dos seus dados (como aquele post de 2018 com um meta malformado). Sempre teste em staging com um dump real do banco antes de rodar qualquer migração.

Usar o Claude Code não é apenas sobre velocidade; é sobre a economia acumulada. São os 15 minutos que você não gastou lendo a documentação de uma função básica ou escrevendo código boilerplate pela décima vez.

A IA cuida do trabalho braçal e repetitivo. O "COMO" o sistema será construído ainda é uma decisão sua.

Se você está trabalhando em uma arquitetura complexa de WordPress e quer uma revisão técnica antes do lançamento, veja como eu trabalho.