Instructions et mémoire du projet project-instructions

L’agent de modernisation de l’expérience ne sait que ce qui se trouve dans la conversation en cours et dans les fichiers de votre projet. Pour qu’il suive les conventions de votre projet dans chaque conversation, écrivez-les dans les fichiers Markdown de votre référentiel Git. Cet article explique comment l’agent utilise ces fichiers et comment les organiser pour qu’ils fonctionnent efficacement.

Tout ce qui peut aller jusqu’à Démarrer une nouvelle conversation s’applique à chaque projet. Les compétences personnalisées sont une option avancée dont la plupart des projets n’ont pas besoin.

Ce dont se souvient l’agent memory

Source
Ce qu’il contient
Combien de temps dure-t-il ?
Compétences intégrées
Workflows de l’agent pour la migration, la conception, le développement de blocs, la documentation et d’autres tâches.
Fourni par Adobe et mis à jour à chaque version.
Conversation actuelle
Vos demandes, les réponses de l’agent, ce qu’il a lu et modifié.
La console maintient la conversation de votre projet afin que vous puissiez la poursuivre. Lorsqu’une conversation est longue, les messages précédents sont résumés et les détails peuvent être perdus. Effacer la conversation lance une nouvelle conversation sans l’historique précédent.
Fichiers dans l’espace de travail de la console
Le référentiel Git extrait, la copie de travail du contenu importé et les fichiers de migration temporaires.
L’espace de travail est une copie de travail. Le code que vous transmettez reste dans votre référentiel Git et le contenu que vous chargez reste dans votre destination de contenu.

L’agent ne conserve pas une mémoire séparée de vos préférences ou des conversations antérieures. Tout ce qu’il doit savoir dans chaque conversation doit se trouver dans un fichier qu’il lit. Comme les fichiers se trouvent dans votre référentiel Git, ils aident également les autres développeurs dans le projet et tout autre outil d’IA qu’ils utilisent avec celui-ci.

Utiliser AGENTS.md comme point d’entrée agents-md

AGENTS.md est un fichier Markdown à la racine du référentiel. Il suit un format ouvert que de nombreux agents de codage d’IA lisent.

L’agent utilise actuellement des modèles Claude, qui chargent un fichier nommé CLAUDE.md à partir de la racine du référentiel au début de chaque conversation. La bonne pratique, que le modèle AEM suit, consiste à utiliser un fichier CLAUDE.md sur une seule ligne :

see @AGENTS.md

La référence @ fait charger l’agent AGENTS.md avec CLAUDE.md et le conserve dans son contexte pendant son fonctionnement. Écrivez les instructions de votre projet dans AGENTS.md et laissez CLAUDE.md sur cette ligne. Vos instructions restent alors au format ouvert, que d’autres outils d’IA lisent également, et la configuration continue de fonctionner si le modèle derrière l’agent change. Ce modèle est un détail d’implémentation. N’écrivez donc pas d’instructions qui en dépendent.

Les projets créés à partir du standard AEM actuel, pour le contenu basé sur des documents ou pour la création dans Experience Manager, incluent les deux fichiers et leur AGENTS.md contient les règles générales de codage Edge Delivery Services. Conserver les deux fichiers. Si votre projet a été créé avant que le standard ne les inclue, demandez à l’agent de les ajouter à partir du standard actuel. Pour vérifier ce qu’il a chargé, démarrez une nouvelle conversation et demandez-lui quelles instructions de projet elle contient.

Ajoutez une courte section pour votre projet à AGENTS.md :

  • Qu’est-ce que le site, sa source et sa destination de contenu ?
  • Les quelques règles qui s’appliquent à presque toutes les tâches.
  • Index des autres fichiers d’instructions, avec une note sur le moment de lecture de chacun.

Conserver AGENTS.md court. L’agent emporte tout dans chaque conversation, donc chaque ligne prend de la place qu’il pourrait utiliser pour la tâche. Le texte long et général rend également plus difficile pour l’agent de dire quelles règles comptent.

