项目说明和内存 project-instructions
Experience现代化代理只知道当前对话中和项目文件中的内容。 要使它遵循每个对话中的项目惯例，请在Git存储库中的Markdown文件中写入它们。 本文解释了代理如何使用这些文件以及如何组织这些文件以使代理高效工作。
最多开始新对话的所有内容适用于每个项目。 自定义技能是大多数项目不需要的高级选项。
座席记住的内容 memory
工程师不会单独存储您的首选项或以前的对话。 任何它在每次对话中应该知道的事情，都必须在它读取的文件中。 由于文件位于您的Git存储库中，因此它们还可以帮助项目中的其他开发人员以及他们用于该项目的任何其他AI工具。
使用AGENTS.md作为入口点 agents-md
AGENTS.md是位于存储库根目录的Markdown文件。 它遵循许多AI编码代理读取的打开格式。
代理当前使用Claude模型，该模型在每个对话开始时从存储库根目录加载名为CLAUDE.md的文件。 AEM样板遵循的最佳实践是CLAUDE.md文件，其行如下：
see @AGENTS.md
@引用使代理加载AGENTS.md与CLAUDE.md一起运行，并在运行时将其保留在其上下文中。 在AGENTS.md中编写项目说明，并将CLAUDE.md保留为这一行。 然后，您的说明将保持为其他AI工具也读取的开放格式，如果代理背后的模型发生更改，则设置将继续工作。 该模型是实施详细信息，因此不要编写依赖它的指令。
从当前AEM样板创建的项目（用于基于文档的内容或Experience Manager创作）同时包含这两个文件，并且其AGENTS.md包含常规的Edge Delivery Services编码规则。 保留两个文件。 如果您的项目是在模板包含之前创建的，请让代理从当前模板添加它们。 要检查它加载的内容，请启动新的对话并询问它具有哪些项目说明。
将项目的简短部分添加到AGENTS.md：
- 网站的性质、来源及其内容目标。
- 适用于几乎所有任务的少数规则。
- 其它指令文件的索引，注明何时读取每个指令文件。
保持AGENTS.md短。 座席负责处理每条会话中的所有信息，因此每条线路都占用了执行任务所需的空间。 较长的通用文本也会使代理更难判断哪些规则重要。
组织进一步的说明文件 organize
将详细信息放在单独的文件中，如果有多个文件，则将其分组到文件夹中。 例如：
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
引用AGENTS.md中的每个文件。 当任务需要引用文件时，代理会打开该文件，因此您无需在每次提示时都命名该文件：
## 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.
请遵循以下准则：
- 每个文件一个主题。 当文件变长时，按主题将其拆分。 然后，代理只读取当前任务所需的内容，并为工作本身保留更多的上下文。
- 说什么时候读取文件。 索引中的一行说明足以供座席决定。
- 指向代码。 该代码是有关如何实施某些内容的参考。 描述意图和约定，并命名实现这些意图和约定的文件，而不是复制代码。
- 没有密钥。 这些文件是存储库的一部分。 切勿在其中放置密码、令牌或其他凭据。
Edge Delivery Services提供已提交到存储库的文件，除非这些文件在.hlxignore文件中被排除。 AEM样板的.hlxignore不包括名称以点开头的Markdown文件和文件。 使用Markdown编写指令文件，以便将这些文件排除在外；否则，可以从网站的URL请求其他格式的文件，如JSON或纯文本。 控制台不显示.hlxignore，因此如果您需要对其进行更改，请在GitHub或本地克隆中进行编辑。
文档内容惯例 content-conventions
作者最适合使用精简内容结构：标题、某些文本、图像和链接，而无需额外字段。 为了使内容保持简单，实施依赖惯例，例如哪些内容是可选内容或元素的位置如何更改其角色。 作者、开发人员和代理只能遵循这些约定，前提是写下它们。 David的模型描述了此类结构的一般规则；从您的内容约定中引用它，并仅记录您项目自己的决策。
值得记录的惯例包括：
- 块的内容变体。 例如，对于Teaser：图像和call to action是否为可选、作者选择较大标题还是较小标题的方式，以及标题前面的简短段落是否变成眉毛，标题上方的小标签。
- 阻止变体。 存在哪些变体以及何时使用每个变体。
- 节样式。 存在哪些节样式，例如深色背景或窄列、它们的工作方式以及它们内部的块。 某些部分可能期望特定块实现特定效果。
- 页面模板。 模板页面必须遵循的内容约定，例如，以主页开头并以相关链接结尾的文章页面。
- 编码、设计和内容规则。 命名、设计令牌、品牌规则、URL和资产惯例，以及新团队成员需要了解的任何其他信息。
一个块的条目可以短如下：
### 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`.
当迁移创建块时，代理还会为开发人员编写自述文件，并为作者编写创作指南。 查看代理为块提供的内容。 从索引中引用这些文件而不是重复它们。
更改代理的应答方式 reply-style
代理填写其答案的方式与任何其他方式一样，因此您可以在AGENTS.md中设置它。 例如，如果您不希望它通过建议后续步骤来结束每个答案，或者您想要更短的答案，请这样说：
## 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.
这些说明决定了座席答案的文本。 控制台在 后续步骤 下显示的建议是单独生成的，因此它们仍会显示，您可以忽略它们。
保留每个请求的记录 trace
您的Git历史记录和内容的版本历史记录是代理执行的操作的记录；请参阅跟踪代理执行的操作。 为了使记录易于遵循，请在AGENTS.md中添加一个常设规则，以便每个请求都保留自己的提交和内容上传：
## 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.
- 正在推送需要允许LLM使用我的Git凭据，或者为通过Cloud Manager连接的存储库使用Adobe凭据权限。 请参阅设置页面。 如果权限不可用，请在每个请求后使用同步 > 推送 > 代码推送您自己。
- 上传需要Adobe凭据权限。 只有在您的消息询问内容或您同意询问内容时，控制台才会允许代理上传内容，因此规则会提示代理询问，而您的回答会批准上传。 对于创作实例上的内容，请自行上传页面。
- 工作分支使代理的推送远离实时站点的代码。 开发人员审阅更改并使用拉取请求将它们合并到
main中，如更广泛贡献，相同生产控制中所述。
让代理维护文件 maintain
您不需要手动编写这些文件。 要求代理创建和更新代码，然后像查看代码一样查看代码。
-
在第一个模板和块存在时创建第一个版本：
从代码和导入的内容中记录此项目的块、变体、区域样式、页面模板和设计令牌。 将每个主题放在
project/下的其自己的短文件中，并添加索引，其中包含何时将每个文件读取到AGENTS.md。 -
保持为最新。 向
AGENTS.md添加一个固定规则，如上面示例的最后一行，以便代理程序在创建或更改块、节样式或模板时更新文件。 -
检查他们。 代理人可以记录其假设的惯例，而不是您同意的惯例。 纠正任何错误，并时常询问：
根据当前代码和内容检查
project/下的文件。 修复过期的语句，并拆分任何增长过长的文件。 -
使用代码推送它们，以便您的团队和将来的对话获得相同的说明。
开始新对话 new-conversation
由于代理自动加载AGENTS.md，因此将开始一个新的对话，其中包含您的项目说明，并通过索引查找其他文件。 当对话已变长或偏离任务时，使用 清除聊天 开始新对话。 清除之前，请要求代理保存重要内容：
在我取消聊天之前，请将我们在此对话中商定的决策和惯例记录在项目文件中，并列出您更改的内容。
清除将删除较早的消息，并且无法撤消。 若要保留对话，请先选择下载聊天。
要完全移交给其他人员或团队，请参阅保留人员和代理的上下文。
高级：自定义技能 custom-skills
大多数项目不需要自定义技能。 该代理的内置技能涵盖迁移、设计、数据块开发和文档记录，并且这些技能会随着每个版本的发布而改进。 请参阅发行说明。
技能是指一种任务的一组指令，通常按步就进。 它的工作方式类似于AGENTS.md的一部分，但有一个区别：代理仅在执行某项任务时读取该项技能，而不是在每次对话中携带该项技能。 在以下情况下考虑自定义技能：
- 一个周期性任务的说明会使
AGENTS.md变长。 - 代理程序需要不断处理特定的重复任务，并且需要精确的步骤，例如，从源站点上不寻常的图库中提取图像或处理嵌入的视频。
添加自定义技能：
- 要求代理在
.claude/skills/下自己的文件夹中创建技能，如.claude/skills/gallery-images/SKILL.md。 文件以简短标题开始，该标题为技能提供name以及何时使用它的description。 下面是步骤、显示任务成功的检查以及简短示例。 - 要求代理提交并推送技能。 控制台的文件视图无法存放名称以点开头的文件夹；代码视图说明了代理推送这些文件夹所需的权限，以及没有这些权限应该怎么做。
- 在新对话中测试技能。 按名称询问它，例如“使用画廊图像技能导入此页面”。 要检查座席是否找到该技能，请要求它阅读该技能并告知其名称和描述。 座席技能列表包括座席的内置技能，因此不会显示您的技能是否已加载。
SKILL.md的标头如下所示：
---
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.
---
您无需在AGENTS.md中列出该技能。 座席会看到文件夹中每项技能的描述，并在任务与技能匹配时阅读该技能，因此可以准确地描述何时使用该技能。
技能写法的一个好办法是在座席正确完成任务后立即要求座席提供技能：
在
.claude/skills/gallery-images/SKILL.md中编写技能，以捕获您刚刚提取画廊图像的方式，包括您使用的支票。 然后提交并推送它。
自定义技能不会替换或更改座席的内置技能。 当新版本以本机方式处理任务时，移除覆盖该任务的自定义技能。
为什么选择.claude/skills skills-location
与控制台当前运行的代理一样，基于Claude的代理也会在存储库根目录的.claude/skills/文件夹中自行发现技能。 本地加载技能：座席只查看该技能的简短描述，直到任务与其匹配为止，可以按名称请求该技能，并应用技能标题中的设置，如可以使用哪些工具。 此操作比可见文件夹（如AGENTS.md索引的skills/）更可靠，代理必须读取索引并决定打开该文件。
文件夹的名称以点开头，具有两种效果：
- 您的网站不提供该服务，因为上述的
.hlxignore规则将其排除。 - 控制台的文件视图不显示它。 要查看技能，请要求座席显示该技能，或在GitHub中打开该技能。
如果您的项目在包含AGENTS.md个索引的可见文件夹中已经拥有技能，则这些技能将继续工作。 若要以本机方式加载这些文件，请要求代理将它们移动到.claude/skills/，添加标头，并删除索引行。