content-driven-development

コンテンツ駆動開発（CDD）

AEM Edge Delivery Services のコンテンツ駆動開発ワークフローを進めます。このワークフローにより、実際のコンテンツに基づいてコードを構築し、作成者にとって使いやすいコンテンツモデルを実現できます。

重要：変更のテストに使用するコンテンツを特定または作成する前に、コードの記述や変更を始めないでください。

このスキルを使用するタイミング

すべての AEM 開発タスクで CDD を使用してください。

• ✅ 新しいブロックの作成
• ✅ 既存ブロックの変更（構造的または機能的な変更）
• ✅ コアのデコレーション機能の変更
• ✅ 検証が必要なバグ修正
• ✅ 作成者によるコンテンツの作成方法や構成方法に影響するコード変更

次の場合は使用しないでください。

• ドキュメントのみの変更
• 作成者によるコンテンツ作成に影響しない設定変更
• まだコード変更を伴わない調査タスク

考え方

コンテンツ駆動開発では、コードを書く前に、テスト用コンテンツを作成または特定することを優先します。これにより、次のことが実現します。

• 実際のコンテンツに基づいたコードの構築
• 作成者にとって使いやすいコンテンツモデル
• 開発全体を通じた検証

任意：CDD の原則を理解する

次の場合は、references/cdd-philosophy.md を読んでください。

• コンテンツファーストのアプローチについて、「なぜ」と質問された場合
• CDD の判断の背景にある理由を理解する必要がある場合
• 作成者と開発者のどちらのエクスペリエンスを優先すべきか判断できない場合

それ以外の場合：以下のワークフローの手順に従ってください

Step 0: TodoList の作成

最初のステップ： TodoWrite ツールを使用して、次の 8 つのタスクを含む TodoList を作成します。

1. 開発サーバーを起動する（実行されていない場合）

   • 成功条件：開発サーバーが起動しており、http://localhost:3000 にアクセスできる

2. 分析と計画

   • 成功条件：明確な理解が文書化され、受け入れ基準が定義されている

3. コンテンツモデルを設計する

   • 成功条件：コンテンツ構造が文書化され、検証されている

4. テスト用コンテンツを特定または作成する

   • 成功条件：すべてのシナリオを網羅するテスト用コンテンツにアクセスできる

5. 実装する

   • 成功条件：すべてのビューポートで機能する

6. Lint とテストを実行する

   • 成功条件：すべてのチェックに合格する

7. 最終検証

   • 成功条件：すべての受け入れ基準を満たし、すべてが正常に動作する

8. リリースする

   • 成功条件：検証用のプレビューリンクを含む PR が作成されている

完了としてマークするタイミング： 8 つのタスクすべてを含む TodoList が作成されたとき

---

Step 1: 開発サーバーを起動する

開発サーバーが起動しているか確認します：

curl -s -o /dev/null -w "%{http_code}" http://localhost:3000

期待値：200（サーバー起動中）または接続エラー（サーバー停止中）

起動していない場合は、起動します：

aem up --no-open --forward-browser-logs

注：

• 可能であればバックグラウンドで実行してください（開発サーバーは起動したままにする必要があります）
• AEM CLI のグローバルインストールが必要です：npm install -g @adobe/aem-cli
• 代替方法：npx -y @adobe/aem-cli up --no-open --forward-browser-logs

重要： コマンドの出力にエラーがないか確認してください。よくある問題：

• ポート 3000 がすでに使用されている
• AEM CLI がインストールされていない
• 設定エラー

起動後、動作していることを確認します：

curl -s -o /dev/null -w "%{http_code}" http://localhost:3000

期待値：200

成功条件：

• ✅ 開発サーバーが起動している
• ✅ http://localhost:3000 が 200 を返す
• ✅ サーバー起動時の出力にエラーがない

完了としてマークするタイミング： 開発サーバーが起動し、アクセス可能であることを確認できたとき

---

Step 2: 分析と計画

呼び出すスキル： analyze-and-plan

提供する情報：

• ユーザーからのタスクの説明
• デザインを合わせるためのスクリーンショット、デザインファイル、または既存の URL（利用可能な場合）

analyze-and-plan スキルで行うこと：

• タスクに応じた分析をガイドする
• 受け入れ基準の定義を支援する
• 提供された場合、ビジュアルデザインやモックアップを任意で分析する
• 以降の手順で参照できる分析結果を作成する