Organiser d’autres fichiers d’instructions organize

Placez les détails dans des fichiers distincts, regroupés dans un dossier lorsqu’il en existe plusieurs. Par exemple :

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

Référencez chaque fichier de AGENTS.md. L’agent ouvre un fichier référencé lorsque la tâche le nécessite, de sorte que vous n’avez pas besoin de nommer le fichier à chaque invite :

## 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.

Suivez ces instructions :

  • Une rubrique par fichier. Lorsqu’un fichier croît longtemps, fractionnez-le par rubrique. L’agent ne lit alors que ce dont la tâche en cours a besoin et conserve une plus grande partie de son contexte pour le travail lui-même.
  • Dites quand lire un fichier. Une description d’une seule ligne dans l’index suffit à l’agent pour prendre une décision.
  • Pointez sur le code. Le code est la référence pour la manière dont quelque chose est implémenté. Décrivez l’intention et les conventions, et nommez le fichier qui les met en œuvre plutôt que de copier du code.
  • Aucun secret. Ces fichiers font partie de votre référentiel. N’y placez jamais de mots de passe, de jetons ou d’autres informations d’identification.

Edge Delivery Services sert les fichiers validés dans le référentiel, sauf s’ils sont exclus dans le fichier .hlxignore. Le .hlxignore du modèle standard d’AEM exclut les fichiers Markdown et les fichiers dont le nom commence par un point. Écrivez les fichiers d’instructions en Markdown de sorte qu’ils restent exclus ; les fichiers dans d’autres formats, tels que JSON ou texte brut, pourraient autrement être demandés à partir des URL du site. La console n’affiche pas .hlxignore. Si vous devez donc le modifier, modifiez-le dans GitHub ou dans un clone local.

Conventions de contenu du document content-conventions

Les auteurs fonctionnent mieux avec des structures de contenu allégées : un en-tête, du texte, une image et un lien, sans champs supplémentaires. Pour que le contenu reste aussi simple, l’implémentation s’appuie sur des conventions, telles que le contenu facultatif ou la manière dont la position d’un élément modifie son rôle. Les auteurs, les développeurs et l’agent ne peuvent respecter ces conventions que si elles sont écrites. Le modèle de David décrit les règles générales de ces structures ; référencez-le à partir de vos conventions de contenu et notez uniquement les décisions de votre projet.

Les conventions qui méritent d’être documentées incluent :

  • Variations de contenu d’un bloc. Pour un teaser, par exemple : si l’image et le call to action sont facultatifs, comment les auteurs choisissent un titre plus grand ou plus petit, et si un court paragraphe avant le titre devient un sourcil, une petite étiquette au-dessus du titre.
  • Bloquer les variantes. Les variantes qui existent et quand les utiliser.
  • Styles de section. Quels styles de section existent, par exemple un arrière-plan sombre ou une colonne étroite, ce qu’ils font et quels blocs fonctionnent à l’intérieur d’eux ? Certaines sections peuvent s’attendre à ce qu’un bloc spécifique produise un effet particulier.
  • Modèles de page. Conventions de contenu que les pages d’un modèle doivent respecter ; par exemple, une page d’article qui commence par un héros et se termine par des liens connexes.
  • Règles de codage, de conception et de contenu. Dénomination, jetons de conception, règles de marque, conventions d’URL et de ressources, ainsi que tout autre élément que le nouveau membre de l’équipe doit connaître.

Une entrée pour un bloc peut être aussi courte que :

### 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`.

Lorsque la migration crée un bloc, l’agent écrit également un fichier README pour les développeurs et un guide de création pour les auteurs. Voir Ce que l’agent fournit avec un bloc. Référencez ces fichiers à partir de votre index plutôt que de les répéter.

Modifier la réponse de l’agent reply-style

La façon dont l’agent écrit ses réponses est une convention comme une autre, vous pouvez donc la définir dans AGENTS.md. Par exemple, si vous ne souhaitez pas qu’il termine chaque réponse en suggérant les étapes suivantes, ou si vous souhaitez des réponses plus courtes, dites-le :

