WP Playground: O elo perdido entre Agentes de IA e Código Real

Agentes de IA escrevem código. Mas código sem teste é apenas uma sugestão. No ecossistema WordPress, validar um plugin ou tema exige um ambiente completo. Você precisa do WordPress instalado, compatível e pronto para que esses agentes testem seu site, analisem o banco de dados, ativem plugins e definam configurações específicas.

O WordPress Playground é exatamente este ponto de conexão entre agentes e o ambiente real. O problema é que, por padrão, o Playground reinicia a instância do WordPress a cada reinício. Montar tudo isso manualmente a cada iteração mata a produtividade que o agente deveria trazer.

É aqui que Blueprints e o WordPress Playground CLI entram em jogo. Com um único arquivo JSON e um comando no terminal, o agente levanta um WordPress configurado para testar o código gerado, identificar erros e corrigi-los em um ciclo automatizado. Se você já leu meus posts sobre fundamentos de Blueprints e o Playground CLI, este artigo conecta essas peças ao mundo dos agentes de IA.

Por que agentes de IA precisam do playground

O problema é simples: um agente como o Claude Code, o Gemini CLI ou o GitHub Copilot pode gerar um plugin WordPress inteiro, mas, sem um ambiente de execução, não consegue verificar se o código funciona. Por isso, muitas vezes, programadores e vibe coders ficam frustrados com os resultados gerados pela inteligência artificial para WordPress.

Sem verificação, alucinações passam despercebidas ou tarefas ficam incompletas. O ciclo “escrever → testar → corrigir” (write-test-fix loop) resolve isso:

O agente escreve código PHP do plugin.
Um Playground roda com um blueprint que configura o ambiente do WordPress com o plugin montado.
O agente roda testes E2E com Playwright.
O agente lê a saída de erro, corrige o código.
Repete até os testes passarem.

Com Playground CLI + Blueprint, é um comando. O ambiente sobe em segundos, efêmero e descartável, perfeito para o ritmo de um agente. Para criar blueprints, existem ferramentas visuais, como o Step Library ou o Agent Skills.ts, existem ferramentas visuais, como o Step Library ou o Agent Skills.

A wp-playground Agent Skill: ensinando agentes a usar o Playground

A wp-playground skill é um conjunto de instruções que ensina agentes de IA a usar o Playground CLI de forma eficiente. Em vez do agente inventar comandos (e alucinar), a skill fornece documentação estruturada sobre como construir Blueprints, rodar o CLI e debugar problemas.

A skill segue o conceito de progressive disclosure e carrega apenas, na janela de contexto, as informações de que o agente realmente precisa naquele momento, economizando tokens e mantendo o foco.

Agentes suportados: Claude Code, Gemini CLI, GitHub Copilot, Cursor, Antigravity e Codex.

Instalação da skill

O jeito mais rápido é via terminal, na raiz do seu projeto WordPress:

npx skills add wordpress/agent-skills --skill wp-playground

A skill será instalada no diretório correspondente ao agente detectado:

Agente	Diretório
Claude Code	`.claude/skills/wp-playground/`
Gemini CLI	`.gemini/skills/wp-playground/`
GitHub Copilot	`.github/skills/wp-playground/`
Cursor	`.cursor/skills/wp-playground/`
Antigravity	`.agent/skills/wp-playground/`
Codex	`.codex/skills/wp-playground/`

Para instalação manual ou build customizado:

git clone https://github.com/WordPress/agent-skills.git
cd agent-skills
node shared/scripts/skillpack-build.mjs --clean
node shared/scripts/skillpack-install.mjs --dest=../your-wp-project --targets=claude,gemini,cursorCode language: PHP (php)

WordPress Playground MCP: agentes controlando WordPress em tempo real

Além da skill (que opera via CLI no terminal), o WordPress Playground também suporta MCP (Model Context Protocol) — um canal direto entre o agente e uma instância do Playground rodando no browser.

A diferença prática:

	CLI Skill	MCP
Ambiente	Terminal (headless)	Browser (visual)
Conexão	Comandos shell	WebSocket
Quando usar	CI/CD, testes automatizados	Interação visual, screenshots, debugging

Com o MCP, o agente pode instalar plugins, executar PHP, criar conteúdo e navegar pelo wp-admin — tudo via ferramentas padronizadas do protocolo MCP.

Configurando o MCP Server

Claude Code (.claude/settings.json ou via IDE):

claude mcp add --transport stdio --scope user wordpress-playground -- npx -y @wp-playground/mcpCode language: CSS (css)

Gemini CLI (.gemini/settings.json):