成功条件：

• ✅ 要件が分析されている
• ✅ 受け入れ基準が定義されている
• ✅ 後続の手順で使えるよう、分析結果がファイルに記録されている

完了としてマークするタイミング： 分析結果が文書化され、受け入れ基準が定義されたとき

---

ステップ 3：コンテンツモデルを設計する

スキップする条件： コンテンツ構造に影響しない CSS のみの変更

呼び出すもの： content-modeling スキル

提供する情報：

• ステップ 2 の分析結果（コンテンツ要件、作成者の入力）
• ブロック名と目的

content-modeling スキルで行うこと：

• テーブル構造（行、列、セマンティックな書式）を設計する
• ベストプラクティス（1 行あたり 4 セル、セマンティックな書式）に照らして検証する
• 作成者向けにコンテンツモデルを文書化する

成功条件：

• ✅ コンテンツモデルを設計する（テーブル構造を定義する）
• ✅ ベストプラクティスに照らして検証する
• ✅ コンテンツモデルを文書化する

コンテンツモデルを設計し、文書化したら、todo を完了にする

---

ステップ 4：テストコンテンツを特定／作成する

目標： このステップの終了時に、すべてのテストシナリオを網羅するアクセス可能なテストコンテンツの URL を用意します

状況に応じて最適な方法を選択します：

---

オプション A：ユーザーからテスト URL が提供された場合

使用する条件： ユーザーがすでにコンテンツを持っており、URL を提供している

手順：

1. URL が読み込めることを検証します：curl -s -o /dev/null -w "%{http_code}" http://localhost:3000/path
2. 期待値：200 ステータス
3. URL を記録します
4. 完了にします

---

オプション B：新しいブロック（既存のコンテンツがない）

使用する条件： まだ存在しないまったく新しいブロックを作成する

手順：

1. 検索をスキップします（まだ検索対象がありません）
2. 次のいずれかの方法でテストコンテンツを作成します：

方法 1：CMS コンテンツ（推奨）

1. ユーザーに CMS（Google Drive／SharePoint／DA／Universal Editor）でコンテンツを作成するよう依頼します
2. ステップ 3 のコンテンツモデルを参考資料として提供します
3. ユーザーから URL が提供されるまで待ちます
4. 検証します：curl -s -o /dev/null -w "%{http_code}" http://localhost:3000/path
5. 期待値：200 ステータス

DA を使用する場合： ユーザーにコンテンツを作成してもらうのではなく、HTML コンテンツをプログラムから DA にプッシュする必要がある場合は、まず da-auth スキルを呼び出して有効な DA_TOKEN を取得し、DA Admin API（POST https://admin.da.live/source/{org}/{repo}/{path}）を使ってコンテンツをプッシュし、プレビューを生成します。

方法 2：ローカル HTML（一時的）

1. drafts/tmp/{block-name}.plain.html に HTML ファイルを作成します
2. ステップ 3 のコンテンツモデルに沿った構造にします
3. ローカル HTML ファイルの形式については、references/html-structure.md を参照します
4. 開発サーバーを再起動します：aem up --html-folder drafts --no-open --forward-browser-logs
5. 検証します：curl -s -o /dev/null -w "%{http_code}" http://localhost:3000/drafts/tmp/{block-name}
6. 期待値：200 ステータス
7. 注： PR の前に、ユーザーが CMS コンテンツを作成する必要があります（プレビューリンクに必須です）

---

オプション C：既存のブロック

使用する条件： 既存のブロックを変更、修正、またはスタイリングする

手順：

まず、既存のコンテンツを検索します

1. find-test-content スキルを呼び出します
2. ブロック名と開発サーバーの URL（任意。既定値は localhost:3000）を指定します

find-test-content で行うこと：

• ブロックを含む既存のコンテンツページを検索します
• 見つかったすべてのバリエーションを自動的に検出して報告します
• インスタンス数とバリエーション情報を含む URL を報告します

次に、検索結果を評価します

十分なコンテンツが見つかった場合：

1. URL を記録します
2. URL が読み込めることを検証します：curl -s -o /dev/null -w "%{http_code}" http://localhost:3000/path
3. 期待値：200 ステータス
4. 完了にします

