Projektanweisungen und -speicher project-instructions
Der Experience Modernization Agent weiß nur, was in der aktuellen Unterhaltung und in den Dateien Ihres Projekts ist. Damit es bei jeder Unterhaltung den Konventionen Ihres Projekts entspricht, schreiben Sie sie in Markdown-Dateien in Ihrem Git-Repository. In diesem Artikel wird erläutert, wie der Agent diese Dateien verwendet und wie Sie sie so organisieren können, dass sie effizient funktionieren.
Alles bis zu Neue Konversation beginnen gilt für jedes Projekt. Benutzerdefinierte Fähigkeiten sind eine erweiterte Option, die die meisten Projekte nicht benötigen.
Woran sich der Agent erinnert memory
Der Agent speichert Ihre Voreinstellungen oder früheren Konversationen nicht separat. Alles, was es bei jedem Gespräch wissen sollte, muss in einer Datei enthalten sein, die es liest. Da sich die Dateien in Ihrem Git-Repository befinden, helfen sie auch den anderen Entwicklern des Projekts und allen anderen KI-Tools, die sie damit verwenden.
Verwenden von AGENTS.md als Einstiegspunkt agents-md
AGENTS.md ist eine Markdown-Datei im Stammverzeichnis des Repositorys. Es folgt einem offenen Format das viele KI-Kodierungs-Agenten lesen.
Der Agent verwendet derzeit Claude-Modelle, die zu Beginn jeder Konversation eine Datei mit dem Namen CLAUDE.md aus dem Repository-Stamm laden. Die Best Practice, der das AEM-Textbaustein folgt, ist eine CLAUDE.md mit dieser einzigen Zeile:
see @AGENTS.md
Die @-Referenz sorgt dafür, dass der Agent zusammen mit CLAUDE.md AGENTS.md lädt und ihn im Kontext behält, während er funktioniert. Schreiben Sie Ihre Projektanweisungen in AGENTS.md und lassen Sie CLAUDE.md als diese Zeile. Ihre Anweisungen bleiben dann im offenen Format, das auch andere KI-Tools lesen, und die Einrichtung funktioniert weiterhin, wenn sich das Modell hinter dem Agenten ändert. Dieses Modell ist ein Implementierungsdetail, also schreiben Sie keine Anweisungen, die davon abhängen.
Projekte, die mit dem aktuellen AEM-Textbaustein für dokumentbasierte Inhalte oder für das Experience Manager-Authoring erstellt wurden, enthalten beide Dateien, und ihr AGENTS.md enthält allgemeine Edge Delivery Services-Kodierungsregeln. Beide Dateien beibehalten. Wenn Ihr Projekt erstellt wurde, bevor das Textbaustein-Element sie enthielt, bitten Sie den Agenten, sie aus dem aktuellen Textbaustein-Element hinzuzufügen. Um zu überprüfen, was geladen wurde, beginnen Sie eine neue Unterhaltung und fragen Sie, welche Projektanweisungen es hat.
Fügen Sie AGENTS.md einen kurzen Abschnitt für Ihr Projekt hinzu:
- Was die Site ist, ihre Quelle und ihr Inhaltsziel.
- Die wenigen Regeln, die für fast jede Aufgabe gelten.
- Ein Index der anderen Anweisungsdateien mit einem Hinweis, wann jede zu lesen ist.
Halten Sie AGENTS.md kurz. Der Agent trägt alles in jedem Gespräch, sodass jede Zeile Platz einnimmt, den sie für die Aufgabe verwenden könnte. Lange, allgemeine Texte erschweren es dem Agenten auch zu sagen, welche Regeln wichtig sind.
Weitere Anweisungsdateien organisieren organize
Legen Sie Details in separaten Dateien ab, die in einem Ordner gruppiert sind, wenn mehrere davon vorhanden sind. Beispiel:
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
Verweisen Sie auf jede Datei aus AGENTS.md. Der Agent öffnet eine referenzierte Datei, wenn die Aufgabe es benötigt, sodass Sie die Datei nicht bei jeder Eingabeaufforderung benennen müssen:
## 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.
Befolgen Sie diese Richtlinien:
- Ein Thema pro Datei. Wenn eine Datei lang wird, teilen Sie sie nach Thema auf. Der Agent liest dann nur, was die aktuelle Aufgabe benötigt, und behält mehr von seinem Kontext für die Arbeit selbst bei.
- Sagen Sie, wann eine Datei gelesen werden soll. Eine einzeilige Beschreibung im Index reicht aus, damit der Agent eine Entscheidung treffen kann.
- Zeigen Sie auf den Code. Der Code ist die Referenz dafür, wie etwas implementiert wird. Beschreiben Sie die Absicht und die Konventionen und benennen Sie die Datei, die sie implementiert, anstatt Code zu kopieren.
- Keine Geheimnisse. Diese Dateien sind Teil Ihres Repositorys. Geben Sie niemals Kennwörter, Token oder andere Anmeldeinformationen darin ein.
Edge Delivery Services stellt Dateien bereit, die in das Repository übertragen werden, es sei denn, sie werden in der .hlxignore-Datei ausgeschlossen. Die .hlxignore des AEM-Textbausteins schließt Markdown-Dateien und Dateien aus, deren Namen mit einem Punkt beginnen. Schreiben Sie Anweisungsdateien in Markdown, damit sie ausgeschlossen bleiben. Dateien in anderen Formaten, wie JSON oder Nur-Text, können andernfalls von den URLs der Site angefordert werden. Die Konsole zeigt keine .hlxignore an. Wenn Sie sie also ändern müssen, bearbeiten Sie sie in GitHub oder in einem lokalen Klon.
Konventionen für den Dokumentinhalt content-conventions
Autoren eignen sich am besten für schlanke Inhaltsstrukturen: eine Überschrift, etwas Text, ein Bild und einen Link, ohne zusätzliche Felder. Um den Inhalt so einfach zu halten, verlässt sich die Implementierung auf Konventionen, z. B. welche Inhalte optional sind oder wie die Position eines Elements seine Rolle ändert. Autoren, Entwickler und der Agent können diese Konventionen nur befolgen, wenn sie niedergeschrieben sind. Davids Modell beschreibt die allgemeinen Regeln für solche Strukturen. Verweisen Sie auf sie aus Ihren Inhaltskonventionen und schreiben Sie nur die eigenen Entscheidungen Ihres Projekts auf.
Zu den Konventionen, die es wert sind, dokumentiert zu werden, gehören:
- Inhaltsvarianten eines Bausteins. Für einen Teaser gilt beispielsweise Folgendes: ob das Bild und die call to action optional sind, wie Autorinnen und Autoren einen größeren oder kleineren Titel auswählen und ob ein kurzer Absatz, bevor der Titel zur Augenbraue wird, eine kleine Beschriftung über dem Titel darstellt.
- Blockvarianten. Welche Varianten es gibt und wann sie verwendet werden sollten.
- Abschnittsstile. Welche () es gibt, z. B. einen dunklen Hintergrund oder eine schmale Spalte, was sie tun und welche Blöcke in ihnen funktionieren. In einigen Abschnitten wird möglicherweise erwartet, dass ein bestimmter Block eine bestimmte Wirkung erzielt.
- Seitenvorlagen. Inhaltskonventionen, denen Seiten einer Vorlage entsprechen müssen, z. B. eine Artikelseite, die mit einem Hero beginnt und mit verwandten Links endet.
- Kodierungs-, Design- und Inhaltsregeln. Namen, Design-Token, Markenregeln, URL- und Asset-Konventionen und alles andere, was ein neues Teammitglied wissen muss.
Ein Eintrag für einen Block kann so kurz sein wie dieser:
### 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`.
Wenn bei der Migration ein Block erstellt wird, schreibt der Agent auch eine README für Entwickler und ein Authoring-Handbuch für Autoren. Siehe Was der Agent mit einem Block bereitstellt. Verweisen Sie auf diese Dateien aus Ihrem Index, anstatt sie zu wiederholen.
Antwort des Agenten ändern reply-style
Die Art und Weise, wie der Agent seine Antworten schreibt, ist eine Konvention wie jede andere, sodass Sie sie in AGENTS.md festlegen können. Wenn Sie zum Beispiel nicht möchten, dass jede Antwort durch Vorschläge für nächste Schritte beendet wird, oder Sie kürzere Antworten wünschen, sagen Sie es so:
## 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.
Diese Anweisungen bestimmen den Text der Antworten des Agenten. Die Vorschläge, die in der Konsole unter Nächste Schritte angezeigt werden, werden separat generiert, sodass sie weiterhin angezeigt werden und Sie sie ignorieren können.
Hinterlassen Sie für jede Anfrage einen Datensatz trace
Ihr Git-Verlauf und der Versionsverlauf Ihres Inhalts sind die Aufzeichnung dessen, was der Agent getan hat; siehe Verfolgen dessen, was der Agent getan hat. Um das Nachvollziehen dieses Datensatzes zu vereinfachen, fügen Sie eine stehende Regel zu AGENTS.md hinzu, sodass jede Anfrage ihren eigenen Commit und den Upload von Inhalten verlässt:
## 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.
- Pushen benötigt Zulassen, dass LLM meine Git-Anmeldeinformationen verwendet oder die Berechtigung mit Adobe-Anmeldeinformationen für Repositorys, die über Cloud Manager verbunden sind. Siehe Einstellungsseite. Wenn Ihnen die Berechtigung nicht zur Verfügung steht, pushen Sie sich nach jeder Anfrage mit Sync > Push > Code.
- Hochladen erfordert die Berechtigung für Adobe-Anmeldeinformationen. In der Konsole kann der Agent nur Inhalte hochladen, wenn Sie in Ihrer Nachricht danach gefragt werden oder wenn Sie damit einverstanden sind, sodass die Regel den Agent fragt und Ihre Antwort das Hochladen genehmigt. Laden Sie für Inhalte in der Autoreninstanz die Seiten selbst hoch.
- Der Arbeitszweig hält die Push-Benachrichtigungen des Agenten vom Code der Live-Site fern. Ein Entwickler überprüft die Änderungen und führt sie mit einer Pull-Anfrage in
mainzusammen, wie in Umfassenderer Beitrag, Gleiche Produktionskontrolle beschrieben.
Lassen Sie den Agenten die Dateien verwalten maintain
Sie müssen diese Dateien nicht von Hand schreiben. Bitten Sie den Agenten, sie zu erstellen und zu aktualisieren, und überprüfen Sie sie dann so, wie Sie den Code überprüfen würden.
-
Erstellen Sie die erste Version sobald die ersten Vorlagen und Blöcke vorhanden sind:
Dokumentieren Sie die Blöcke, Varianten, Abschnittsstile, Seitenvorlagen und Design-Token dieses Projekts aus dem Code und den importierten Inhalten. Platzieren Sie jedes Thema in einer eigenen kurzen Datei unter
project/und fügen Sie einen Index mit dem Zeitpunkt hinzu, wann jede Datei zuAGENTS.mdgelesen werden soll. -
Halten Sie sie aktuell. Fügen Sie
AGENTS.mdeine stehende Regel hinzu, z. B. die letzte Zeile des obigen Beispiels, sodass der Agent die Dateien aktualisiert, sobald er einen Block, einen Abschnittsstil oder eine Vorlage erstellt oder ändert. -
Überprüfen Sie sie. Der Agent kann eine Konvention aufzeichnen, von der er ausgeht, und nicht eine, der Sie zugestimmt haben. Korrigieren Sie alles, was falsch ist, und fragen Sie von Zeit zu Zeit:
Überprüfen Sie die Dateien unter
project/anhand des aktuellen Codes und Inhalts. Korrigieren Sie Anweisungen, die veraltet sind, und teilen Sie alle Dateien auf, die zu lang geworden sind. -
Pushen Sie sie mit dem Code sodass Ihr Team und zukünftige Konversationen die gleichen Anweisungen erhalten.
Neue Konversation beginnen new-conversation
Da der Agent AGENTS.md automatisch lädt, beginnt eine neue Konversation mit Ihren Projektanweisungen, und er findet die anderen Dateien über den Index. Beginnen Sie eine neue Unterhaltung mit Chat löschen wenn eine Unterhaltung zu lang geworden ist oder von der Aufgabe abgewichen ist. Bevor Sie sie löschen, bitten Sie den Agenten, alles zu speichern, was wichtig ist:
Bevor ich den Chat lösche, notiere die Entscheidungen und Konventionen, die wir in diesem Gespräch vereinbart haben, in den Projektdateien und führe auf, was du geändert hast.
Durch Löschen werden die früheren Nachrichten entfernt und können nicht rückgängig gemacht werden. Um die Konversation fortzusetzen, wählen Sie Chat herunterladen aus.
Eine vollständige Übergabe an eine andere Person oder ein Team finden Sie unter Kontext für Personen und Agenten beibehalten.
Fortgeschrittene Benutzer: Benutzerspezifische Fähigkeiten custom-skills
Die meisten Projekte benötigen keine benutzerdefinierten Fähigkeiten. Die integrierten Fähigkeiten des Agenten umfassen Migration, Design, Blockentwicklung und Dokumentation und verbessern sich mit jeder Version. Siehe die Versionshinweise.
Eine Fertigkeit ist ein Satz von Anweisungen für eine Art von Aufgabe, häufig Schritt für Schritt. Es funktioniert wie ein Abschnitt von AGENTS.md, mit einem Unterschied: Der Agent liest eine Fähigkeit nur, wenn er diese Aufgabe ausführt, anstatt sie in jedem Gespräch zu tragen. Erwägen Sie eine benutzerdefinierte Qualifikation, wenn:
- Anweisungen für eine wiederkehrende Aufgabe machen
AGENTS.mdlang. - Der Agent hat immer wieder mit einer bestimmten, wiederholten Aufgabe zu kämpfen und benötigt präzise Schritte, z. B. das Extrahieren von Bildern aus einer ungewöhnlichen Galerie auf der Quellseite oder das Verarbeiten von eingebetteten Videos.
So fügen Sie eine benutzerdefinierte Kenntnis hinzu:
- Bitten Sie den Agenten, die Kenntnisse in einem eigenen Ordner unter
.claude/skills/zu erstellen, z. B..claude/skills/gallery-images/SKILL.md. Die Datei beginnt mit einer kurzen Kopfzeile, die der Qualifikation einennameund einedescriptiondarüber gibt, wann sie verwendet werden soll. Die Schritte, die Prüfungen, die die Aufgabe erfolgreich abgeschlossen haben, und ein kurzes Beispiel folgen. - Bitten Sie den Agenten, die Kenntnisse zu übertragen. In den Dateiansichten der Konsole können keine Ordner bereitgestellt werden, deren Namen mit einem Punkt beginnen. In Codeansichten werden die Berechtigungen erläutert, die der Agent benötigt, um sie per Push zu übertragen, und auch, was ohne sie zu tun ist.
- Testen Sie die Kenntnisse in einer neuen Unterhaltung. Fragen Sie ihn nach dem Namen, wie zum Beispiel „Verwenden Sie die gallery-images-Fähigkeit, um diese Seite zu importieren“. Um zu überprüfen, ob der Agent sie gefunden hat, bitten Sie ihn, die Kenntnis zu lesen und Ihnen ihren Namen und ihre Beschreibung mitzuteilen. Eine Liste der Fähigkeiten des Agenten deckt seine integrierten Fähigkeiten ab, sodass nicht angezeigt wird, ob Ihre geladen wurden.
Die Kopfzeile von SKILL.md sieht wie folgt aus:
---
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.
---
Sie müssen die Kenntnisse nicht in AGENTS.md auflisten. Der Agent sieht die Beschreibung aller Kenntnisse in dem Ordner und liest eine Kenntnis, wenn eine Aufgabe damit übereinstimmt. Daher sollte er genau beschreiben, wann er sie verwenden soll.
Eine gute Möglichkeit, eine Kenntnis zu schreiben, besteht darin, den Agenten direkt nach Abschluss der Aufgabe danach zu fragen:
Schreiben Sie eine Fertigkeit in
.claude/skills/gallery-images/SKILL.md, die erfasst, wie Sie die Galerie-Bilder extrahiert haben, einschließlich der von Ihnen verwendeten Schecks. Dann übertragen und pushen.
Benutzerdefinierte Fähigkeiten ersetzen oder ändern nicht die integrierten Fähigkeiten des Agenten. Wenn eine neue Version eine Aufgabe nativ verarbeitet, entfernen Sie die benutzerdefinierten Kenntnisse, die sie abgedeckt haben.
Warum .claude/skills skills-location
Claude-basierte Agenten, wie der, den die Konsole derzeit ausführt, entdecken eigenständig Kenntnisse in einem .claude/skills/ Ordner im Stammverzeichnis des Repositorys. Eine Qualifikation wird dort nativ geladen: Der Agent sieht nur die Kurzbeschreibung der Qualifikation, bis eine Aufgabe damit übereinstimmt, kann nach ihr anhand des Namens gefragt werden und wendet Einstellungen aus der Kopfzeile der Qualifikation an, z. B. welche Tools sie verwenden kann. Dies funktioniert zuverlässiger als ein sichtbarer Ordner, z. B. skills/, der Indizes AGENTS.md, bei dem der Agent den Index lesen und die Datei öffnen muss.
Der Name des Ordners beginnt mit einem Punkt, der zwei Auswirkungen hat:
- Ihre Site bedient sie nicht, da die oben beschriebenen
.hlxignoreRegeln 🔗 ausschließen. - Die Dateiansichten“ der Konsole nicht angezeigt. Um eine Qualifikation zu überprüfen, bitten Sie den Agenten, sie anzuzeigen, oder öffnen Sie sie in GitHub.
Wenn Ihr Projekt bereits über Kenntnisse in einem sichtbaren Ordner verfügt, der Indizes AGENTS.md, funktionieren diese weiterhin. Um sie nativ laden zu lassen, bitten Sie den Agenten, sie nach .claude/skills/ zu verschieben, fügen Sie die Kopfzeile hinzu und entfernen Sie die Indexzeilen.