Claude Code para WordPress: plugins, WooCommerce, PHP y debugging

cd /ruta/mi-wordpress

claude

Analiza este plugin WordPress completo.

No modifiques ningún archivo.

Identifica:

- archivo principal del plugin
- proceso de inicialización
- clases principales
- namespaces
- actions
- filters
- shortcodes
- AJAX handlers
- endpoints REST
- cron jobs
- custom post types
- taxonomías
- tablas personalizadas
- opciones wp_options
- user meta
- post meta
- scripts y estilos
- WooCommerce integrations
- permisos
- nonces
- dependencias externas

Después crea un mapa de arquitectura
y explícame el flujo principal
del plugin.

Busca todos los:

add_action()
add_filter()
do_action()
apply_filters()

del plugin.

Para cada uno indica:

- hook
- callback
- archivo
- prioridad
- número de argumentos
- cuándo se ejecuta
- qué modifica

Después identifica:

- callbacks huérfanos
- hooks duplicados
- dependencias difíciles de seguir
- hooks demasiado globales

No cambies código todavía.

claude --permission-mode plan

Quiero añadir [FEATURE].

Investiga primero:

1. qué archivos están relacionados
2. qué hooks existentes podemos reutilizar
3. dónde se almacenan los datos
4. qué permisos necesitamos
5. si requiere nonce
6. si afecta REST o AJAX
7. posibles efectos en WooCommerce
8. riesgos de compatibilidad
9. tests necesarios

Después crea un plan paso a paso.

No implementes todavía.

# Proyecto WordPress

Este repositorio contiene un plugin WordPress.

## Reglas generales

- Sigue WordPress Coding Standards.
- Mantén compatibilidad con las versiones declaradas por el plugin.
- No modifiques WordPress core.
- No modifiques plugins de terceros.
- No añadas dependencias sin necesidad.
- No cambies APIs públicas sin autorización.
- Prefiere APIs públicas de WordPress y WooCommerce.

## Seguridad

IMPORTANT:

- Valida antes de procesar datos cuando sea posible.
- Sanitiza toda entrada no confiable.
- Escapa la salida en el momento de renderizarla.
- Los nonces protegen contra CSRF pero NO reemplazan autorización.
- Comprueba capacidades con current_user_can().
- Usa $wpdb->prepare() para consultas SQL dinámicas.
- No almacenes secretos en el repositorio.
- Revisa permisos en AJAX y REST API.

## AJAX

Para handlers AJAX:

- verifica nonce
- verifica capability cuando corresponda
- sanitiza parámetros
- devuelve wp_send_json_success() o wp_send_json_error()
- no expongas datos privados

## REST API

Para endpoints:

- registra rutas en rest_api_init
- define permission_callback
- valida argumentos
- sanitiza argumentos
- utiliza WP_REST_Response o WP_Error
- versiona namespaces

## WooCommerce

- Prefiere APIs públicas de WooCommerce.
- No dependas de Automattic\WooCommerce\Internal.
- No dependas de código marcado @internal.
- Usa objetos WC_Product, WC_Order, WC_Customer y APIs públicas cuando corresponda.
- Respeta HPOS y mecanismos oficiales de almacenamiento.

## Base de datos

- No construyas SQL con concatenación de datos del usuario.
- Usa $wpdb->prepare().
- Evita consultas N+1.
- No cambies esquemas sin plan de migración.
- Usa dbDelta() cuando sea apropiado para tablas del plugin.

## Testing

Después de cambios PHP:

php -l archivo.php

Si el proyecto tiene herramientas configuradas:

composer test
vendor/bin/phpcs
vendor/bin/phpunit

## WordPress CLI

Puedes utilizar WP-CLI para inspección y verificación.

Evita cambios destructivos salvo que se pidan explícitamente.

## Git

Antes de terminar:

- revisa git diff
- confirma que no se modificó código fuera del alcance
- ejecuta pruebas relevantes
- resume archivos modificados y verificaciones realizadas

wp core version

wp plugin list

wp theme list

wp cron event list

wp option get siteurl

Usa WP-CLI para inspeccionar este WordPress.

Quiero conocer:

- versión de WordPress
- PHP disponible si puede determinarse
- plugins activos
- tema activo
- cron events relevantes
- configuración del plugin actual
- posibles errores visibles

Utiliza solamente comandos de lectura.

