Como documentar uma API REST do WordPress com IA

A IA pode redigir documentação de API REST do WordPress a partir de rotas, esquemas e testes registrados, mas não deve inventar endpoints, permissões, efeitos colaterais ou exemplos que não foram verificados em relação à implementação em execução.

A IA é mais útil aqui como organizadora de evidências, mecanismo de comparação e assistente de redação. Ela pode tornar uma tarefa complexa do WordPress mais fácil de inspecionar, mas não pode criar autoridade ausente, certificar fatos que não observou nem converter silenciosamente uma recomendação em permissão para agir.

Em uma frase: a IA pode redigir documentação de API REST do WordPress a partir de rotas, esquemas e testes registrados, mas não deve inventar endpoints, permissões, efeitos colaterais ou exemplos que não foram verificados em relação à implementação em execução.

O que este guia ajuda você a realizar

Crie documentação de API versionada e baseada em evidências que descreva rotas, métodos, autenticação, callbacks de permissão, esquemas, efeitos colaterais, erros e exemplos testados.

• Um inventário de rotas e métodos vinculado a evidências do código-fonte e do tempo de execução.
• Esquemas de solicitação e resposta com campos obrigatórios, condicionais e somente leitura.
• Comportamento de autenticação e autorização, incluindo negativas esperadas.
• Exemplos testados, casos de erro, notas de versão e status de descontinuação.

O artefato concluído deve ser compreensível para a pessoa responsável pela decisão e reproduzível por alguém que não participou do prompt original. Uma resposta fluente não é suficiente. Toda conclusão relevante precisa de uma fonte, um escopo e um caminho de verificação. Quando as evidências não podem estabelecer algo, a saída correta é um desconhecido explícito ou uma hipótese testável.

Evidências e insumos a preparar

• Saída das rotas registradas no ambiente pretendido.
• Código-fonte do controlador e do callback em um commit exato.
• Esquemas, callbacks de permissão e requisitos de capabilities.
• Testes de integração e fixtures de solicitação-resposta redigidas.
• Política de versionamento, descontinuação e compatibilidade retroativa.

Antes de fornecer evidências a um assistente, remova credenciais, valores secretos e informações pessoais não relacionadas. Preserve os identificadores, versões, timestamps, localidade, unidades e rótulos de fonte necessários para interpretar o que permanece. Uma captura de tela sem URL, estado ou data pode ser contexto útil, mas raramente é autoridade suficiente para uma decisão de produção.

Não comece com uma solicitação ampla como “revise isto”, “corrija isto” ou “melhore isto”. Defina a decisão que o trabalho deve apoiar, a população incluída, a fonte que é autoritativa para cada campo, as operações permitidas e as ações que permanecem proibidas. Acesso autenticado ao WordPress ou uma exportação controlada é necessário para esta tarefa.

Descoberta e documentação são diferentes

Uma rota pode ser registrada sem esquema completo, exemplos úteis ou documentação clara dos efeitos colaterais. A descoberta em tempo de execução é uma entrada, não a referência finalizada.

Autenticação não é autorização

Uma senha de aplicação válida identifica um usuário; cada endpoint ainda precisa de uma decisão de permissão apropriada para a ação e o objeto.

Exemplos são afirmações executáveis

Uma solicitação copiada implica que o método, o caminho, os campos e a resposta estão atuais. Os exemplos devem ser gerados por testes ou verificados por eles.

Mantenha observação, inferência e autoridade separadas

Uma revisão controlada deve distinguir pelo menos quatro estados:

1. Observado: presente diretamente em um registro, arquivo, resposta, página renderizada ou teste executado nomeado.
2. Inferido: uma interpretação plausível sustentada por evidências, mas não estabelecida diretamente.
3. Recomendado: uma decisão humana proposta ou próxima ação.
4. Autorizado e verificado: uma mudança aprovada separadamente, executada e então conferida diante dos critérios de aceitação.

A saída da IA normalmente começa nos três primeiros estados. Ela não se torna autorizada apenas por ser detalhada, internamente coerente ou tecnicamente convincente. Preserve essa distinção em tabelas, relatórios, tickets e estudos de caso públicos.

Um fluxo de trabalho seguro

1. Congele a versão do plugin ou da aplicação e o ambiente de destino.
2. Colete descoberta de rotas, definições de fonte, esquemas e testes.
3. Normalize endpoints por namespace, caminho, método e versão.
4. Peça à IA que redija documentação com referências explícitas de evidência e desconhecidos.
5. Verifique cada afirmação sobre autenticação, permissão, validação e efeito colateral.
6. Execute exemplos em uma fixture isolada e redija valores sensíveis.
7. Revise a usabilidade para desenvolvedores, orientação de erros e compatibilidade retroativa.
8. Publique a referência versionada e teste-a novamente na CI de lançamento.

Essa sequência posiciona deliberadamente uma revisão responsável entre a análise e a implementação. Se uma etapa posterior precisar de acesso mais amplo, crie uma nova tarefa, uma nova identidade ou uma mudança explícita de permissão. Não eleve silenciosamente a identidade analítica porque ela encontrou um limite correto.

Receita de prompt

Substitua cada valor entre colchetes antes de usar o prompt. Não cole senhas, chaves de API, cookies de autenticação, registros privados de clientes ou informações pessoais não relacionadas.

Você está revisando [TASK SCOPE] para [SITE, REPOSITORY OR DATASET] usando somente as evidências fornecidas.

Objetivo:
Crie documentação de API versionada e baseada em evidências que descreva rotas, métodos, autenticação, callbacks de permissão, esquemas, efeitos colaterais, erros e exemplos testados.

