Instruções e memória do projeto project-instructions
O Agente de modernização de experiência sabe apenas o que está na conversa atual e nos arquivos do seu projeto. Para que as convenções do seu projeto sejam seguidas em todas as conversas, escreva-as nos arquivos do Markdown no repositório Git. Este artigo explica como o agente usa esses arquivos e como organizá-los para funcionar com eficiência.
Tudo até Iniciar uma Nova Conversa se aplica a todos os projetos. As habilidades personalizadas são uma opção avançada de que a maioria dos projetos não precisa.
O que o agente lembra memory
O agente não mantém uma memória separada de suas preferências ou de conversas anteriores. Tudo o que ele deve saber em cada conversa deve estar em um arquivo lido. Como os arquivos estão no repositório Git, eles também ajudam os outros desenvolvedores no projeto e em quaisquer outras ferramentas de IA que usem com ele.
Usar AGENTS.md como ponto de entrada agents-md
AGENTS.md é um arquivo Markdown na raiz do repositório. Ele segue um formato aberto que muitos agentes de codificação de IA leem.
Atualmente, o agente usa modelos Claude, que carregam um arquivo chamado CLAUDE.md da raiz do repositório no início de cada conversa. A prática recomendada, que a matriz do AEM segue, é um arquivo CLAUDE.md com esta única linha:
see @AGENTS.md
A referência @ faz o agente carregar AGENTS.md junto com CLAUDE.md e mantê-lo em seu contexto enquanto funciona. Escreva as instruções do projeto em AGENTS.md e deixe CLAUDE.md como esta linha. Suas instruções permanecem no formato aberto que outras ferramentas de IA também leem, e a configuração continua funcionando se o modelo por trás do agente for alterado. Esse modelo é um detalhe de implementação, portanto, não escreva instruções que dependam dele.
Os projetos criados a partir do modelo atual do AEM, para conteúdo baseado em documento ou para criação no Experience Manager, incluem ambos os arquivos e seus AGENTS.md contêm regras gerais de codificação do Edge Delivery Services. Manter ambos os arquivos. Se o projeto foi criado antes de serem incluídos na chapa padrão, peça ao agente para adicioná-los da chapa padrão atual. Para verificar o que foi carregado, inicie uma nova conversa e pergunte quais instruções de projeto ela tem.
Adicione uma pequena seção para seu projeto a AGENTS.md:
- O que é o site, sua origem e seu destino de conteúdo.
- As poucas regras aplicáveis a quase todas as tarefas.
- Um índice dos outros arquivos de instruções, com uma nota sobre quando ler cada um.
Mantenha AGENTS.md curto. O agente carrega tudo em cada conversa, então cada linha ocupa espaço que poderia ser usado para a tarefa. Um texto longo e geral também torna mais difícil para o agente saber quais regras são importantes.
Organize mais arquivos de instruções organize
Coloque os detalhes em arquivos separados, agrupados em uma pasta quando houver vários deles. Por exemplo:
AGENTS.md Entry point: project summary and an index of the files below
project/
blocks.md Blocks, their variants, and how authors fill them
sections-and-templates.md Section styles and page template conventions
design.md Design tokens, typography, spacing, and brand rules
content.md Content, naming, URL, and asset conventions
decisions.md Agreed decisions, with dates and reasons
Referencie cada arquivo de AGENTS.md. O agente abre um arquivo referenciado quando a tarefa precisa dele, de modo que não é necessário nomear o arquivo em cada prompt:
## Project Instructions
This project migrates the WKND sample site to Edge Delivery Services. Content is document-based and edited in Experience Workspace.
Read these files when the task needs them:
| File | Read when |
|---|---|
| `project/blocks.md` | Creating, changing, or using a block |
| `project/sections-and-templates.md` | Building or styling sections or page templates |
| `project/design.md` | Changing colors, typography, spacing, or other styles |
| `project/content.md` | Importing, writing, or restructuring content |
| `project/decisions.md` | Before changing an agreed convention |
When we agree on a new convention, update the matching file in the same change.
Siga estas orientações:
- Um tópico por arquivo. Quando um arquivo ficar longo, divida-o por tópico. Em seguida, o agente lê somente o que a tarefa atual precisa e mantém mais de seu contexto para o próprio trabalho.
- Diga quando ler um arquivo. Uma descrição de uma linha no índice é suficiente para o agente decidir.
- Aponte para o código. O código é a referência para como algo é implementado. Descreva a intenção e as convenções e nomeie o arquivo que as implementa em vez de copiar o código.
- Nenhum segredo. Esses arquivos fazem parte do seu repositório. Nunca coloque senhas, tokens ou outras credenciais neles.
O Edge Delivery Services serve arquivos que são confirmados no repositório, a menos que sejam excluídos no arquivo .hlxignore. O .hlxignore da matriz do AEM exclui arquivos do Markdown e arquivos cujos nomes começam com um ponto. Grave arquivos de instrução no Markdown para que permaneçam excluídos; arquivos em outros formatos, como JSON ou texto sem formatação, podem ser solicitados dos URLs do site. O console não mostra .hlxignore, portanto, se precisar alterá-lo, edite-o no GitHub ou em um clone local.
Convenções de conteúdo do documento content-conventions
Os autores funcionam melhor com estruturas de conteúdo simples: um cabeçalho, algum texto, uma imagem e um link, sem campos extras. Para manter o conteúdo simples, a implementação depende de convenções, como qual conteúdo é opcional ou como a posição de um elemento altera sua função. Autores, desenvolvedores e o agente só poderão seguir essas convenções se elas forem anotadas. O Modelo de David descreve as regras gerais para essas estruturas; faça referência a ele nas suas convenções de conteúdo e anote apenas as decisões do seu projeto.
As convenções que merecem ser documentadas incluem:
- Variações de conteúdo de um bloco. Para um teaser, por exemplo: se a imagem e a call to action são opcionais, como os autores escolhem um título maior ou menor e se um parágrafo curto antes do título se torna uma sobrancelha, um pequeno rótulo acima do título.
- Bloquear variantes. Quais variantes existem e quando usar cada uma.
- Estilos de seção. Quais estilos de seção existem, como um plano de fundo escuro ou uma coluna estreita, o que eles fazem e quais blocos funcionam dentro deles. Algumas seções podem esperar que um bloco específico atinja um efeito específico.
- Modelos de página. Convenções de conteúdo que as páginas de um modelo devem seguir, por exemplo, uma página de artigo que começa com um herói e termina com links relacionados.
- Regras de codificação, design e conteúdo. Nomeação, tokens de design, regras de marca, convenções de URL e ativo e qualquer outra coisa que um novo membro da equipe precisaria saber.
Uma entrada para um bloco pode ser tão curta quanto esta:
### Teaser
Promotes one page or offer.
| Content | Required | Convention |
|---|---|---|
| Image | No | Without an image, the text spans the full width. |
| Eyebrow | No | A short paragraph before the heading becomes the eyebrow. |
| Title | Yes | Heading 2 for the standard size, Heading 3 for a compact teaser. |
| Text | No | One or two short paragraphs. |
| Links | No | A bold link becomes a primary button, an italic link a secondary button. |
Variants: `dark` (light text on a dark background).
Works in sections: default, `dark`, and `narrow`.
Quando a migração cria um bloco, o agente também grava um README para desenvolvedores e um guia de criação para autores. Consulte O que o agente fornece com um bloco. Faça referência a esses arquivos a partir do índice, em vez de repeti-los.
Alterar como o agente responde reply-style
Como o agente grava suas respostas é uma convenção como qualquer outra, para que você possa defini-la em AGENTS.md. Por exemplo, se você não quiser que cada resposta termine sugerindo as próximas etapas ou quiser respostas mais curtas, diga:
## How to answer
- Keep answers short: what you changed, where, and anything that needs my decision.
- Don't suggest next steps unless I ask for them.
- Answer in German. Keep code, file names, and commit messages in English.
Essas instruções moldam o texto das respostas do agente. As sugestões que o console mostra em Próximas etapas são geradas separadamente, para que ainda sejam exibidas e você possa ignorá-las.
Deixar registro de cada solicitação trace
Seu histórico de Git e o histórico de versões do seu conteúdo são o registro do que o agente fez; consulte Rastrear o que o agente fez. Para facilitar o acompanhamento desse registro, adicione uma regra permanente a AGENTS.md para que cada solicitação deixe sua própria confirmação e carregamento de conteúdo:
## After Each Request
- Commit your changes with a message that summarizes my request.
- Push the commit to the `develop` branch. Never push to `main`.
- If pages changed, list them and ask whether to upload them to Experience Workspace.
- A publicação precisa de Permitir que o LLM use minhas credenciais do Git ou a permissão de credenciais do Adobe para repositórios conectados por meio do Cloud Manager. Consulte Página de configurações. Se a permissão não estiver disponível para você, envie a si mesmo por push com Sincronização > Push > Código após cada solicitação.
- O carregamento precisa da permissão de credenciais do Adobe. O console permite que o agente carregue conteúdo somente quando a mensagem o solicitar ou quando você concordar, de modo que a regra faz o agente perguntar e a resposta aprova o carregamento. Para o conteúdo na instância do autor, faça upload das páginas você mesmo.
- A ramificação de trabalho mantém os envios por push do agente longe do código do site ativo. Um desenvolvedor revisa as alterações e as mescla em
maincom uma solicitação de pull, conforme descrito em Contribuição mais ampla, Mesmo controle de produção.
Deixe o agente manter os arquivos maintain
Você não precisa gravar esses arquivos manualmente. Peça ao agente para criá-los e atualizá-los e, em seguida, revise-os como faria com o código de revisão.
-
Crie a primeira versão depois que os primeiros modelos e blocos existirem:
Documente os blocos, variantes, estilos de seção, modelos de página e tokens de design deste projeto a partir do código e do conteúdo importado. Coloque cada tópico em seu próprio arquivo curto em
project/e adicione um índice com quando ler cada arquivo emAGENTS.md. -
Mantenha-os atualizados. Adicione uma regra permanente a
AGENTS.md, como a última linha do exemplo acima, para que o agente atualize os arquivos sempre que criar ou alterar um bloco, estilo de seção ou modelo. -
Verifique-as. O agente pode registrar uma convenção que ele assumiu em vez de uma que você concordou. Corrija tudo o que estiver errado e pergunte de vez em quando:
Verificar os arquivos em
project/em relação ao código e conteúdo atuais. Corrija declarações que estão desatualizadas e divida qualquer arquivo que tenha se tornado muito longo. -
Envie a eles o código por push para que sua equipe e conversas futuras recebam as mesmas instruções.
Iniciar uma nova conversa new-conversation
Como o agente carrega o AGENTS.md automaticamente, uma nova conversa começa com as instruções do projeto e localiza os outros arquivos por meio do índice. Iniciar uma nova conversa com Limpar chat quando uma conversa ficar longa ou tiver sido removida da tarefa. Antes de limpá-la, peça ao agente para salvar o que é importante:
Antes que eu limpe o bate-papo, registre as decisões e convenções que concordamos nesta conversa nos arquivos do projeto e liste o que você alterou.
Limpar remove as mensagens anteriores e não pode ser desfeito. Para manter a conversa, selecione Baixar chat primeiro.
Para uma transferência completa para outra pessoa ou equipe, consulte Reter contexto para pessoas e agentes.
Avançado: habilidades personalizadas custom-skills
A maioria dos projetos não precisa de habilidades personalizadas. As habilidades incorporadas do agente abrangem migração, design, desenvolvimento de blocos e documentação, e melhoram a cada versão. Consulte as notas de versão.
Uma habilidade é um conjunto de instruções para um tipo de tarefa, muitas vezes passo a passo. Funciona como uma seção de AGENTS.md, com uma diferença: o agente lê uma habilidade somente quando realiza aquela tarefa, em vez de carregá-la em todas as conversas. Considere uma habilidade personalizada quando:
- As instruções para uma tarefa recorrente tornam
AGENTS.mdlongo. - O agente continua lutando com uma tarefa específica e repetida e precisa de etapas precisas, por exemplo, extrair imagens de uma galeria incomum no site de origem ou manipular vídeos incorporados.
Para adicionar uma habilidade personalizada:
- Peça ao agente para criar a habilidade em sua própria pasta em
.claude/skills/, como.claude/skills/gallery-images/SKILL.md. O arquivo começa com um cabeçalho curto que dá à habilidade umnamee umdescriptionde quando usá-la. As etapas, as verificações que mostram que a tarefa foi bem-sucedida e um pequeno exemplo segue. - Peça ao agente que confirme e empurre a habilidade. As exibições de arquivos do console não podem preparar pastas cujos nomes começam com um ponto; Exibições de Código explica a permissão que o agente precisa para enviá-las e o que fazer sem ela.
- Teste a habilidade em uma nova conversa. Peça por nome, como “Use a habilidade de imagens da galeria para importar esta página”. Para verificar se o agente a encontrou, peça para ele ler a habilidade e informar seu nome e descrição. Uma lista das habilidades do agente abrange suas habilidades incorporadas, de modo que não mostra se a sua carregou.
O cabeçalho de SKILL.md tem esta aparência:
---
name: gallery-images
description: Extract the images of the source site's photo galleries, which a script loads. Use when importing pages that contain a gallery.
---
Você não precisa listar a habilidade em AGENTS.md. O agente vê a descrição de cada habilidade na pasta e lê uma habilidade quando uma tarefa corresponde a ela. Portanto, descreva com precisão quando usá-la.
Uma boa maneira de escrever uma habilidade é pedir ao agente para ela logo após ela ter concluído a tarefa corretamente:
Escreva uma habilidade no
.claude/skills/gallery-images/SKILL.mdque capture como você acabou de extrair as imagens da galeria, incluindo as verificações que você usou. Em seguida, confirme e envie por push.
Habilidades personalizadas não substituem ou alteram as habilidades integradas do agente. Quando uma nova versão lida com uma tarefa nativamente, remova a habilidade personalizada que a abordou.
Por que .claude/skills skills-location
Os agentes baseados em Claude, como o que o console executa atualmente, descobrem habilidades por conta própria em uma pasta .claude/skills/ na raiz do repositório. Uma habilidade é carregada nativamente: o agente vê somente a descrição curta da habilidade até que uma tarefa corresponda a ela, pode ser solicitada por nome e aplica configurações do cabeçalho da habilidade, como quais ferramentas ele pode usar. Funciona de forma mais confiável do que uma pasta visível, como skills/ que AGENTS.md indexa, na qual o agente deve ler o índice e decidir abrir o arquivo.
O nome da pasta começa com um ponto, que tem dois efeitos:
- Seu site não atende a ele, pois as
.hlxignoreregras descritas acima o excluem. - As exibições de arquivos do console não o mostram. Para revisar uma habilidade, peça ao agente para mostrá-la ou abri-la no GitHub.
Se o seu projeto já tiver habilidades em uma pasta visível que AGENTS.md indexa, elas continuarão funcionando. Para carregá-las nativamente, peça ao agente para movê-las para .claude/skills/, adicionar o cabeçalho e remover as linhas de índice.