No actualices,
no elimines,
no actives
ni desactives nada.

Resume cualquier anomalía encontrada.

php -l includes/class-orders.php

Tenemos un problema AJAX.

Síntoma:

[DESCRIBIR]

Traza el flujo completo:

JavaScript
→ request
→ admin-ajax.php
→ action
→ wp_ajax_*
→ callback PHP
→ nonce
→ capability
→ validación
→ consulta
→ respuesta JSON

Comprueba específicamente:

- nombre de action
- handler para usuario autenticado
- handler nopriv si corresponde
- nonce
- check_ajax_referer()
- current_user_can()
- sanitización
- SQL
- wp_send_json_success()
- wp_send_json_error()
- errores JavaScript

Encuentra primero
la causa raíz.

No cambies código
hasta poder explicar
exactamente dónde falla.

check_ajax_referer( 'my_action', 'nonce' );

if ( ! current_user_can( 'manage_options' ) ) {
    wp_send_json_error(
        array( 'message' => 'No autorizado.' ),
        403
    );
}

echo esc_html( $title );

echo esc_attr( $class_name );

echo esc_url( $link );

Audita todo uso de $wpdb
en este plugin.

Busca:

- variables concatenadas en SQL
- consultas sin prepare()
- uso incorrecto de placeholders
- LIKE inseguro
- consultas N+1
- SELECT *
- índices faltantes
- queries ejecutadas dentro de loops
- escrituras innecesarias
- datos sensibles

Para cada problema indica:

archivo
línea
severidad
consulta actual
riesgo
solución recomendada

No cambies código todavía.

$row = $wpdb->get_row(
    $wpdb->prepare(
        "SELECT * FROM {$table_name} WHERE user_id = %d",
        $user_id
    )
);

Necesito crear:

POST /wp-json/ciborg/v1/items

Antes de programar:

1. busca endpoints existentes del plugin
2. identifica sus convenciones
3. revisa permisos
4. revisa modelos de datos

El nuevo endpoint debe:

- registrarse en rest_api_init
- utilizar namespace ciborg/v1
- definir permission_callback
- validar argumentos
- sanitizar entradas
- comprobar capacidades
- devolver WP_REST_Response o WP_Error
- usar códigos HTTP apropiados
- incluir tests

No utilices wp_send_json()
dentro del callback REST.

register_rest_route(
    'ciborg/v1',
    '/items',
    array(
        'methods'             => 'POST',
        'callback'            => 'ciborg_create_item',
        'permission_callback' => function () {
            return current_user_can( 'manage_options' );
        },
    )
);

Analiza esta integración WooCommerce.

Quiero saber:

- qué hooks WooCommerce utiliza
- qué objetos WC_* utiliza
- qué datos modifica
- si depende del almacenamiento de pedidos
- si es compatible con HPOS
- si accede directamente a tablas
- si utiliza APIs públicas
- si depende de clases @internal
- qué ocurre al activar/desactivar el plugin
- posibles problemas de compatibilidad

No modifiques código.

Prioriza APIs públicas
y patrones documentados
de WooCommerce.

Busca en este plugin:

Automattic\WooCommerce\Internal

y cualquier uso
de métodos,
clases
o hooks
marcados @internal.

Para cada resultado:

- archivo
- línea
- API interna utilizada
- API pública alternativa si existe
- riesgo de compatibilidad

No cambies código todavía.

Estamos preparando una actualización de WooCommerce.

Consulta la documentación oficial
y los developer advisories relevantes.

Después revisa:

- plugins activos desarrollados por nosotros
- mu-plugins
- functions.php del tema
- hooks WooCommerce utilizados

Identifica callbacks
que puedan depender
de comportamiento
que haya cambiado.

No modifiques nada
hasta entregar
el informe de compatibilidad.

Tenemos este error WordPress:

[ERROR]

Quiero que:

1. localices el origen
2. traces la ejecución hasta la causa
3. determines por qué ocurre
4. identifiques si depende de un hook
5. identifiques versión o compatibilidad si aplica
6. reproduzcas el error
7. implementes la corrección mínima
8. ejecutes PHP lint
9. ejecutes tests relacionados

No suprimas warnings.
No desactives validaciones.
No añadas @ para ocultar errores.

Corrige la causa raíz.

tail -n 500 wp-content/debug.log | claude -p "
Analiza estos logs de WordPress.

Agrupa:

- PHP Fatal
- PHP Warning
- PHP Deprecated
- errores de plugins
- errores de WooCommerce
- consultas fallidas

Identifica el primer error relevante,
diferencia causas de consecuencias
y recomienda qué investigar primero.
"

Quiero añadir el shortcode:

[ciborg_directory]

Antes de programar:

- busca otros shortcodes del plugin
- reutiliza sus patrones
- identifica cómo cargan assets
- revisa escaping
- revisa consultas
- revisa caché si existe

El shortcode debe:

- devolver output, no imprimirlo directamente
- escapar toda salida dinámica
- evitar cargar CSS/JS globalmente si no es necesario
- soportar atributos documentados
- no introducir SQL inseguro

Añade tests si el proyecto
ya tiene infraestructura para ellos.

Audita cómo este plugin
carga CSS y JavaScript.

Busca:

- assets cargados en todas las páginas
- dependencias innecesarias
- versiones incorrectas
- scripts duplicados
- código inline excesivo
- admin assets en frontend
- frontend assets en admin

Propón una estrategia
para cargar cada asset
solamente donde sea necesario.

No cambies comportamiento visual.

Busca todas las tareas WP-Cron
creadas por este plugin.

Identifica:

- nombre del hook
- cuándo se agenda
- frecuencia
- callback
- argumentos
- cuándo se elimina
- qué ocurre al desactivar el plugin

Después compara
con:

wp cron event list

Busca:

- eventos duplicados
- callbacks inexistentes
- eventos que nunca se limpian
- operaciones demasiado costosas
- llamadas externas sin timeout.

Audita el lifecycle de este plugin.

Revisa:

- activation hook
- deactivation hook
- uninstall
- creación de tablas
- actualización de esquema
- cron jobs
- transients
- opciones
- archivos temporales
- capabilities personalizadas

Dime qué se crea,
qué se conserva
y qué se elimina
en cada etapa.

Identifica datos
que puedan quedar huérfanos.

Necesitamos almacenar:

[DATOS]

Antes de crear una tabla personalizada,
evalúa si debería utilizar:

- posts
- post meta
- users
- user meta
- options
- taxonomy
- WooCommerce APIs
- custom table

Explica el tradeoff.

Si una tabla personalizada
es realmente apropiada,
diseña:

- nombre con $wpdb->prefix
- columnas
- tipos
- primary key
- índices
- schema version
- migración
- creación segura
- desinstalación

No implementes
hasta justificar
por qué una custom table
es la mejor opción.

Usa un subagent especializado
para auditar este plugin WordPress.

Busca únicamente vulnerabilidades
con impacto plausible.

Revisa:

- SQL injection
- XSS almacenado
- XSS reflejado
- CSRF
- capabilities
- privilege escalation
- AJAX nopriv
- REST permission_callback
- uploads
- path traversal
- SSRF
- command injection
- unserialize inseguro
- secretos
- exposición de datos
- redirects
- datos sin sanitizar
- output sin escaping

Para cada hallazgo incluye:

SEVERIDAD
ARCHIVO
LÍNEA
FLUJO DE DATOS
IMPACTO
CORRECCIÓN

No modifiques código.

No reportes problemas puramente teóricos.

.claude/agents/wordpress-security.md

---
name: wordpress-security
description: Reviews WordPress and WooCommerce code for security vulnerabilities
tools: Read, Grep, Glob, Bash
---

You are a WordPress security reviewer.

Focus on:

- nonce verification
- authorization and capabilities
- input validation
- sanitization
- output escaping
- SQL injection
- AJAX handlers
- REST permission callbacks
- file uploads
- redirects
- SSRF
- secrets
- WooCommerce permissions

A nonce is not authorization.

Always inspect whether
current_user_can()
or an appropriate permission check exists.

Report only findings
supported by concrete code paths.

Include:
- severity
- file
- line
- impact
- recommended remediation

.claude/skills/review-wordpress-plugin/SKILL.md

---
name: review-wordpress-plugin
description: Reviews a WordPress plugin before release
disable-model-invocation: true
---

Review the current WordPress plugin.

1. Inspect git diff
2. Run PHP lint on changed PHP files
3. Run configured tests
4. Run PHPCS if available
5. Review nonces and capabilities
6. Review sanitization and escaping
7. Review REST permission callbacks
8. Review AJAX handlers
9. Review dynamic SQL
10. Review WooCommerce compatibility
11. Check for debugging code
12. Check for accidental secrets