Retorne os seguintes campos:
- Namespace
- Rota
- Método
- Finalidade
- Autenticação
- Permissão
- Argumentos
- Esquema
- Efeito colateral
- Resposta de sucesso
- Resposta de erro
- Fixture de teste
- Versão

Regras:
1. Não invente rotas, campos, capabilities ou códigos de status.
2. Separe a autenticação da autorização do endpoint.
3. Preserve exatamente os tokens de namespace, método, campo e enum.
4. Use exemplos redigidos gerados a partir de fixtures seguras.
5. Não chame endpoints de escrita de produção.

Para cada constatação:
- identifique a fonte, o registro, a URL, o arquivo, a linha, a ID do objeto, o estado ou a linha do conjunto de dados exatos;
- preserve datas, versões, unidades, localidade, identificadores e denominadores;
- separe observação, inferência, recomendação e desconhecido;
- declare quais evidências não estavam disponíveis;
- não altere o WordPress, o código-fonte, os dados comerciais, a análise, os sistemas externos ou o conteúdo publicado.

Por que este prompt está estruturado assim

O prompt cria um contrato de evidências antes de pedir recomendações. Ele torna dados ausentes visíveis, reduz a chance de um modelo completar um registro incompleto com prosa plausível e produz uma saída que pode ser revisada sistematicamente. Campos estruturados também facilitam a comparação de execuções repetidas ou a entrega de um subconjunto aprovado a um fluxo de implementação posterior.

Uma implementação de produção pode adicionar esquema JSON, entradas de ferramentas tipadas ou validação automatizada. Esses mecanismos melhoram a consistência, mas não estabelecem que as evidências de origem sejam verdadeiras, completas ou atuais. Revisão humana e verificação específica do sistema continuam necessárias.

Limite de acesso recomendado

Use Somente leitura para a etapa descrita neste guia. As capacidades exatas disponíveis para uma identidade devem vir da versão instalada do produto, do contrato de cobertura publicado e do método de conexão realmente em uso.

O que deve permanecer fora desta tarefa

• Solicitações de produção
• Exposição de segredos
• Exemplos fabricados
• Generalização de permissões
• Alterações incompatíveis não documentadas

Uma ação recusada pode ser uma evidência útil de que o limite de controle está funcionando. Não responda a uma recusa esperada concedendo uma conta de administrador ampla ou Full Power. Primeiro determine se a ação pertence ao mandato atual. Se pertencer, crie uma etapa autorizada separadamente com a capacidade necessária mais restrita.

Como o WP Agent Control se encaixa

A pasta privada guiada para Claude Code ou Codex usa REST do WordPress e uma senha de aplicativo com perfil dedicado somente para leitura. Os perfis existentes Read Only, Draft, Content Editor e Publisher permanecem nas opções avançadas. Não são convertidos automaticamente para OAuth nem recebem o modelo remoto de tarefas e aprovação exata.

Obtenha informações estruturadas do site e inspecione páginas publicadas selecionadas após conectar. Essa leitura pública não exige tarefa temporária. Você também pode visitar páginas públicas sem o plugin; o Agent Control acrescenta acesso estruturado e continuidade para o trabalho autorizado no WordPress.

Conectar sua IA: docs first profile · Ver recursos e compatibilidade: coverage

Lista de verificação

• ☐ A tarefa, a população, o período, o ambiente e a decisão são explícitos.
• ☐ Toda observação relevante está vinculada a evidências exatas ou rotulada como hipótese.
• ☐ IDs estáveis, URLs, versões, datas, unidades, localidades e denominadores são preservados.
• ☐ Evidências ausentes e limites de cobertura permanecem visíveis.
• ☐ A identidade analítica ou de pesquisa não realizou mutação proibida.
• ☐ Um responsável qualificado revisou implicações de segurança, acessibilidade, legais, comerciais ou de lançamento quando aplicável.
• ☐ Qualquer implementação tem mandato, nível de acesso, backup e plano de verificação separados.
• ☐ Identidades temporárias, fixtures e evidências sensíveis são revogadas, redefinidas ou descartadas após a tarefa.

Modos de falha comuns

• Documentação somente de código-fonte: registro condicional ou filtros de execução fazem o conjunto de rotas implantado diferir do código lido pelo assistente.
• Exemplos somente de sucesso: consumidores não aprendem nada sobre respostas de validação, autorização ou conflito.
• Administrador equivale a permitido: a referência descreve suposições amplas de papel em vez do callback de permissão real.
• Referência gerada desatualizada: a documentação não está vinculada à CI e diverge do pacote publicado.

Uma falha recorrente e transversal é a deriva de permissões: a tarefa inicial encontra um limite, e o operador amplia o acesso antes de determinar se a operação ausente é necessária, suportada ou segura. Isso destrói o valor probatório da recusa e torna os resultados posteriores difíceis de atribuir.

Nota avançada

Gere a documentação a partir de uma representação intermediária versionada que combine rotas registradas, esquemas e testes de contrato executados. Explicações redigidas por humanos podem então enriquecer a referência sem se tornarem uma segunda autoridade para fatos de endpoint.

Guias relacionados

• Como criar uma matriz de testes de permissões do WordPress para agentes de IA
• Como revisar código de plugin WordPress com IA
• Guia da API Abilities do WordPress para fluxos de trabalho de IA
• Como expor uma Ability personalizada do WordPress por MCP

Próxima etapa

Continue com o guia de apoio mais relevante e use o guia de níveis de acesso antes de qualquer tarefa autenticada. Quando o acesso temporário ao WordPress não for mais necessário, conclua revogando a identidade.