As skills Payload CMS ajudam um agente de programação a trabalhar com a configuração do Payload, coleções, campos, hooks, controlo de acesso e APIs. O Payload disponibiliza uma skill de desenvolvimento de aplicações com referências de apoio para essas tarefas. Comece por identificar a versão do seu projeto e depois use a skill para fazer uma pequena alteração que possa verificar.
O resultado útil é um modelo de conteúdo e um comportamento adequados à sua aplicação. Um ficheiro de coleção gerado é apenas parte desse resultado. Os editores precisam dos campos e permissões certos, o frontend precisa do comportamento de consulta pretendido e os dados existentes podem precisar de uma migração.
Instale a skill de desenvolvimento do autor
A página da skill Payload CMS na Thrive apresenta a fonte do autor que foi revista e a respetiva revisão fixada. No seu projeto, execute:
npx usethrive add payload-cms --agent claudeUse --agent codex num projeto Codex. O instalador obtém a pasta completa da skill, incluindo os documentos de referência. Isto instala orientações para o agente; não instala o Payload, não configura uma base de dados nem aplica uma migração.
A entrada do catálogo está fixada numa revisão do repositório do Payload. O ramo main do autor pode diferir da versão da sua aplicação. Verifique package.json e o ficheiro de bloqueio de dependências antes de copiar um exemplo de API. Peça ao agente que identifique a versão principal instalada e confirme que a documentação relevante corresponde a essa versão.
Numa aplicação existente, leia também o ficheiro payload.config do projeto, as definições das coleções, o adaptador de base de dados e as convenções para hooks e controlo de acesso. Um exemplo genérico não deve substituir silenciosamente essas decisões.
Dê ao agente uma tarefa de modelação de conteúdo com limites definidos
Suponha que pretende uma coleção Posts com um título, um resumo e um estado de publicação simples. Defina o que os editores podem fazer e o que os visitantes anónimos podem ler antes de escrever os campos. Eis um contrato ilustrativo:
Configuração de coleção e layout de edição ilustrativos; confira os campos e os padrões de API com a versão do Payload instalada. Abra a ilustração no tamanho original.
Requisito | Comportamento pretendido | Verificação |
|---|---|---|
Título | Texto obrigatório | Um título vazio é rejeitado |
Resumo | Texto curto opcional | Os artigos existentes sem este campo continuam válidos |
Estado de publicação | Um conjunto de valores declarado | Os valores desconhecidos são rejeitados |
Leitura pública | Apenas artigos públicos aprovados | Os dados dos rascunhos não aparecem nas respostas a utilizadores anónimos |
Edição | Apenas editores autorizados | A escrita não autorizada é recusada |
Esta tabela descreve um exemplo, não o comportamento de uma aplicação concluída. Se o seu projeto usa os rascunhos e as versões do Payload, use essas funcionalidades de forma deliberada em vez de criar um segundo campo de estado que as contradiga. Determine como o frontend consulta o conteúdo em rascunho e publicado antes de escolher o modelo.
Comece com uma coleção e um fluxo de edição representativo. Reveja se cada campo pertence a essa coleção ou a um documento relacionado. Um registo reutilizável de autor, por exemplo, pode ser uma relação em vez de campos de nome repetidos, se o produto precisar de partilhar informação sobre os autores.
Leia a referência adequada ao problema
A skill de desenvolvimento do Payload contém referências separadas para que o agente possa consultar os pormenores relevantes para a tarefa. Uma alteração de campo precisa de orientações sobre campos e coleções. Um problema de permissões precisa de orientações sobre controlo de acesso e consultas. Um hook que escreve outro registo precisa de informação sobre hooks e o comportamento das transações.
Problema | Área de referência a consultar |
|---|---|
A validação de um campo tem um resultado inesperado | Campos e coleções |
Um utilizador consegue ver documentos que não deveria ver | Controlo de acesso a coleções ou campos |
Uma chamada à Local API contorna uma restrição | Consultas e opções da Local API |
Um hook repete-se ou perde o contexto da transação | Hooks e propagação do pedido |
O comportamento da base de dados muda entre ambientes | Adaptadores e configuração de migrações |
Peça a passagem específica da fonte que fundamenta uma escolha de API com consequências relevantes. Isso é mais útil do que pedir ao agente que siga «todas as boas práticas», um pedido que não identifica o comportamento de que precisa.
Verifique o controlo de acesso através da API que usa
A documentação de controlo de acesso do Payload explica as restrições por operação e por coleção, global ou campo. Teste o ponto de entrada que a sua aplicação efetivamente usa. Ocultar um botão no painel de administração não substitui uma verificação de permissões na API.
Para operações da Local API que devem respeitar as permissões de um utilizador, o Payload documenta user e overrideAccess: false como opções. Uma consulta pode ter esta forma:
const visiblePosts = await payload.find({
collection: 'posts',
user: requestingUser,
overrideAccess: false,
limit: 10,
})Este é um fragmento de integração, não um programa autónomo executável. Pressupõe uma instância payload inicializada, uma coleção posts declarada e um utilizador identificado pelo fluxo de autenticação da sua aplicação. Verifique estes pressupostos e a versão instalada antes de o aplicar.
Teste um utilizador autorizado, um utilizador não autorizado e um pedido anónimo, se a operação for pública. Nas operações de escrita, confirme tanto a resposta como os dados que ficaram guardados. Uma consulta bem-sucedida por um administrador não prova que um visitante não consegue ler rascunhos.
Trate hooks e migrações como alterações de comportamento
Um hook pode modificar o documento original ou provocar outras operações de escrita. Descreva quando deve ser executado, o que altera e como se comporta quando é chamado repetidamente. Quando a documentação do autor exige que o contexto do pedido seja passado a outra operação, preserve esse contexto para que o trabalho relacionado use a transação pretendida.
Num exemplo como gerar um slug a partir de um título, considere se editar um título deve alterar um URL público existente. Um valor recém-gerado pode parecer correto no editor e, ao mesmo tempo, quebrar ligações de entrada. Escolha o comportamento de que o produto precisa e depois verifique um registo novo e um registo existente.
Uma alteração de esquema pode também precisar de uma migração da base de dados. Peça ao agente que produza e examine a migração relevante através do fluxo documentado para o seu adaptador. Teste-a com dados representativos antes de uma alteração em produção. Registe como são tratados os campos em falta e os valores existentes, em vez de presumir que uma verificação de tipos abrange os registos guardados.
Dê aos editores uma pequena verificação de aceitação
Abra a coleção no painel de administração e conclua o fluxo pretendido: criar, editar, guardar um rascunho se essa função existir e publicar com as permissões aprovadas. Confira os rótulos e as mensagens de validação com as pessoas que os usam. Depois, consulte o conteúdo público através do percurso de API que o frontend efetivamente usa.
Registe os comandos e os resultados que foram verificados. Se não estava disponível uma base de dados ou uma conta de teste, indique que comportamento ficou por verificar. Não descreva uma aplicação como segura só porque a configuração compila.
Para uma migração ao longo de várias sessões, a skill Planning with Files pode manter juntos os mapeamentos de campos, as decisões e os resultados dos testes. Use o plano para acompanhar as evidências; use os testes do Payload e as verificações em execução para determinar o comportamento da aplicação.
