專案指示與記憶體 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/、新增標題並移除索引行。