Para de escrever boilerplate WordPress

Passei os últimos meses a construir um harness para desenvolvimento de plugins WordPress com Claude Code, um sistema que deixa o agente gerar boilerplate WordPress para eu não ter de o fazer. Skills, hooks, ficheiros de planeamento, dois sub-agents, uma CLI, um exemplo trabalhado. Esta semana saiu como v1.0.0 do wp-agentic-kit, e escrevo isto para que outros developers de WordPress não tenham de descobrir a camada de harness do zero. O kit é opinativo; este post é sobre o que aprendi e que me fez achar que estas opiniões valiam a pena.

Desisti da IA para WordPress por volta do fim de 2024. O output estava sempre a um nonce em falta ou a um escape errado de me dar um CVE. Pedia um endpoint REST e recebia algo com permission_callback a __return_true numa rota que mutava estado. Pedia uma Settings page e recebia capability checks a disparar no hook errado. O código parecia certo e quase nunca estava. Voltei a escrever à mão.

Um ano depois acho que estava errado, mas não pela razão que se possa pensar. A solução não era um modelo melhor. A solução era o sistema à volta do modelo. O código ia sempre ser de graça. O que não era de graça é garantir que esse código gratuito fazia o que eu precisava.

Índice

• Onde começou o meu raciocínio
• As quatro ideias que acabei por codificar
• O momento em que me apanhei a prescrever demais
• Uma feature, de ponta a ponta
• Começa em cinco minutos
• O que noto agora que o harness está montado
• Onde isto não se aplica
• O que fazer segunda de manhã
• Disclosure e um convite

Onde começou o meu raciocínio

Há umas semanas escrevi sobre como o trabalho do senior engineer mudou. Esse post era a tese geral. Este é o que acontece quando te sentas para aplicar essa tese a uma codebase específica. No meu caso, WordPress, porque é em WordPress que ganho a maior parte da vida: engagements no Codeable, clientes da Pluginslab, os meus próprios plugins.

Comecei a escrever bocados do harness em Janeiro, sobretudo para coçar comichões minhas. Um CLAUDE.md a explicar as convenções do plugin. Um hook pre-commit com phpcs porque o agente esquecia-se sempre de escapar. Uma skill que fazia as perguntas certas quando eu queria adicionar um bloco Gutenberg. Cada peça resolvia uma chatice. Nenhuma delas parecia um “projecto”.

Depois fui convidado para falar no WordCamp Portugal 2026 sobre engenharia agêntica. O talk obrigou-me a juntar as peças em algo coerente que se pudesse explicar em palco. O kit é o que caiu dessa montagem. Escrevi-o mais para a audiência do WordCamp do que para mim, e o acto de o escrever para outra pessoa mudou quais as peças que ficaram e quais saíram.

As quatro ideias que acabei por codificar

A Anthropic publica um AI Fluency Framework com quatro ideias a que chamam os quatro D’s. Não comecei por aqui; redescobri-os a posteriori. Quando voltei a olhar para o que andava a construir, o kit mapeava nestes quatro de forma quase demasiado limpa. Aceitei o framing.

Delegação. Entrega trabalho estruturado ao agente. Não “escreve-me um plugin”, mas “segue esta entrevista, faz uma pergunta de cada vez, depois faz scaffold com estas convenções”. A estrutura ganha à freestyle. As duas skills do kit (wordpress-scaffold, wordpress-feature) são esses handoffs estruturados.

Descrição. Diz ao agente o que é permitido e o que estás a construir. Não em prosa, em listas. “Funções de escape permitidas: esc_html, esc_attr, esc_url” é vinculativo. “Usa funções de escape modernas” é interpretável, e o modelo interpreta de forma diferente cada vez que lê. O constitution.md do kit é uma lista enumerada, não um parágrafo.

Discernimento. Arranja uma leitura independente antes de aprovares. Não um segundo agente que também consiga escrever código, mas um sub-agent read-only que audita o plano ou o diff e reporta findings. Pode assinalar um nonce em falta. Não o pode “corrigir” para te ajudar, e é precisamente esse o ponto. O kit traz dois: plan-reviewer e security-reviewer, ambos sem ferramentas Edit ou Write por design.

Diligência. Torna as redes de segurança impossíveis de saltar. Um hook que corre phpcs em cada commit não se deixa convencer por um prompt esperto. Um hook que injecta o plano activo no contexto a cada turno não se ignora sob pressão de deadline. Diligência é engenharia, não memória. O kit traz cinco hooks; o crítico é o UserPromptSubmit, que volta a ancorar o agente no plano a cada turno.

