Codex para WordPress: cómo desarrollar plugins, depurar errores y revisar seguridad

cd wp-content/plugins/mi-plugin

git status

codex

codex --cd /ruta/wordpress/wp-content/plugins/mi-plugin

Analiza este plugin WordPress.

No modifiques archivos todavía.

Explícame:

1. propósito del plugin
2. archivo bootstrap
3. clases principales
4. hooks actions y filters
5. shortcodes
6. endpoints REST
7. handlers AJAX
8. tablas personalizadas
9. opciones utilizadas
10. cron jobs
11. JavaScript y CSS
12. integraciones externas
13. dependencias
14. flujo de datos
15. zonas sensibles de seguridad

Indica los archivos
y funciones exactas
para cada punto.

# WordPress project instructions

## Stack

- WordPress
- PHP
- MySQL
- JavaScript
- AJAX
- REST API
- WooCommerce where present

## General rules

- Do not modify WordPress core.
- Prefer WordPress APIs over custom replacements.
- Preserve existing public APIs.
- Avoid unrelated refactors.
- Keep changes narrowly scoped.
- Follow the existing plugin architecture.

## Security

- Validate input when a strict rule exists.
- Sanitize untrusted input.
- Escape output according to context.
- Check user capabilities for privileged actions.
- Use nonces for CSRF protection where appropriate.
- Never treat a nonce as authorization.
- Use prepared SQL for dynamic database queries.
- Review REST permission callbacks.
- Never expose credentials or secrets.

## Database

- Preserve existing table prefixes.
- Do not delete production data.
- Explain migrations before implementing them.
- Avoid schema changes unless required.

## Verification

Before finishing:

1. run PHP syntax checks on changed PHP files
2. run project tests when available
3. run linting when configured
4. inspect git diff
5. look for debug code
6. report files changed
7. report tests executed
8. report remaining risks

Objetivo:

Añadir un campo "Teléfono"
al formulario de registro
del plugin.

Comportamiento actual:

El formulario guarda:
- nombre
- email
- categoría

Comportamiento esperado:

- mostrar teléfono
- validar formato
- sanitizar antes de guardar
- guardar en la estructura existente
- mostrarlo en el panel administrativo
- mantener compatibilidad con registros antiguos

Restricciones:

- no modificar WordPress core
- no crear una tabla nueva
- no cambiar URLs públicas
- no romper usuarios existentes
- seguir la arquitectura actual

Antes de editar:

1. identifica los archivos afectados
2. explica el flujo actual
3. propón un plan
4. indica riesgos

Después implementa
el cambio mínimo.

Finalmente ejecuta
las verificaciones disponibles
y revisa el diff.

No modifiques archivos todavía.

Crea un plan de implementación.

Para cada paso indica:

- archivo
- función o clase
- cambio necesario
- motivo
- dependencia
- riesgo
- forma de verificarlo

Busca reutilizar
la arquitectura existente.

Evita crear
abstracciones nuevas
si el proyecto ya tiene
una solución equivalente.

Haz una auditoría
de seguridad de este plugin WordPress.

No modifiques archivos.

Revisa especialmente:

1. $_GET
2. $_POST
3. $_REQUEST
4. $_FILES
5. AJAX handlers
6. REST routes
7. admin-post handlers
8. formularios
9. SQL dinámico
10. uploads
11. operaciones de filesystem
12. opciones y metadata
13. autenticación
14. autorización
15. nonces
16. credenciales
17. output HTML

Para cada hallazgo incluye:

- severidad
- archivo
- línea
- código afectado
- vulnerabilidad
- escenario realista
- impacto
- corrección recomendada

No reportes
problemas puramente teóricos
sin una ruta plausible
de explotación.

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

check_ajax_referer(
    'my_plugin_action',
    'nonce'
);

$title = isset( $_POST['title'] )
    ? sanitize_text_field(
        wp_unslash( $_POST['title'] )
    )
    : '';

echo esc_html( $title );

Busca en este plugin:

- consultas $wpdb
- SQL concatenado
- variables dentro de queries
- LIKE dinámicos
- nombres de tablas dinámicos

Comprueba si cada consulta
maneja correctamente
los valores dinámicos.

Prioriza el uso
de $wpdb->prepare()
cuando corresponda.

No modifiques nada todavía.

Devuelve:
archivo,
línea,
query
y riesgo.

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

Encuentra todos
los handlers AJAX
del plugin.

Para cada uno determina:

- hook registrado
- usuarios autenticados o públicos
- parámetros recibidos
- nonce
- capability check
- validación
- sanitización
- consultas SQL
- cambios de estado
- estructura de respuesta

Marca específicamente
cualquier handler
que permita escritura
sin autorización suficiente.

register_rest_route(
    'my-plugin/v1',
    '/settings',
    array(
        'methods'  => 'POST',
        'callback' => 'my_plugin_save_settings',

        'permission_callback' => function () {
            return current_user_can(
                'manage_options'
            );
        },
    )
);

Investiga este bug.

Síntoma:

Al guardar el formulario,
la pantalla muestra éxito
pero el registro
no aparece en la base de datos.

No modifiques código todavía.

Sigue este proceso:

1. reproduce el flujo
2. identifica el entry point
3. sigue los datos
   desde frontend hasta DB
4. revisa request y response
5. revisa logs
6. localiza el punto
   donde se pierde el dato
7. determina la causa raíz
8. explica por qué ocurre

Solo después
propón la corrección mínima.

Antes de crear archivos nuevos:

1. busca cómo resuelve
   este proyecto
   funcionalidades similares

2. reutiliza:
   - clases existentes
   - helpers
   - repositories
   - services
   - hooks
   - templates
   - convenciones

3. no introduzcas
   un framework paralelo