コンテンツが見つからない場合、または網羅性が不十分な場合：

1. オプション B の方法でテストコンテンツを追加作成します
2. URL が読み込めることを検証します
3. 完了にします

---

成功条件：

• ✅ 既知の URL でテストコンテンツにアクセスできる
• ✅ コンテンツがすべてのテストシナリオ（バリエーション、エッジケース）を網羅している
• ✅ URL を検証済み（200 を返す）

テストコンテンツを特定／作成して検証したら、todo を完了にする

---

Step 5: 実装

実行するもの： building-blocks スキル

提供するもの：

• Step 3 のコンテンツモデル（該当する場合）
• Step 4 のテスト用コンテンツ URL
• Step 2 の分析／要件
• 変更の種類：新規ブロック、既存ブロックの変更、CSS のみなど

building-blocks スキルで行うこと：

• 変更の種類に応じた実装方法を案内します
• JavaScript による装飾を行います（必要な場合）
• CSS スタイリングを行います（モバイルファースト、レスポンシブ）
• 開発中にブラウザーで反復テストを行います

成功基準：

• ✅ コードの実装が完了している
• ✅ すべてのビューポート（モバイル、タブレット、デスクトップ）で機能する
• ✅ コンソールエラーがない

以下の場合に todo を完了にします： building-blocks スキルで実装が完了し、すべてのビューポートで動作することが報告された場合

---

Step 6: リントとテスト

実行すること：

npm run lint

リントエラーがある場合：

1. 問題を修正します（自動修正可能な問題には npm run lint:fix を使用します）
2. エラーがなくなるまでリントを再実行します

既存のテストを実行します：

npm test

注： ユニットテストは任意であり、ロジックが複雑なユーティリティでのみ必要です。testing-blocks スキル（Step 5 で building-blocks が実行）がブラウザーテストを担当します。このステップでは、残っているリントの問題を検出し、プロジェクトのテストスイートを実行します。

成功基準：

• ✅ npm run lint がエラーなしで成功する
• ✅ npm test が成功する（テストが存在する場合）

以下の場合に todo を完了にします： すべてのリントとテストのチェックに合格した場合

---

Step 7: 最終検証

実行すること：

1. Step 2 の受け入れ基準を確認します

   • Step 2 で作成した分析ドキュメントを読みます
   • 受け入れ基準を一つずつ満たしていることを確認します

2. ブラウザーで最終確認を行います

   • テスト用コンテンツ URL をブラウザーで読み込みます
   • モバイル、タブレット、デスクトップのビューポートを確認します
   • コンソールエラーがないことを確認します
   • 視覚的なデグレがないことを確認します

3. デグレがないことを確認します

   • 既存ブロックを変更した場合：既存のバリアントが引き続き動作することをテストします
   • コア機能を変更した場合：いくつかのページを抜き取りで確認します

成功基準：

• ✅ Step 2 の受け入れ基準をすべて満たしている
• ✅ すべてのビューポートで動作する
• ✅ コンソールエラーがない
• ✅ 既存機能にデグレがない

以下の場合に todo を完了にします： すべての受け入れ基準を確認し、デグレが見つからなかった場合

---

ステップ 8：リリースする

作業内容：

1. フィーチャーブランチを作成します（まだ作成していない場合）：

   git checkout -b block-name
   

2. 特定のファイルのみをステージングします：

   git add blocks/{block-name}/{block-name}.js blocks/{block-name}/{block-name}.css
   # Add only files you worked on - NEVER use `git add .`
   

3. Conventional Commits 形式でコミットします：

   git commit -m "feat(block-name): add new block"
   

   コミットメッセージに関連する詳細を含め、フッターにエージェントの帰属情報を記載します（エージェントが Co-authored-by: cursor <[email protected]> を追加します）。

4. フィーチャーブランチにプッシュします：

   git push origin HEAD
   