Estas quatro ideias são os ossos do starter kit. O kit torna cada uma concreta com ficheiros que podes ler, editar e roubar. Já escrevi sobre porque é que o WordPress especificamente beneficia disto em Agentic Development: Why WordPress Developers Must Adopt It Now; o kit é o que esse argumento parece quando entra em produção.

O momento em que me apanhei a prescrever demais

Por volta da v0.7 do kit, tive um momento que lhe mudou a forma. Andava a estender a constituição para listar também todos os pacotes npm que o agente podia usar. Todas as deps de Composer. Todas as helper classes. A lista crescia, e o kit parecia cada vez mais frágil. A certa altura apanhei-me a resmungar para o ecrã:

O Claude já é suficientemente inteligente para que, se eu lhe disser demasiado, seja mais provável que falhe do que faça as coisas dele.

Foi essa a chave. A constituição não devia ser uma grande allowlist. Deviam ser duas: uma allowlist estrita para as escolhas com impacto em segurança (sanitizers, escapers, constantes de capability, construções proibidas) e uma lista default para as dependências. A lista estrita vincula com força porque o failure mode é um CVE. A lista default é consultiva porque o failure mode é “adicionaste uma biblioteca utilitária sobre a qual alguém possa ter perguntas”. Mesmo ficheiro, contratos diferentes.

A mesma lógica aplicou-se à regra de plan-freeze. A minha primeira versão era: “Cada plano vai num PR seu. Cada feature espera por revisão humana do plano antes de qualquer código ser escrito.” Estava certo para features com impacto em segurança e absurdo para correcções de typos. A solução foi um Freeze assessment de cinco checkboxes em cada plano: qualquer checkbox marcada significa freeze, zero checkboxes significa avançar na mesma sessão. Um typo e um novo endpoint REST deixaram de pagar a mesma cerimónia.

Cortei cerca de um terço da prosa dos prompts a seguir a isso. As duas skills passaram de cerca de 180 linhas para 54. O kit sente-se mais leve agora e o agente faz menos desvios pedinchas para pedir autorização para tretas.

Uma feature, de ponta a ponta

Eis o que construir uma feature parece depois de o kit estar montado. Tens um plugin com uma settings page e uns blocos. Um stakeholder pede um bloco Gutenberg que mostre o estado de uma encomenda, alimentado por um endpoint REST que possa ser chamado de qualquer sítio.

Abres o Claude Code e escreves:

i need a gutenberg block “order-status” that shows the current status of an order, and a REST endpoint to fetch the status by order id. dynamic render.

O que acontece, por ordem:

1. O agente lê o CLAUDE.md, repara que já existe um plugin, e invoca a skill wordpress-feature.
2. A skill escreve o spec.md: o que vai ser construído, três a sete bullets de aceitação, e uma secção Out of scope explícita (sem vista de lista, sem histórico cronológico, sem notificações). Essa linha de out-of-scope é a frase de maior alavancagem do spec, porque tudo o que não esteja lá nomeado fica indefinido e o modelo vai assumir que está dentro do âmbito.
3. A skill escreve o plan.md: passos faseados com caminhos de ficheiros em cada passo. Cada passo tem o teste que se escreve primeiro.
4. O plano termina com um Freeze assessment. Nova rota REST marca “toca em código com impacto em segurança” e “muda a superfície da API pública”. Duas checkboxes marcadas, logo a recomendação é freeze. A skill corre ./scripts/open-plan-pr.sh, que abre um PR só com spec.md e plan.md. O sub-agent plan-reviewer audita o PR (read-only). Eu revejo o plano no GitHub. Cinco minutos, focado em saber se a abordagem está certa, não se a sintaxe está. Faço merge.
5. O agente escreve o código numa branch separada. Os hooks disparam a cada edit (lint), a cada prompt (re-injectar plano), e a cada commit (suite completa de qualidade). Commit partido, commit bloqueado.
6. Antes de o PR da feature fazer merge, o security-reviewer audita o diff. Read-only, classificado por severidade.
7. Depois do merge, a directoria da feature passa para .claude/plans/archive/. Memória de longo prazo para a próxima feature que toque em código semelhante.

É este o ciclo. O agente escreve. Eu julgo. A maior parte do meu tempo vai para ler o spec e o plano, não o diff.

Começa em cinco minutos

Não precisas de ler nada do que está acima para começar. Corre:

npx create-wp-ai-plugin my-plugin

Vai fazer-te cinco perguntas: nome do plugin, prefixo de vendor opcional, descrição, autor, versões alvo de WordPress e PHP. Depois a CLI puxa o kit, substitui os teus identificadores em todos os ficheiros, renomeia pl-example.php para {your-slug}.php, instala dependências de PHP e Node, puxa quinze skills com sabor a WordPress de WordPress/agent-skills, e inicia um repo git com uma tag scaffold.

