プロジェクトの手順とメモリ project-instructions

Experience Modernization Agentは、現在の会話とプロジェクトのファイル内の内容のみを把握します。 すべての会話でプロジェクトの規則に従うように、Git リポジトリのMarkdown ファイルに書き込みます。 この記事では、エージェントがこれらのファイルをどのように使用し、効率的に動作するようにファイルを整理する方法について説明します。

新しい会話の開始までのすべての項目が、すべてのプロジェクトに適用されます。 ​ カスタムスキル ​は、ほとんどのプロジェクトで必要のない高度なオプションです。

エージェントが覚えていること memory

担当者は、ユーザーの好みや以前の会話のメモリを個別に保持しません。 すべての会話で知っておくべきことは、読み込むファイルに含まれている必要があります。 ファイルはGit リポジトリ内にあるので、プロジェクト上の他の開発者や、そこで使用するその他のAI ツールにも役立ちます。

エントリポイントとしてAGENTS.mdを使用する agents-md

AGENTS.mdは、リポジトリのルートにあるMarkdown ファイルです。 これは、多くのAI コーディングエージェントが読む​ オープン形式に従います。

現在、エージェントはClaude モデルを使用しており、会話の開始時にリポジトリルートからCLAUDE.mdという名前のファイルを読み込みます。 ベストプラクティスは、AEMのボイラープレート ​に従うもので、次の1行のCLAUDE.md ファイルです。

see @AGENTS.md

@参照により、エージェントはAGENTS.mdをCLAUDE.mdと一緒に読み込み、作業中はコンテキストに残します。 プロジェクトの指示をAGENTS.mdに書き、CLAUDE.mdをこの1行のままにします。 その後、指示は他の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に命令ファイルを書き込んで除外するようにします。JSONやプレーンテキストなどの他の形式のファイルは、サイトのURLから要求される可能性があります。 コンソールに.hlxignoreが表示されないので、変更する必要がある場合は、GitHubまたはローカルクローンで編集します。

ドキュメントコンテンツの規則 content-conventions

作成者は、見出し、テキスト、画像、リンクなどのリーンコンテンツ構造（追加フィールドなし）を最も効果的に使用できます。 コンテンツをシンプルにするために、実装は、どのコンテンツがオプションであるか、要素の位置がどのように役割を変更するかなどの規則に依存しています。 作成者、開発者、およびエージェントは、これらの規則が記述されている場合にのみ、これらの規則に従うことができます。 Davidのモデル ​は、このような構造の一般的なルールを記述します。コンテンツ規則から参照し、プロジェクト独自の決定のみを書き留めます。

文書化する価値のある規則には、次のようなものがあります。

1つのブロックのエントリは、次のように短くすることができます。

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

移行でブロックが作成されると、エージェントは開発者にはREADMEを、作成者向けにはオーサリングガイドを書きます。 ​ エージェントがブロックに提供する機能を参照してください。 これらのファイルを繰り返す代わりに、インデックスから参照します。

エージェントの回答を変更する 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.

エージェントによるファイルの管理 maintain

これらのファイルを手書きで書く必要はありません。 担当者に作成と更新を依頼し、コードのレビューと同様に確認します。

新しい会話を開始 new-conversation

エージェントはAGENTS.mdを自動的に読み込むため、新しい会話はプロジェクトの指示から始まり、インデックスを介して他のファイルが見つかります。 会話が長くなったり、タスクから切り離されたりした場合は、チャットをクリア​して新しい会話を開始します。 消去する前に、担当者に次の重要な情報を保存するように依頼します。

チャットをクリアする前に、この会話で合意した決定と規則をプロジェクトファイルに記録し、変更した内容をリストします。

消去すると、以前のメッセージが削除され、元に戻すことはできません。 会話を維持するには、まず​ チャットをダウンロード ​を選択します。

別のユーザーまたはチームへの完全な引き継ぎについては、人物とエージェントのコンテキストの保持を参照してください。

高度な機能：カスタムスキル custom-skills

多くのプロジェクトでは、カスタムスキルは必要ありません。 エージェントに組み込まれたスキルは、移行、デザイン、ブロック開発、ドキュメントなどであり、各リリースで改善されます。 ​ リリースノート ​を参照してください。

スキルとは、1種類のタスクを指示するセットです。多くの場合、ステップバイステップで説明します。 これはAGENTS.mdのセクションのように機能しますが、1つの違いがあります。エージェントは、会話のたびに実行するのではなく、そのタスクを実行する場合にのみスキルを読み取ります。 次の場合に、カスタムスキルを検討します。

カスタムスキルを追加するには：

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/skills/ フォルダーで自分でスキルを発見します。 そこでスキルがネイティブに読み込まれます。エージェントは、タスクが一致するまでスキルの短い説明のみを表示し、名前で要求され、使用できるツールなど、スキルのヘッダーから設定を適用します。 これは、エージェントがインデックスを読み取り、ファイルを開くことを決定するAGENTS.md インデックスのskills/などの目に見えるフォルダーよりも確実に機能します。

フォルダー名はドットで始まり、2つの効果があります。

プロジェクトに既にAGENTS.md個のインデックスを持つ表示可能なフォルダー内にスキルがある場合、そのスキルは引き続き機能します。 ネイティブに読み込むには、エージェントに対して.claude/skills/に移動するよう依頼し、ヘッダーを追加してインデックス行を削除します。