Cómo documentar una API REST de WordPress con IA

La IA puede redactar documentación de API REST de WordPress a partir de rutas registradas, esquemas y pruebas, pero no debe inventar endpoints, permisos, efectos secundarios ni ejemplos que no se hayan verificado frente a la implementación en ejecución.

La IA es más útil aquí como organizadora de evidencias, motor de comparación y asistente de redacción. Puede hacer que una tarea compleja de WordPress sea más fácil de inspeccionar, pero no puede crear autoridad faltante, certificar hechos que no ha observado ni convertir silenciosamente una recomendación en permiso para actuar.

En una frase: la IA puede redactar documentación de API REST de WordPress a partir de rutas registradas, esquemas y pruebas, pero no debe inventar endpoints, permisos, efectos secundarios ni ejemplos que no se hayan verificado frente a la implementación en ejecución.

Lo que esta guía le ayuda a lograr

Cree documentación de API versionada y respaldada por evidencias que describa rutas, métodos, autenticación, callbacks de permisos, esquemas, efectos secundarios, errores y ejemplos probados.

• Un inventario de rutas y métodos vinculado a evidencias del código fuente y del tiempo de ejecución.
• Esquemas de solicitud y respuesta con campos obligatorios, condicionales y de solo lectura.
• Comportamiento de autenticación y autorización, incluidas las denegaciones esperadas.
• Ejemplos probados, casos de error, notas de versión y estado de desuso.

El artefacto terminado debe ser comprensible para la persona responsable de la decisión y reproducible por alguien que no participó en el prompt original. Una respuesta fluida no es suficiente. Cada conclusión material necesita una fuente, un alcance y una ruta de verificación. Cuando las evidencias no pueden establecer algo, la salida correcta es una incógnita explícita o una hipótesis comprobable.

Evidencias e insumos que preparar

• Salida de rutas registradas del entorno previsto.
• Código fuente del controlador y de los callbacks en un commit exacto.
• Esquemas, callbacks de permisos y requisitos de capacidades.
• Pruebas de integración y fixtures de solicitud-respuesta redactadas.
• Política de versionado, desuso y compatibilidad con versiones anteriores.

Antes de proporcionar evidencias a un asistente, elimine credenciales, valores secretos e información personal no relacionada. Conserve los identificadores, versiones, marcas de tiempo, configuración regional, unidades y etiquetas de fuente necesarios para interpretar lo que queda. Una captura de pantalla sin URL, estado o fecha puede ser contexto útil, pero rara vez constituye autoridad suficiente para una decisión de producción.

No comience con una solicitud amplia como «revise esto», «arregle esto» o «hágalo mejor». Defina la decisión que el trabajo debe respaldar, la población incluida, la fuente que es autoritativa para cada campo, las operaciones permitidas y las acciones que siguen prohibidas. Para esta tarea se requiere acceso autenticado a WordPress o una exportación controlada.

El descubrimiento y la documentación son diferentes

Una ruta puede estar registrada sin un esquema completo, ejemplos útiles o documentación clara de efectos secundarios. El descubrimiento en tiempo de ejecución es un insumo, no la referencia terminada.

La autenticación no es la autorización

Una contraseña de aplicación válida identifica a un usuario; cada endpoint aún necesita una decisión de permiso adecuada para la acción y el objeto.

Los ejemplos son afirmaciones ejecutables

Una solicitud copiada implica que el método, la ruta, los campos y la respuesta son actuales. Los ejemplos deben generarse a partir de pruebas o verificarse mediante ellas.

Mantenga separadas la observación, la inferencia y la autoridad

Una revisión controlada debe distinguir al menos cuatro estados:

1. Observado: presente directamente en un registro, archivo, respuesta, página renderizada o prueba ejecutada con nombre.
2. Inferido: una interpretación plausible respaldada por evidencias, pero no establecida directamente.
3. Recomendado: una decisión humana propuesta o una acción siguiente.
4. Autorizado y verificado: un cambio aprobado por separado que se ejecutó y luego se comprobó frente a los criterios de aceptación.