gemini mcp add wordpress-playground npx -y @wp-playground/mcpCode language: CSS (css)

Após configurar, verifique a conexão:

# Gemini CLI
/mcp list

# Claude Code — o MCP aparece automaticamente nas ferramentas disponíveisCode language: PHP (php)

Exemplo prático: agente gerenciando WordPress via MCP

Com o MCP configurado, uma conversa com o agente pode ser assim:

Você: “Instale o WooCommerce, crie um produto de teste e verifique se a página de loja está funcionando.”

O agente usa as ferramentas MCP para:

Abrir uma instância do Playground no browser.
Executar PHP para instalar e ativar o WooCommerce.
Criar conteúdo via wp_insert_post() com um produto de teste.
Navegar para /shop/ e verificar o resultado.
Capturar screenshot para confirmar visualmente.

Tudo sem você tocar no terminal ou no browser.

Blueprints Skill como ponte: de linguagem natural a ambiente configurado

Uma das vantagens mais poderosas é que agentes com a nova agent skill para blueprints conseguem gerar Blueprints a partir de linguagem natural.

npx skills add https://github.com/wordpress/agent-skills --skill blueprintCode language: JavaScript (javascript)

O formato original das Blueprints é JSON, que não é amigável para usuários finais, além de exigir a decoração de todas as propriedades aceitas pelas Blueprints. Com a nova skill, o agente sabe exatamente quais propriedades e steps são válidos, o que reduz drasticamente as alucinações.

Os steps mais usados por agentes:

installPlugin — instalar plugins do wordpress.org ou de URLs externas
installTheme — instalar temas
runPHP — executar código PHP arbitrário (criar posts, configurar options)
writeFile — escrever arquivos (mu-plugins, configurações)
importWxr — importar conteúdo via WXR
setSiteOptions — definir opções do site
wp-cli — executar comandos WP-CLI

Ciclo “escrever, testar, corrigir”

Na prática, o loop completo do agente é assim:

# 1. Agente inicia o Playground com o plugin montado
npx @wp-playground/cli start --blueprint=test-env.json --auto-mount --port=9400

# 2. Agente roda teste E2E com Playwright
npx playwright test tests/e2e/my-plugin.spec.ts

# 3. Se falhar, agente lê o erro, edita o código e repeteCode language: PHP (php)

O Playground CLI no modo start persiste os dados entre reinícios em ~/.wordpress-playground/sites/. Use --reset para começar do zero quando necessário.

Hooks: automatizando o ciclo de vida da sessão com agentes

Para fechar o ciclo de automação, os hooks permitem que o Playground inicie automaticamente quando você abre uma sessão com o agente e encerre quando a sessão termina.

Aqui vai o resumo dos três hooks essenciais:

1. Session start — iniciar Playground automaticamente:

#!/bin/bash
# hooks/start-playground.sh
PORT=9400

if lsof -i :$PORT -sTCP:LISTEN &>/dev/null; then
  echo "WordPress Playground já rodando em http://localhost:$PORT."
  exit 0
fi

npx @wp-playground/cli start --port=$PORT &>/dev/null &
sleep 3

if lsof -i :$PORT -sTCP:LISTEN &>/dev/null; then
  echo "WordPress Playground iniciado em http://localhost:$PORT."
else
  echo "Falha ao iniciar o Playground." >&2
  exit 2
fiCode language: PHP (php)

2. Post-edit — verificar sintaxe PHP após cada edição:

O agente edita um arquivo .php → o hook roda php -l automaticamente → se há erro de sintaxe, o agente é avisado imediatamente.

3. Session end — encerrar o Playground:

O hook identifica o processo na porta 9400 e encerra com kill.

A configuração varia entre Gemini CLI (.gemini/settings.json) e Claude Code (.claude/settings.json).

llms.txt: o Playground se apresenta para a IA

Vale conhecer o arquivo playground.wordpress.net/llms.txt: um resumo legível por máquina das capacidades, APIs e documentação do Playground, no formato llms.txt. É o que permite a um agente “entender” o Playground sem você precisar explicar tudo no prompt. Se você acompanha o tema, já falei sobre o formato no post Guia de llms.txt no WordPress — aqui ele aparece aplicado a uma ferramenta real.

Conclusão

WordPress Playground é o elo perdido entre a geração de código por agentes de IA e a validação desse código em um ambiente WordPress real. Com a combinação de wp-playground skill, blueprint skill, MCP e Hooks, o ecossistema forma um pipeline completo: o agente escreve, o Playground testa, o agente corrige — tudo sem intervenção manual.

Experimente instalar a wp-playground skill no seu agente preferido e veja como o ciclo de desenvolvimento muda.