O que tens é um plugin a funcionar: um endpoint REST de exemplo, uma fixture de PHPUnit a passar, um CLAUDE.md que conhece as tuas convenções, os hooks que as forçam, a camada de planeamento com um exemplo trabalhado, e três slash commands para as operações que vais repetir: /plan-freeze, /audit-plan, /ship-feature.

Abre a nova directoria no Claude Code. O harness já está carregado. Diz ao agente o que queres construir.

O que noto agora que o boilerplate WordPress desapareceu

Mudaram três coisas no meu dia-a-dia desde que comecei a usar uma versão deste kit no meu próprio trabalho com clientes.

Já não me preocupo com regressões de segurança. Não porque o agente ficou mais inteligente, mas porque o phpcs corre em cada commit e o security-reviewer lê cada diff antes de fazer merge. Os hooks não pedem autorização. Não embarco uma variável sem escape há meses, e também não tenho sido eu a apanhá-la.

Deixei de andar à deriva entre sessões. O hook UserPromptSubmit re-injecta o plano activo e o progresso a cada turno. Abro um projecto passada uma semana, escrevo o primeiro prompt, e o agente já sabe onde fiquei, o que vem a seguir e qual o passo bloqueado. O imposto do “o que é que eu estava aqui a fazer?” desapareceu.

Deixei de ler diffs linha a linha. Por volta da terceira ou quarta feature com o harness no sítio, a minha atenção subiu na stack. Leio o spec e o plano com atenção. Passo o olho pelo diff. Os resultados dos testes carregam o peso que a leitura linha a linha carregava antes. Essa mudança é o que o kit te tenta dar.

Onde isto não se aplica

Dois casos onde eu saltaria o harness, pelo menos no início.

Scripts one-shot e plugins descartáveis. Montar este harness para um snippet de 50 linhas que migra a shortcode antiga de um cliente é over-engineering. Faz vibe-code, faz ship e segue em frente. O harness compensa quando vais voltar à mesma codebase repetidamente, não quando lá vais tocar uma vez.

Devs que ainda não fizeram ship de um plugin. Se nunca passaste pelo ciclo de escrever, activar, partir, fazer debug e desinstalar um plugin, ainda não tens as opiniões que valem a pena codificar numa constituição. Faz ship de uns plugins pelo caminho lento. Encontra as convenções em que acreditas mesmo. Depois volta e escreve-as.

O que fazer segunda de manhã

Três jogadas concretas, por ordem de custo.

1. Faz scaffold de um plugin descartável com o kit. Gasta dez minutos. Lê o exemplo trabalhado em .claude/plans/features/001-example-hello-rest/. O spec, o plano, o progresso, o código em si. Vais pensar “sim, é isto que quero” ou “não, isto está errado para mim”. Qualquer das respostas é útil.

2. Adiciona uma regra ao CLAUDE.md do teu próprio plugin. A regra deve ser algo que já corrigiste ao agente duas vezes. “Usa sempre wp_kses_post para output em HTML, nunca esc_html em conteúdo rico”. “Custom post types são registados em includes/class-cpt.php, não no bootstrap”. Se já corrigiste duas vezes, escreve-a uma vez.

3. Instala um hook. Escolhe a rede de segurança de que te andas sempre a esquecer. A minha foi phpcs no commit; a tua pode ser correr testes antes do push ou recusar commit se uma feature flag estiver desligada. Cinco minutos em .claude/hooks/ e .claude/settings.json. Agora corre sempre.

Não precisas do kit todo para começar. Precisas é de começar.

Disclosure e um convite

Um disclosure para fechar. Sou Codeable expert e founder da Pluginslab. Vendo trabalho de engenharia, sobretudo WordPress, muitas vezes WooCommerce. Fazer ship mais rápido com menos regressões é bom para o meu negócio. Não sou portanto neutro na afirmação de que é na camada de harness que está a alavancagem. Construí o kit e estou a dizer-te para usares o kit. Lê o post como sinal do que faço nos meus próprios projectos, não como sales pitch.

O kit está sob licença MIT e vive em pluginslab/wp-agentic-kit. Se adoptares e partir alguma coisa, diz-me. Se adoptares e mudar a forma como uma segunda-feira se sente, diz-me na mesma. Os dois tipos de feedback tornam a próxima versão melhor. A versão portuguesa da tese subjacente está no talk do WordCamp Portugal; se preferes ver em vez de ler, é por aí.

A versão mais forte do argumento não é este post. É o que muda depois de passares uma semana a fazer ship com um harness montado. Corre o install. Tenta uma feature. Depois volta e diz-me o que partiu.

Relacionado: The Senior Engineer’s Job Just Changed, o argumento mais amplo por trás deste kit.