5. プレビューリンクを付けて PR を作成します：

   • ブランチのプレビュー URL 形式：https://{branch}--{repo}--{owner}.aem.page/{path}
   • 例：https://carousel--aem-skills-demo--shsteimer.aem.page/
   • 必須： PR の説明にプレビューリンクを含めます（自動 PSI チェックで使用されます）。
   • 必要に応じて、複数のプレビューリンクを追加します（例：異なるバリエーションやエッジケース）。

   ドラフト PR が必要かどうかの判断：

   次の場合はドラフト PRを作成します：

   • ✅ 新しい機能やバリエーションについて、ローカルのテストコンテンツのみが存在する
   • ✅ テストコンテンツで、まだ CMS にない新機能を確認できる
   • ✅ 最終検証の前に、ユーザーによる CMS コンテンツの作成が必要

   次の場合は通常の PRを作成します：

   • ✅ すべてのテストコンテンツが CMS に存在し、プレビューできる
   • ✅ 変更が既存のコンテンツにのみ影響する（既存の CMS コンテンツでリグレッションをテストできる）

   ドラフト PR のワークフロー：

   1. gh pr create --draft を使って、ドラフトとして PR を作成します。
   2. 既存のコンテンツのプレビューリンクを含めます（該当する場合はリグレッションテスト用）。
   3. PR の説明に次のステップを含めます（以下のテンプレートを参照）：
      • ローカルで使用したテストコンテンツと、対象となるシナリオを説明します。
      • 同じ、または類似したコンテンツを作成してプレビューし、そのリンクを PR に追加するよう提案します。
      • 手順は簡潔にし、レビュー担当者が実行できる内容にします。
   4. 次の手順に沿って CMS コンテンツを作成するようユーザーに案内します：
      • ブラウザーでローカルのテストコンテンツを開きます：http://localhost:3000/drafts/tmp/[test-file]
      • AEM Sidekick 拡張機能を右クリックします。
      • 「View document source」オプションをクリックします。
      • コピー ボタンでドキュメントのコンテンツをコピーします。
      • Word／Google Docs／Document Authoring に貼り付けます（UE の場合はガイドとして使用してください。コピーと貼り付けは直接機能しません）。
      • CMS コンテンツをプレビューします。
   5. ユーザーがプレビュー URL を PR の説明に追加し、PR をレビュー可能な状態にします（または、ユーザーの指示を受けてエージェントが行います）。

PR の説明テンプレート：

すべての PR でこのテンプレートを使用し、関連するプレビューリンクをすべて含め、必要に応じて調整します：

## Description
Brief description of changes

[If an issue exists]
Fix #<gh-issue-id>

Test URLs:

[Repeat for all relevant test urls]
- Before: https://main--{repo}--{owner}.aem.page/{path}
- After: https://{branch}--{repo}--{owner}.aem.page/{path} 

[If only local test content (draft PR):]

This PR is currently a **draft** pending creation of CMS test content.

### Next Steps to Complete PR:

[add relevant steps here]

成功基準：

• ✅ 適切なメッセージ形式と帰属情報を付けて変更をコミットしている
• ✅ フィーチャーブランチにプッシュしている（main ではない）
• ✅ 説明にプレビューリンクを含めて PR を作成している

PR を作成し、レビュー可能な状態にしたら、ToDo を完了としてマークします

---

関連スキル

• analyze-and-plan：要件分析と受け入れ基準のため、ステップ 2 で呼び出されます。
• content-modeling：コンテンツモデルを設計するため、ステップ 3 で呼び出されます。
• da-auth：コンテンツを DA にプッシュする場合や、DA のプレビューをプログラムで実行する場合は、有効な Adobe IMS トークンを取得します。DA を使用する場合、ステップ 4 の開始時に呼び出します。
• find-test-content：既存のコンテンツを探すため、ステップ 4 のオプション C で呼び出されます。
• building-blocks：実装のため、ステップ 5 で呼び出されます。
• testing-blocks：ブラウザーでのテストのため、building-blocks から呼び出されます。
• block-collection-and-party：類似するブロックや参考となる実装を探すために使用します。

避けるべきアンチパターン

CDD の原則に反するよくある間違い：

• ❌ コンテンツモデルを理解する前にコーディングを始める
• ❌ 実際の例を確認せずにコンテンツ構造について推測する
• ❌ 開発者には使いやすく、作成者には使いにくいコンテンツモデルを作る
• ❌ 「時間を節約する」ためにコンテンツ作成を省略する（後で余計に時間がかかります）

リソース

• 考え方： references/cdd-philosophy.md - コンテンツファーストが重要な理由
• HTML 構造： references/html-structure.md - ローカルの HTML テストファイルを作成するためのガイド