Return:

- blocking issues
- warnings
- tests executed
- files reviewed
- release recommendation

Crea un Hook de Claude Code
que después de editar archivos PHP:

1. detecte el archivo modificado
2. ejecute php -l sobre ese archivo
3. bloquee la finalización si existe un error de sintaxis
4. devuelva el error a Claude para que lo corrija

No ejecutes PHP lint
sobre archivos que no sean .php.

Audita este plugin WordPress
buscando problemas de rendimiento.

Prioriza:

- consultas N+1
- WP_Query repetidas
- consultas dentro de loops
- options autoload demasiado grandes
- transients mal utilizados
- HTTP requests en cada page load
- falta de caché
- cron demasiado frecuente
- hooks globales costosos
- assets cargados innecesariamente
- WooCommerce queries costosas

No optimices todavía.

Para cada hallazgo indica
cómo medir el rendimiento
antes y después.

Antes de optimizar esta consulta,
explica:

- cuántas veces se ejecuta
- cuándo se ejecuta
- volumen esperado de datos
- índices relevantes
- coste probable
- cómo podemos medirlo

Propón una prueba reproducible.

Solo optimiza
si podemos comparar
antes y después.

Antes de considerar terminado el cambio:

1. revisa los requisitos originales
2. revisa git diff
3. ejecuta PHP lint
4. ejecuta tests configurados
5. ejecuta PHPCS si existe
6. revisa seguridad
7. revisa nonces y capabilities
8. revisa sanitización y escaping
9. revisa consultas SQL
10. revisa REST/AJAX afectados
11. busca debugging temporal
12. busca secretos accidentales
13. comprueba cambios fuera de alcance

Al finalizar entrega:

- archivos modificados
- comandos ejecutados
- tests ejecutados
- resultados
- riesgos pendientes
- recomendación de deploy

No afirmes que funciona
sin mostrar evidencia.

Usa un subagent con contexto limpio.

Revisa exclusivamente
los cambios de git diff.

Asume que la implementación
puede estar equivocada.

Busca:

- requisitos incumplidos
- regresiones
- errores PHP
- WordPress API misuse
- nonces sin autorización
- capabilities faltantes
- XSS
- SQL injection
- REST permissions
- WooCommerce incompatibilities
- tests faltantes

No reportes preferencias
de estilo sin impacto.

Devuelve solamente
hallazgos accionables.

Revisa git diff.

Si todas las verificaciones pasan:

1. confirma que no haya cambios accidentales
2. confirma que no haya secretos
3. crea un commit descriptivo
4. resume la funcionalidad modificada
5. prepara el pull request

En el PR incluye:

- problema
- solución
- WordPress APIs utilizadas
- tests
- compatibilidad
- riesgos pendientes.

OBJETIVO

Quiero implementar:

[FEATURE]


CONTEXTO

Es un proyecto WordPress.

Área afectada:

[PLUGIN / TEMA / WOOCOMMERCE]


ANTES DE PROGRAMAR

Investiga:

- arquitectura
- archivos relacionados
- hooks
- clases
- AJAX
- REST
- datos
- permisos
- nonces
- SQL
- patrones existentes


SEGURIDAD

Comprueba:

- validación
- sanitización
- escaping
- capabilities
- nonces
- REST permission_callback
- consultas preparadas


WORDPRESS

- no modifiques core
- no modifiques plugins de terceros
- usa APIs públicas
- sigue WordPress Coding Standards


WOOCOMMERCE

Si aplica:

- usa APIs públicas
- evita Automattic\WooCommerce\Internal
- evita código @internal
- considera compatibilidad de almacenamiento


IMPLEMENTACIÓN

Crea primero un plan.

Después implementa
la solución mínima
que siga la arquitectura existente.


VERIFICACIÓN

Después de implementar:

- PHP lint
- tests
- PHPCS si está disponible
- WP-CLI cuando ayude
- revisión de git diff
- comprobación manual o navegador si aplica


REVISIÓN FINAL

Usa un subagent independiente
para revisar:

- regresiones
- seguridad
- requisitos incumplidos
- cambios fuera de alcance


RESULTADO

Entrega:

- archivos modificados
- explicación de la solución
- comandos ejecutados
- tests realizados
- riesgos pendientes
- recomendación de deploy.