Istruzioni del progetto e memoria project-instructions
L’agente di modernizzazione esperienza conosce solo ciò che si trova nella conversazione corrente e nei file del progetto. Per fare in modo che segua le convenzioni del progetto in ogni conversazione, scrivile nei file Markdown nell’archivio Git. Questo articolo spiega come l’agente utilizza tali file e come organizzarli in modo che funzionino in modo efficiente.
Fino a Avvia una nuova conversazione si applica a ogni progetto. Le abilità personalizzate sono un’opzione avanzata di cui la maggior parte dei progetti non ha bisogno.
Aspetti che l’agente ricorda memory
L’agente non conserva una memoria separata delle tue preferenze o delle conversazioni precedenti. Tutto ciò che deve sapere in ogni conversazione deve trovarsi in un file che legge. Poiché i file si trovano nell’archivio Git, aiutano anche gli altri sviluppatori nel progetto e in tutti gli altri strumenti di intelligenza artificiale utilizzati con esso.
Utilizzare AGENTS.md come punto di ingresso agents-md
AGENTS.md è un file Markdown nella directory principale dell’archivio. Segue un formato aperto letto da molti agenti di codifica IA.
L’agente utilizza attualmente modelli Claude, che caricano un file denominato CLAUDE.md dalla directory principale dell’archivio all’inizio di ogni conversazione. La best practice, seguita da AEM boilerplate, è un file CLAUDE.md con questa riga singola:
see @AGENTS.md
Il riferimento @ fa caricare l’agente AGENTS.md insieme a CLAUDE.md e lo mantiene nel suo contesto mentre funziona. Scrivere le istruzioni del progetto in AGENTS.md e lasciare CLAUDE.md come riga singola. Le istruzioni rimangono quindi nel formato aperto letto anche da altri strumenti di intelligenza artificiale e la configurazione continua a funzionare se il modello dietro l’agente cambia. Tale modello è un dettaglio di implementazione, quindi non scrivere istruzioni che dipendono da esso.
I progetti creati dalla piattaforma AEM corrente, per contenuti basati su documenti o per l’authoring Experience Manager, includono entrambi i file e AGENTS.md contengono regole generali di codifica Edge Delivery Services. Mantieni entrambi i file. Se il progetto è stato creato prima che la piastra di contenimento li includesse, chiedi all’agente di aggiungerli dalla piastra di contenimento corrente. Per verificare cosa è stato caricato, inizia una nuova conversazione e chiedi di quali istruzioni di progetto dispone.
Aggiungi una breve sezione per il progetto a AGENTS.md:
- Descrizione del sito, origine e destinazione del contenuto 🔗.
- Le poche regole che si applicano a quasi ogni attività.
- Un indice degli altri file di istruzioni, con una nota su quando leggerli.
Mantieni AGENTS.md breve. L’agente porta con sé tutto in ogni conversazione, in modo che ogni fila occupi spazio che potrebbe usare per il compito. Un testo lungo e generale rende anche più difficile per l’agente dire quali regole contano.
Organizzazione di ulteriori file di istruzioni organize
Inserisci i dettagli in file separati, raggruppati in una cartella quando ce ne sono diversi. Ad esempio:
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
Fare riferimento a ogni file da AGENTS.md. L’agente apre un file di riferimento quando necessario per l’attività, quindi non è necessario assegnare un nome al file in ogni 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.
Segui queste linee guida:
- Un argomento per file. Quando un file diventa lungo, suddividerlo per argomento. L’agente legge quindi solo ciò di cui l’attività corrente ha bisogno e mantiene una maggiore quantità di contesto per il lavoro stesso.
- Indica quando leggere un file. Una descrizione di una riga nell’indice è sufficiente per consentire all’agente di decidere.
- Puntare al codice. Il codice è il riferimento per l’implementazione di un elemento. Descrivi l’intento e le convenzioni, quindi denomina il file che li implementa anziché copiare il codice.
- Nessun segreto. Questi file fanno parte dell’archivio. Non inserire mai password, token o altre credenziali.
Edge Delivery Services fornisce i file di cui è stato eseguito il commit nell’archivio, a meno che non vengano esclusi nel file .hlxignore. Il .hlxignore della boilerplate di AEM esclude i file Markdown e i file i cui nomi iniziano con un punto. Scrivere i file di istruzioni in Markdown in modo che rimangano esclusi; i file in altri formati, come JSON o testo normale, potrebbero altrimenti essere richiesti dagli URL del sito. La console non mostra .hlxignore, quindi se devi modificarla, modificala in GitHub o in un clone locale.
Convenzioni contenuto documento content-conventions
Gli autori funzionano al meglio con strutture di contenuto snelle: un titolo, del testo, un’immagine e un collegamento, senza campi aggiuntivi. Per mantenere il contenuto così semplice, l’implementazione si basa su convenzioni, ad esempio il contenuto facoltativo o il modo in cui la posizione di un elemento cambia il suo ruolo. Autori, sviluppatori e agenti possono seguire queste convenzioni solo se sono stati scritti. Il modello di David descrive le regole generali per tali strutture; fai riferimento alle convenzioni di contenuto e annota solo le decisioni del tuo progetto.
Le convenzioni che vale la pena documentare includono:
- Varianti di contenuto di un blocco. Ad esempio, per un teaser: se l’immagine e il call to action sono facoltativi, in che modo gli autori scelgono un titolo più o meno grande e se un breve paragrafo prima del titolo diventa una sopracciglia, una piccola etichetta sopra il titolo.
- Blocca varianti. Quali varianti esistono e quando usarle.
- Stili sezione. Quali stili di sezione esistono, ad esempio uno sfondo scuro o una colonna stretta, cosa fanno e quali blocchi funzionano al loro interno. Alcune sezioni possono prevedere che un blocco specifico produca un effetto particolare.
- Modelli di pagina. Convenzioni di contenuto che le pagine di un modello devono seguire, ad esempio una pagina di articolo che inizia con un protagonista e termina con collegamenti correlati.
- Regole di codifica, progettazione e contenuto. Denominazione, token di progettazione, regole del brand, convenzioni URL e risorse e tutto ciò che un nuovo membro del team dovrebbe sapere.
Una voce per un blocco può essere breve come questo:
### 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 la migrazione crea un blocco, l’agente scrive anche un README per gli sviluppatori e una guida per l’authoring per gli autori. Vedi Cosa fornisce l’agente con un blocco. Fai riferimento a tali file dal tuo indice anziché ripeterli.
Modifica la risposta dell’agente reply-style
Il modo in cui l’agente scrive le proprie risposte è una convenzione come qualsiasi altra, quindi è possibile impostarla in AGENTS.md. Ad esempio, se non vuoi che termini ogni risposta suggerendo i passaggi successivi, o desideri risposte più brevi, dì:
## 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.
Queste istruzioni modellano il testo delle risposte dell’agente. I suggerimenti visualizzati nella console in Passaggi successivi vengono generati separatamente, quindi vengono comunque visualizzati e possono essere ignorati.
Lascia un record di ogni richiesta trace
La cronologia Git e la cronologia delle versioni del contenuto sono la registrazione di ciò che l’agente ha fatto; vedi Individuare le operazioni eseguite dall’agente. Per semplificare la gestione del record, aggiungere una regola permanente a AGENTS.md in modo che ogni richiesta lasci il proprio commit e caricamento del contenuto:
## 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.
- Il push richiede Consenti a LLM di utilizzare le mie credenziali Git o l’autorizzazione delle credenziali Adobe per gli archivi connessi tramite Cloud Manager. Consulta Pagina impostazioni. Se l’autorizzazione non è disponibile, invia un messaggio push con Sincronizza > Invia > Codice dopo ogni richiesta.
- Il caricamento richiede l’autorizzazione delle credenziali di Adobe. La console consente all’agente di caricare il contenuto solo quando il messaggio lo richiede o se lo accetti quando lo richiede, quindi la regola dispone dell’agente che lo richiede e la risposta approva il caricamento. Per i contenuti nell’istanza di authoring, carica le pagine da solo.
- Il ramo di lavoro mantiene gli push dell’agente lontano dal codice del sito attivo. Uno sviluppatore esamina le modifiche e le unisce in
maincon una richiesta pull, come descritto in Contributo più ampio, stesso controllo di produzione.
Consenti all’agente di gestire i file maintain
Non è necessario scrivere questi file manualmente. Chiedi all’agente di crearli e aggiornarli, quindi rivedili come rivederesti il codice.
-
Crea la prima versione una volta che esistono i primi modelli e blocchi:
Documenta i blocchi, le varianti, gli stili di sezione, i modelli di pagina e i token di progettazione di questo progetto dal codice e dal contenuto importato. Inserire ogni argomento nel proprio file breve in
project/e aggiungere un indice con la data di lettura di ogni file inAGENTS.md. -
Mantenili aggiornati. Aggiungere una regola permanente a
AGENTS.md, ad esempio l’ultima riga dell’esempio precedente, in modo che l’agente aggiorni i file ogni volta che crea o modifica un blocco, uno stile di sezione o un modello. -
Controllali. L’agente può registrare una convenzione che ha assunto invece di una che hai accettato. Correggi tutto ciò che non va e chiedi di tanto in tanto:
Controllare i file in
project/rispetto al codice e al contenuto correnti. Correggi le istruzioni non aggiornate e dividi i file che sono diventati troppo lunghi. -
Invia il codice in modo che il tuo team e le conversazioni future ricevano le stesse istruzioni.
Avvia una nuova conversazione new-conversation
Poiché l’agente carica automaticamente AGENTS.md, inizia una nuova conversazione con le istruzioni del progetto e trova gli altri file tramite l’indice. Avvia una nuova conversazione con Cancella chat quando una conversazione è diventata lunga o si è allontanata dall’attività. Prima di cancellare il contenuto, chiedi all’agente di salvare quanto conta:
Prima di cancellare la chat, registra le decisioni e le convenzioni che abbiamo concordato in questa conversazione nei file del progetto, e elenca quello che hai cambiato.
La cancellazione rimuove i messaggi precedenti e non può essere annullata. Per mantenere la conversazione, selezionare Scarica chat.
Per un passaggio completo a un’altra persona o team, vedere Mantieni contesto per persone e agenti.
Avanzate: abilità personalizzate custom-skills
La maggior parte dei progetti non richiede competenze personalizzate. Le competenze integrate dell’agente riguardano la migrazione, la progettazione, lo sviluppo di blocchi e la documentazione, e migliorano con ogni versione. Consulta le note sulla versione.
Un’abilità è un insieme di istruzioni per un tipo di attività, spesso passo dopo passo. Funziona come una sezione di AGENTS.md, con una differenza: l’agente legge un’abilità solo quando esegue tale attività, invece di portarla in ogni conversazione. Considera un’abilità personalizzata quando:
- Le istruzioni per un’attività ricorrente rendono
AGENTS.mdlungo. - L’agente continua a lottare con un’attività specifica e ripetuta e ha bisogno di passaggi precisi, per esempio l’estrazione di immagini da una galleria insolita sul sito di origine o la gestione di video incorporati.
Per aggiungere un’abilità personalizzata:
- Chiedere all’agente di creare l’abilità nella propria cartella in
.claude/skills/, ad esempio.claude/skills/gallery-images/SKILL.md. Il file inizia con una breve intestazione che fornisce all’abilità unnamee undescriptiondi quando utilizzarla. Seguono la procedura, i controlli che mostrano l’attività riuscita e un breve esempio. - Chiedi all’agente di eseguire il commit e di inviare l’abilità. Nelle visualizzazioni file della console non è possibile inserire nell’area intermedia le cartelle il cui nome inizia con un punto. Visualizzazioni codice spiega l’autorizzazione necessaria all’agente per inviarle e cosa fare senza di esse.
- Prova l’abilità in una nuova conversazione. Richiedi per nome, ad esempio “Utilizza l’abilità per le immagini della galleria per importare questa pagina”. Per verificare che l’agente l’abbia trovata, chiedi di leggere l’abilità e indicane il nome e la descrizione. Un elenco delle abilità dell’agente include le sue abilità incorporate, quindi non mostra se il tuo è caricato.
L’intestazione di SKILL.md è simile alla seguente:
---
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.
---
Non è necessario elencare l’abilità in AGENTS.md. L’agente visualizza la descrizione di ogni abilità nella cartella e legge un’abilità quando un’attività corrisponde a essa; descrivi quindi con precisione quando utilizzarla.
Un buon modo per scrivere un’abilità è quello di chiedere all’agente di per essa subito dopo aver completato correttamente l’attività:
Scrivere un’abilità in
.claude/skills/gallery-images/SKILL.mdche acquisisce il modo in cui sono state estratte le immagini della raccolta, inclusi i controlli utilizzati. Poi esegui il commit e lo push.
Le abilità personalizzate non sostituiscono o modificano le abilità incorporate dell’agente. Quando una nuova versione gestisce un’attività in modo nativo, rimuovi l’abilità personalizzata che l’ha coperta.
Perché .claude/skills skills-location
Gli agenti basati su Claude, come quello attualmente in esecuzione nella console, rilevano autonomamente le abilità in una cartella .claude/skills/ nella directory principale dell’archivio. Un’abilità viene caricata in modo nativo: l’agente visualizza solo la breve descrizione dell’abilità finché un’attività non la corrisponde, può esserne richiesta una per nome e applica le impostazioni dall’intestazione dell’abilità, ad esempio quali strumenti può utilizzare. Questo funziona in modo più affidabile di una cartella visibile come skills/ che AGENTS.md indicizza, in cui l’agente deve leggere l’indice e decidere di aprire il file.
Il nome della cartella inizia con un punto, che ha due effetti:
- Il tuo sito non lo gestisce, perché le regole
.hlxignoredescritte sopra lo escludono. - Le visualizzazioni file della console non vengono visualizzate. Per rivedere un’abilità, chiedi all’agente di mostrarla o aprila in GitHub.
Se il progetto presenta già delle abilità in una cartella visibile indicizzata da AGENTS.md, queste continueranno a funzionare. Per caricarli in modo nativo, chiedere all’agente di spostarli in .claude/skills/, aggiungere l’intestazione e rimuovere le righe di indice.