## 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.

Ces instructions façonnent le texte des réponses de l’agent. Les suggestions affichées par la console sous Étapes suivantes sont générées séparément, elles apparaissent donc toujours et vous pouvez les ignorer.

Laisser un enregistrement de chaque demande trace

Votre historique Git et l’historique des versions de votre contenu constituent l’enregistrement de ce que l’agent a fait. Consultez Suivi de ce que l’agent a fait. Pour faciliter le suivi de cet enregistrement, ajoutez une règle permanente à AGENTS.md afin que chaque requête laisse sa propre validation et son propre chargement de contenu :

## 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.
  • L’envoi nécessite Autoriser LLM à utiliser mes informations d’identification Git ou l’autorisation Adobe pour les référentiels connectés via Cloud Manager. Voir La Page Paramètres. Si vous ne disposez pas de l’autorisation, effectuez une synchronisation Sync > Push > Code après chaque demande.
  • Le chargement de nécessite l’autorisation des informations d’identification Adobe. La console permet à l’agent de charger le contenu uniquement lorsque votre message le demande ou que vous êtes d’accord lorsqu’il le demande, de sorte que la règle autorise la demande de l’agent et que votre réponse approuve le chargement. Pour le contenu sur l’instance d’auteur, chargez les pages vous-même.
  • La branche de travail éloigne les notifications push de l’agent du code du site actif. Un développeur examine les modifications et les fusionne dans main avec une demande d’extraction, comme décrit dans Contribution plus large, même contrôle de production.

Laisser l’agent gérer les fichiers maintain

Vous n’avez pas besoin d’écrire ces fichiers à la main. Demandez à l’agent de les créer et de les mettre à jour, puis passez-les en revue comme vous le feriez pour le code.

  • Créez la première version une fois que les premiers modèles et blocs existent :

    Documentez les blocs, variantes, styles de section, modèles de page et jetons de conception de ce projet à partir du code et du contenu importé. Placez chaque rubrique dans son propre fichier court sous project/ et ajoutez un index avec quand lire chaque fichier dans AGENTS.md.

  • Conservez-les à jour. Ajoutez une règle permanente à AGENTS.md, telle que la dernière ligne de l’exemple ci-dessus, de sorte que l’agent mette à jour les fichiers chaque fois qu’il crée ou modifie un bloc, un style de section ou un modèle.

  • Vérifiez-les. L’agent peut enregistrer une convention qu’il a supposée plutôt qu’une convention que vous avez acceptée. Corrigez tout ce qui ne va pas et demandez de temps en temps :

    Vérifiez les fichiers sous project/ par rapport au code et au contenu actuels. Corrigez les instructions obsolètes et fractionnez les fichiers dont la taille a augmenté trop longtemps.

  • Envoyez-les avec le code afin que votre équipe et les conversations futures obtiennent les mêmes instructions.

Démarrer une nouvelle conversation new-conversation

Comme l’agent charge AGENTS.md automatiquement, une nouvelle conversation commence avec les instructions de votre projet et recherche les autres fichiers dans l’index. Commencez une nouvelle conversation avec Effacer la conversation lorsqu’une conversation est devenue longue ou s’est éloignée de la tâche. Avant de l’effacer, demandez à l’agent d’enregistrer ce qui importe :

Avant d’effacer la conversation, enregistrez les décisions et conventions sur lesquelles nous nous sommes mis d’accord au cours de cette conversation dans les fichiers du projet et répertoriez les modifications que vous avez apportées.

L’effacement supprime les messages précédents et ne peut pas être annulé. Pour conserver la conversation, sélectionnez d’abord Télécharger le chat.

Pour un transfert complet à une autre personne ou équipe, consultez Conserver le contexte pour les personnes et les agents.

Avancé : compétences personnalisées custom-skills