4. explica
   cualquier nueva abstracción
   antes de crearla

When editing WordPress code:

- follow the project's existing style
- follow WordPress security best practices
- preserve translatability
- preserve backwards compatibility
- use WordPress APIs where appropriate
- maintain accessibility requirements
- do not change third-party vendor code
- do not perform style-only rewrites
  unless requested

# Ejemplos cuando el proyecto
# ya tiene estas herramientas configuradas

vendor/bin/phpcs

vendor/bin/phpunit

php -l archivo.php

Analiza la integración
WooCommerce de este plugin.

Mapea:

- hooks utilizados
- productos
- carrito
- checkout
- pedidos
- Mi Cuenta
- endpoints
- metadata
- estados personalizados
- emails
- cron jobs

Después identifica:

- dependencias de WooCommerce
- APIs internas utilizadas
- posibles incompatibilidades
- acceso directo innecesario
  a estructuras internas
- puntos sensibles
  de autorización

No modifiques código.

Necesitamos añadir
una columna a la tabla
del plugin.

No implementes todavía.

Analiza:

1. cómo se crea actualmente la tabla
2. cómo se guarda la versión del esquema
3. cómo se ejecutan upgrades
4. instalaciones nuevas
5. instalaciones existentes
6. rollback posible
7. datos antiguos
8. índices
9. compatibilidad
10. riesgo de pérdida de datos

Propón primero
un plan de migración
seguro e idempotente.

Corrige este formulario
sin cambiar su diseño.

Problema:

Después de enviar por AJAX,
el mensaje de éxito
aparece correctamente,
pero el formulario
puede enviarse dos veces.

Requisitos:

- localizar causa raíz
- bloquear doble submit
- preservar accesibilidad
- mantener mensajes existentes
- no introducir jQuery
  si el proyecto no lo usa
- no modificar estilos
  no relacionados

Verifica
el flujo completo
frontend → PHP → respuesta.

.agents/
└── skills/
    ├── wordpress-security-review/
    │   └── SKILL.md
    │
    ├── wordpress-debug/
    │   └── SKILL.md
    │
    ├── database-migration-review/
    │   └── SKILL.md
    │
    └── wordpress-release/
        └── SKILL.md

---
name: wordpress-security-review
description: Audit WordPress plugins and themes for security problems involving input, output, authorization, AJAX, REST API, SQL, uploads and secrets.
---

# WordPress Security Review

Check:

1. validation
2. sanitization
3. escaping
4. nonces
5. capabilities
6. SQL
7. AJAX handlers
8. REST permission callbacks
9. file operations
10. secrets

Do not modify code.

Return findings ordered by severity.

For every finding include:

- file
- line
- vulnerability
- realistic impact
- recommended correction

Analiza este plugin
con cuatro subagentes.

architecture:
mapea clases,
hooks,
requests
y persistencia.

security:
revisa nonces,
capabilities,
input,
output,
SQL
y REST.

compatibility:
revisa PHP,
WordPress
y WooCommerce.

testing:
identifica
flujos críticos
sin cobertura.

Trabajen en paralelo.

No modifiquen archivos.

Después consolida
los resultados,
elimina duplicados
y ordena
los hallazgos
por severidad.

Antes de utilizar
una API de WordPress
o una integración externa:

1. verifica la documentación actual
2. confirma la firma
3. confirma parámetros
4. confirma comportamiento
5. identifica deprecaciones
6. solo entonces implementa

$wordpress-security-review

Revisa únicamente
los cambios
desde la ejecución anterior.

Comprueba:

- PHP syntax
- security
- AJAX
- REST
- database
- debug code
- deprecated patterns

No modifiques archivos.

Si no existen
hallazgos nuevos,
indícalo claramente.

/review

Revisa el diff actual.

Busca únicamente:

- bugs reales
- regresiones
- autorización insuficiente
- SQL inseguro
- output sin escape
- AJAX o REST inseguros
- pérdida de datos
- problemas de compatibilidad
- tests importantes faltantes

No reportes
preferencias subjetivas
de estilo.

Ordena
por severidad.

Prepara este plugin
para una nueva release.

No publiques nada.

Comprueba:

1. git status
2. versión actual
3. archivos de versión
4. changelog
5. PHP syntax
6. tests
7. linting
8. debug code
9. dependencias
10. assets generados
11. archivos no deseados
12. compatibilidad
13. seguridad del diff

Después entrega:

- blockers
- warnings
- cambios incluidos
- comandos ejecutados
- estado final

No hagas push,
tag,
deploy
ni publicación.

Objetivo:

[describe el resultado]


Contexto:

[explica el problema]


Comportamiento actual:

[qué ocurre ahora]


Comportamiento esperado:

[qué debería ocurrir]


Archivos o módulos relevantes:

[si los conoces]


Restricciones:

- no modificar WordPress core
- no romper APIs públicas
- mantener compatibilidad existente
- reutilizar arquitectura actual
- evitar refactors no relacionados
- aplicar permisos mínimos
- respetar prácticas de seguridad WordPress


Antes de editar:

1. explora el flujo actual
2. identifica archivos y funciones
3. explica la causa o arquitectura
4. crea un plan
5. enumera riesgos


Implementación:

- realiza el cambio mínimo
- conserva estilo existente
- añade o actualiza tests
  cuando exista infraestructura


Seguridad:

revisa:

- validation
- sanitization
- escaping
- nonces
- capabilities
- SQL
- AJAX
- REST
- filesystem
- secrets


Verificación:

1. PHP syntax
2. tests
3. lint
4. flujo afectado
5. git diff


Respuesta final:

- qué cambió
- archivos modificados
- causa raíz si había un bug
- tests ejecutados
- riesgos restantes