La salida de la IA normalmente comienza en los tres primeros estados. No pasa a estar autorizada simplemente porque sea detallada, internamente coherente o técnicamente convincente. Conserve esta distinción en tablas, informes, tickets y casos de estudio públicos.

Un flujo de trabajo seguro

1. Congele la versión del plugin o la aplicación y el entorno objetivo.
2. Recopile el descubrimiento de rutas, las definiciones fuente, los esquemas y las pruebas.
3. Normalice los endpoints por espacio de nombres, ruta, método y versión.
4. Pida a la IA que redacte la documentación con referencias explícitas a evidencias e incógnitas.
5. Verifique cada afirmación de autenticación, permisos, validación y efectos secundarios.
6. Ejecute los ejemplos frente a una fixture aislada y oculte los valores confidenciales.
7. Revise la usabilidad para desarrolladores, la guía de errores y la compatibilidad con versiones anteriores.
8. Publique la referencia versionada y vuelva a probarla en la CI de lanzamiento.

Esta secuencia sitúa deliberadamente una revisión responsable entre el análisis y la implementación. Si una fase posterior necesita un acceso más amplio, cree una nueva tarea, una nueva identidad o un cambio explícito de permisos. No eleve silenciosamente la identidad analítica porque haya alcanzado un límite correcto.

Receta de prompt

Sustituya cada valor entre corchetes antes de usar el prompt. No pegue contraseñas, claves de API, cookies de autenticación, registros privados de clientes ni información personal no relacionada.

Está revisando [TASK SCOPE] para [SITE, REPOSITORY OR DATASET] utilizando únicamente las evidencias proporcionadas.

Objetivo:
Cree documentación de API versionada y respaldada por evidencias que describa rutas, métodos, autenticación, callbacks de permisos, esquemas, efectos secundarios, errores y ejemplos probados.

Devuelva los siguientes campos:
- Espacio de nombres
- Ruta
- Método
- Propósito
- Autenticación
- Permiso
- Argumentos
- Esquema
- Efecto secundario
- Respuesta de éxito
- Respuesta de error
- Fixture de prueba
- Versión

Reglas:
1. No invente rutas, campos, capacidades ni códigos de estado.
2. Separe la autenticación de la autorización del endpoint.
3. Conserve exactamente los tokens de espacio de nombres, método, campo y enumeración.
4. Use ejemplos redactados generados a partir de fixtures seguras.
5. No llame endpoints de escritura de producción.

Para cada hallazgo:
- identifique la fuente, el registro, la URL, el archivo, la línea, el ID de objeto, el estado o la fila del conjunto de datos exactos;
- conserve fechas, versiones, unidades, configuración regional, identificadores y denominadores;
- separe observación, inferencia, recomendación e incógnita;
- indique qué evidencias no estaban disponibles;
- no cambie WordPress, el código fuente, los datos comerciales, las analíticas, los sistemas externos ni el contenido publicado.

Por qué este prompt está estructurado de esta manera

El prompt crea un contrato de evidencias antes de pedir recomendaciones. Hace visibles los datos faltantes, reduce la probabilidad de que un modelo complete un registro incompleto con prosa plausible y produce una salida que puede revisarse sistemáticamente. Los campos estructurados también facilitan comparar ejecuciones repetidas o entregar un subconjunto aprobado a un flujo de trabajo de implementación posterior.

Una implementación de producción puede añadir un esquema JSON, entradas de herramientas tipadas o validación automatizada. Esos mecanismos mejoran la coherencia, pero no establecen que las evidencias de origen sean verdaderas, completas o actuales. Siguen siendo necesarias la revisión humana y la verificación específica del sistema.

Límite de acceso recomendado