La plupart des projets n’ont pas besoin de compétences personnalisées. Les compétences intégrées de l’agent couvrent la migration, la conception, le développement de blocs et la documentation. Elles s’améliorent à chaque version. Voir les notes de mise à jour.

Une compétence est un ensemble d’instructions pour un type de tâche, souvent étape par étape. Cela fonctionne comme une section de AGENTS.md, à une différence près : l’agent lit une compétence uniquement lorsqu’il effectue cette tâche, au lieu de la transmettre dans chaque conversation. Envisagez une compétence personnalisée lorsque :

  • Les instructions pour une tâche récurrente font AGENTS.md long.
  • L’agent continue à se débattre avec une tâche spécifique et répétée et a besoin d’étapes précises, par exemple extraire des images d’une galerie inhabituelle sur le site source ou gérer des vidéos incorporées.

Pour ajouter une compétence personnalisée :

  1. Demandez à l’agent de créer la compétence dans son propre dossier sous .claude/skills/, par exemple .claude/skills/gallery-images/SKILL.md. Le fichier commence par un en-tête court qui donne à la compétence un name et un description du moment où l’utiliser. Les étapes, les vérifications qui montrent la réussite de la tâche et un court exemple suivent.
  2. Demandez à l’agent de valider et de transmettre la compétence. Les vues de fichiers de la console ne peuvent pas préparer des dossiers dont les noms commencent par un point ; Vues de code explique l’autorisation dont l’agent a besoin pour les pousser et ce qu’il faut faire sans cela.
  3. Testez les compétences dans une nouvelle conversation. Demandez-le par nom, par exemple « Utilisez la compétence galerie-images pour importer cette page ». Pour vérifier que l’agent l’a trouvée, demandez-lui de lire la compétence et de vous dire son nom et sa description. Une liste des compétences de l’agent couvre ses compétences intégrées, de sorte qu’elle n’indique pas si les vôtres sont chargées.

L’en-tête de SKILL.md ressemble à ceci :

---
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.
---

Vous n’avez pas besoin de répertorier la compétence dans AGENTS.md. L’agent voit la description de chaque compétence dans le dossier et lit une compétence lorsqu’une tâche lui correspond, donc décrivez précisément quand l’utiliser.

Une bonne façon d’écrire une compétence est de la demander à l’agent juste après avoir terminé la tâche correctement :

Écrivez une compétence dans .claude/skills/gallery-images/SKILL.md qui capture la manière dont vous venez d’extraire les images de la galerie, y compris les chèques que vous avez utilisés. Validez et envoyez-le.

Les compétences personnalisées ne remplacent pas ni ne modifient les compétences intégrées de l’agent. Lorsqu’une nouvelle version gère une tâche en mode natif, supprimez la compétence personnalisée qui la couvrait.

Pourquoi .claude/skills skills-location

Les agents Claude, comme celui que la console exécute actuellement, découvrent eux-mêmes des compétences dans un dossier .claude/skills/ à la racine du référentiel. Une compétence est chargée nativement : l’agent ne voit que la brève description de la compétence jusqu’à ce qu’une tâche la corresponde, puisse la demander par nom et applique les paramètres de l’en-tête de la compétence, par exemple les outils qu’elle peut utiliser. Cela fonctionne de manière plus fiable qu’un dossier visible tel que skills/ que AGENTS.md indexe, où l’agent doit lire l’index et décider d’ouvrir le fichier.

Le nom du dossier commence par un point, qui a deux effets :

  • Votre site ne le diffuse pas, car les règles .hlxignore décrites ci-dessus l’excluent.
  • Les vues de fichiers de la console ne l’affichent pas. Pour passer en revue une compétence, demandez à l’agent de l’afficher ou ouvrez-la dans GitHub.

Si votre projet possède déjà des compétences dans un dossier visible que AGENTS.md indexe, elles continuent à fonctionner. Pour les charger en mode natif, demandez à l’agent de les déplacer vers .claude/skills/, d’ajouter l’en-tête et de supprimer les lignes d’index.

recommendation-more-help
experience-manager-cloud-service-help-main-toc