Use Solo lectura para la fase descrita en esta guía. Las capacidades exactas disponibles para una identidad deben proceder de la versión de producto instalada, el contrato de cobertura publicado y el método de conexión que se esté utilizando realmente.

Lo que debe quedar fuera de esta tarea

• Solicitudes de producción
• Exposición de secretos
• Ejemplos fabricados
• Generalización de permisos
• Cambios incompatibles no documentados

Una acción rechazada puede ser una evidencia útil de que el límite de control funciona. No responda a un rechazo esperado otorgando una cuenta de administrador amplia o Full Power. Primero determine si la acción pertenece al mandato actual. Si pertenece, cree una fase autorizada por separado con la capacidad requerida más limitada.

Cómo encaja WP Agent Control

La carpeta privada guiada para Claude Code o Codex utiliza REST de WordPress y una contraseña de aplicación con un perfil dedicado de solo lectura. Los perfiles existentes Read Only, Draft, Content Editor y Publisher siguen en las opciones avanzadas. No se convierten automáticamente a OAuth ni heredan el modelo de tareas remotas y aprobación exacta.

Obtén información estructurada del sitio e inspecciona páginas publicadas seleccionadas después de conectar. Esta lectura pública no requiere una tarea temporal. También puedes navegar por páginas públicas sin el plugin; Agent Control añade acceso estructurado y continuidad hacia operaciones autorizadas en WordPress.

Conectar tu IA: docs first profile · Ver funciones y compatibilidad: coverage

Lista de verificación

• ☐ La tarea, la población, el período, el entorno y la decisión son explícitos.
• ☐ Cada observación material está vinculada a evidencias exactas o se etiqueta como hipótesis.
• ☐ Se conservan ID estables, URL, versiones, fechas, unidades, configuraciones regionales y denominadores.
• ☐ Las evidencias faltantes y los límites de cobertura siguen visibles.
• ☐ La identidad analítica o de investigación no realizó ninguna mutación prohibida.
• ☐ Un propietario cualificado revisó las implicaciones de seguridad, accesibilidad, legales, comerciales o de lanzamiento cuando corresponde.
• ☐ Cualquier implementación tiene un mandato, nivel de acceso, copia de seguridad y plan de verificación separados.
• ☐ Las identidades temporales, fixtures y evidencias sensibles se revocan, restablecen o eliminan después de la tarea.

Modos de fallo comunes

• Documentación solo de código fuente: el registro condicional o los filtros en tiempo de ejecución hacen que el conjunto de rutas desplegado difiera del código leído por el asistente.
• Ejemplos solo de éxito: los consumidores no aprenden nada sobre las respuestas de validación, autorización o conflicto.
• Administrador equivale a permitido: la referencia describe suposiciones amplias de rol en lugar del callback de permiso real.
• Referencia generada obsoleta: la documentación no está vinculada a la CI y se desvía del paquete publicado.

Un fallo transversal recurrente es la deriva de permisos: la tarea inicial encuentra un límite y el operador amplía el acceso antes de determinar si la operación faltante es necesaria, compatible o segura. Esto destruye el valor probatorio del rechazo y hace que los resultados posteriores sean difíciles de atribuir.

Nota avanzada

Genere la documentación a partir de una representación intermedia versionada que combine rutas registradas, esquemas y pruebas de contrato ejecutadas. Las explicaciones redactadas por humanos pueden entonces enriquecer la referencia sin convertirse en una segunda autoridad para los hechos de los endpoints.

Guías relacionadas

• Cómo crear una matriz de pruebas de permisos de WordPress para agentes de IA
• Cómo revisar código de plugins de WordPress con IA
• Guía de la API Abilities de WordPress para flujos de trabajo con IA
• Cómo exponer una Ability personalizada de WordPress mediante MCP

Siguiente paso

Continúe con la guía de apoyo más pertinente y use la guía de niveles de acceso antes de cualquier tarea autenticada. Cuando ya no se necesite acceso temporal a WordPress, termine revocando la identidad.