development

プロジェクト引き継ぎ — 開発

開発者向けの包括的な技術ガイドを生成します。このスキルはコードベースを分析し、開発者がプロジェクトを理解、保守、拡張するための実用的なドキュメントを作成します。

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

• 新しい開発者のプロジェクトへのオンボーディング
• 保守チームへの技術的な引き継ぎ
• コードレビューとアーキテクチャドキュメントの作成
• 開発者向けドキュメントの作成

---

ステップ 0：プロジェクトのルートに移動して Edge Delivery Services プロジェクトを確認する（条件付き）

allGuides フラグが設定されている場合は、このステップをスキップしてください（オーケストレーターによる確認と移動はすでに完了しています）。

重要：スキップしない場合は、必ず cd コマンドを実行してください。絶対パスは使用せず、実際にディレクトリを変更してください。

ALL_GUIDES=$(cat .claude-plugin/project-config.json 2>/dev/null | node -e "
  const d = require('fs').readFileSync(0,'utf8');
  try { console.log(JSON.parse(d).allGuides ? 'true' : ''); } catch(e) { console.log(''); }
")
if [ -z "$ALL_GUIDES" ]; then
  # Navigate to git project root (works from any subdirectory)
  cd "$(git rev-parse --show-toplevel)"
  # Verify it's an Edge Delivery Services project
  ls scripts/aem.js
fi

重要：

• 上記の cd コマンドは Bash ツールを使用して必ず実行してください
• 以降のすべてのステップはプロジェクトのルートから実行してください
• 確認に絶対パスを使用せず、実際に移動してください
• ガイドは project-root/project-guides/ に作成されます

スキップせず、scripts/aem.js が存在しない場合は、次のように応答してください：

「このスキルは AEM Edge Delivery Services プロジェクト向けに設計されています。現在のディレクトリは Edge Delivery Services プロジェクトではないようです（scripts/aem.js が見つかりません）。

Edge Delivery Services プロジェクトに移動してから、もう一度お試しください。」

確認に失敗した場合は停止してください。それ以外の場合は続行してください。これでプロジェクトのルートに移動しました。

---

コミュニケーションガイドライン

• 生成するドキュメントやチャットでの応答では、Edge Delivery Services の略称として「EDS」を絶対に使用しないでください
• 必ず正式名称の「Edge Delivery Services」または「AEM Edge Delivery Services」を使用してください
• これはすべての出力ファイル（PDF、HTML、Markdown）とユーザーとのすべてのやり取りに適用されます

---

⚠️ 必須の保存先パス

ファイルは必ず次の正確なパスに保存してください：

project-guides/DEVELOPER-GUIDE.md

ファイルを書き込む前に：

1. まずディレクトリを作成します：mkdir -p project-guides
2. 次に project-guides/DEVELOPER-GUIDE.md に書き込みます

重要な理由： 適切な整理と PDF 変換のため、ファイルは project-guides/ に配置する必要があります。

❌ 誤り： DEVELOPER-GUIDE.md（ルート） ❌ 誤り： docs/DEVELOPER-GUIDE.md ❌ 誤り： /workspace/DEVELOPER-GUIDE.md ✅ 正しい： project-guides/DEVELOPER-GUIDE.md

---

出力形式

必須の出力： project-guides/DEVELOPER-GUIDE.pdf

厳禁事項：

• ❌ fstab.yaml を読み取ったり分析したりしないでください。ほとんどのプロジェクトには存在せず、すべてのサイトが示されているわけではありません
• ❌ .plain.html ファイルを作成しないでください
• ❌ convert_markdown_to_html ツールを使用しないでください。このツールは生のフロントマターが表示される状態でガイド全体を HTML に変換するため、これは望ましくありません
• ❌ ユーザーに「Markdown を手動で PDF に変換してください」と伝えないでください
• ❌ Markdown をルートディレクトリや project-guides/ 以外のパスに保存しないでください
• ❌ 「PDF は後で生成されます」や「セッション終了時に生成されます」と言わないでください。今すぐ生成してください

必須のワークフロー：

1. mkdir -p project-guides を実行して、ディレクトリが存在することを確認します
2. YAML フロントマター（タイトル、日付）を含む Markdown コンテンツを生成します
3. project-guides/DEVELOPER-GUIDE.md に保存します（正確なパス。例外なし）
4. 直ちに PDF 変換を実行します（フェーズ 5.1 を参照）
5. すべてのソースファイルを削除します（PDF のみ残します）
6. 最終出力：project-guides/DEVELOPER-GUIDE.pdf

---

実行チェックリスト

- [ ] Phase 1: Gather Project Information
- [ ] Phase 2: Analyze Project Architecture
- [ ] Phase 3: Document Design System
- [ ] Phase 4: Document Blocks, Models, and Templates
- [ ] Phase 5: Generate Professional PDF

---

フェーズ 0：組織名を取得する（最初に必須）

このスキルを実行する際は常に、ユーザーが直接（例：「開発者ガイドを生成して」）または引き継ぎフロー経由で起動したかどうかにかかわらず、他の作業を行う前に Config Service の組織名を取得する必要があります。このフェーズをスキップしないでください。

0.1 保存済みの組織名を確認する

# Check if org name is already saved
cat .claude-plugin/project-config.json 2>/dev/null | node -e "
  const d = require('fs').readFileSync(0,'utf8');
  try { const o = JSON.parse(d).org; if(o) console.log('org: ' + o); } catch(e) {}
"

0.2 組織名のプロンプト（未保存の場合）

組織名が保存されていない場合、必ず一旦停止し、ユーザーに直接尋ねてください。

"Config Service の組織名を教えてください。これは Edge Delivery Services の URL における {org} の部分です（例：https://main--site--{org}.aem.page）。組織名は GitHub の組織名と異なる場合があります。"

重要なルール：

• 定義済みの選択肢を使って AskUserQuestion を使用しないでください — 通常のテキストで質問してください
• 組織名は必須です — 「スキップ」の選択肢を提示しないでください
• 続行する前に、ユーザーが組織名を入力するのを待ってください
• ユーザーが有効な組織名を提示しない場合は、再度尋ねてください

0.3 組織名を保存する

保存済みの設定またはユーザー入力から組織名を取得したら、今後のために保存してください。

# Create config directory if needed
mkdir -p .claude-plugin
# Ensure .claude-plugin is in .gitignore (contains project config)
grep -qxF '.claude-plugin/' .gitignore 2>/dev/null || echo '.claude-plugin/' >> .gitignore

# Save org name to config file (create or update)
if [ -f .claude-plugin/project-config.json ]; then
  cat .claude-plugin/project-config.json | sed 's/"org"[[:space:]]*:[[:space:]]*"[^"]*"/"org": "{ORG_NAME}"/' > /tmp/project-config.json && mv /tmp/project-config.json .claude-plugin/project-config.json
else
  echo '{"org": "{ORG_NAME}"}' > .claude-plugin/project-config.json
fi

{ORG_NAME} をユーザーが指定した実際の組織名に置き換えてください。

---

フェーズ 1：プロジェクト情報の収集

1.1 プロジェクトの URL とリポジトリを取得する

# Get repository info
git remote -v | head -1

# Get branch info
git branch -a | head -10

抽出する情報：

• リポジトリの所有者と名前
• メインブランチ名

1.2 設定方法を確認する

# Check for helix-config (very old projects)
ls helix-config.yaml 2>/dev/null && echo "Uses legacy helix-config" || echo "Uses Config Service (modern)"

記録する内容： プロジェクトの設定方法（モダンなプロジェクトでは Config Service）。

1.3 Config Service API を使用してサイトを取得する

⚠️ 必須のデータソース — 代替手段は禁止

必ず Config Service API を呼び出してください。サイト情報のソースとして認められるのはこれだけです。

❌ 禁止されている方法（誤った結果が生成されます）：

• fstab.yaml を分析する — リポジトリを使用しない構成では、すべてのサイトが表示されません
• README.md を読む — 情報が古い、または不完全な場合があります
• コードベースの構造から推測する — CDN の設定や追加のサイトを見落とします
• git のリモート URL を使用する — 組織名が Config Service の組織名と異なる場合があります
• プロジェクトフォルダー名に基づいて推測する

✅ 必須：実行してレスポンスを保存する：

ORG=$(cat .claude-plugin/project-config.json | node -e "
  const d = require('fs').readFileSync(0,'utf8');
  console.log(JSON.parse(d).org || '');
")

# Save response to file - Phase 2 depends on this file
curl -s -H "Accept: application/json" "https://admin.hlx.page/config/${ORG}/sites.json" > .claude-plugin/sites-config.json

📁 必須の成果物： .claude-plugin/sites-config.json

API リファレンス： https://www.aem.live/docs/admin.html#tag/siteConfig/operation/getConfigSites

---

レスポンスは sites 配列を含む JSON オブジェクトです（各エントリに name フィールドがあります）。サイト名を抽出し、サイトごとの URL を作成してください。

• プレビュー： https://main--{site-name}--{org}.aem.page/
• ライブ： https://main--{site-name}--{org}.aem.live/

サイトが複数の場合は リポジトリを使用しない構成、1 つの場合は 標準構成 です。

次に、コードとコンテンツの詳細を確認するため、個々のサイト設定を取得してください。

まず、有効な認証トークンがあるか確認してください。

IMS_TOKEN=$(node -e "
  const fs = require('fs');
  try {
    const t = JSON.parse(fs.readFileSync(process.env.HOME + '/.aem/ims-token.json', 'utf8'));
    if (t.imsToken && t.imsTokenExpiry > Math.floor(Date.now()/1000) + 60) {
      process.stdout.write(t.imsToken);
    }
  } catch (e) {}
")

if [ -z "$IMS_TOKEN" ]; then
  echo "AUTH_REQUIRED"
fi

AUTH_REQUIRED の場合、続行する前に認証スキルを呼び出してください。

Skill({ skill: "project-management:auth" })

次に、サイト設定を取得してください。

IMS_TOKEN=$(node -e "
  const fs = require('fs');
  try {
    const t = JSON.parse(fs.readFileSync(process.env.HOME + '/.aem/ims-token.json', 'utf8'));
    process.stdout.write(t.imsToken || '');
  } catch (e) {}
")
curl -s -H "Authorization: Bearer ${IMS_TOKEN}" "https://admin.hlx.page/config/${ORG}/sites/{site-name}.json"

レスポンスの例：

{
  "code": {
    "owner": "github-owner",
    "repo": "repo-name",
    "source": { "type": "github", "url": "https://github.com/owner/repo" }
  },
  "content": {
    "source": {
      "url": "https://content.da.live/org-name/site-name/",
      "type": "markup"
    }
  }
}

レスポンスから抽出する情報：

• code.owner / code.repo — GitHub リポジトリ
• content.source.url — コンテンツのマウントパス（例：https://content.da.live/org/site/）
• content.source.type — コンテンツソースの種類（markup、onedrive、google）

⚠️ fstab.yaml は使用しないでください — 代わりに Config Service API を使用してください。

結果を記録してください（リポジトリを使用しない構成または標準構成）。これは、aem up に --pages-url フラグを含めるかどうかを判断するため、ローカル開発環境のセットアップのセクションで使用します。

1.4 Node.js の要件を確認する

# Check for Node version requirements
cat .nvmrc 2>/dev/null || cat package.json | grep -A2 '"engines"'

---

フェーズ 2：プロジェクトアーキテクチャの分析

フェーズ 1 のサイト設定を読み取ります：

cat .claude-plugin/sites-config.json

2.1 プロジェクト構成をマッピングする

# List top-level structure
ls -la

# List blocks
ls -la blocks/

# List scripts
ls -la scripts/

# List styles
ls -la styles/

# Check for templates
ls -la templates/ 2>/dev/null || echo "No templates folder"

2.2 ボイラープレートとカスタムファイルを特定する

重要： 実際にカスタマイズされたファイルのみを記載してください。

# Check commit history for a file (skip if only "Initial commit")
git log --oneline --follow {file_path} | head -5

# Check who modified a file (skip aem-aemy[bot] only files)
git log --format="%an - %s" --follow {file_path} | head -5

絞り込みのルール：

Git 履歴	対応
「Initial commit」のみ	省略 — ボイラープレートのデフォルトで、作業されたことがありません
aem-aemy[bot] によるコミットのみ	省略 — 自動生成されたものです
チームによる複数のコミット	記載 — カスタマイズされています
機能の説明を含むコミット	記載 — カスタマイズされています

重要： 「initial commit」しかないファイルは、一度も変更されていないボイラープレートのデフォルトです。開発者ガイドに価値を加えないため、記載しないでください。

2.3 scripts/aem.js（コアライブラリ）を分析する

# List what aem.js exports (DO NOT MODIFY this file)
grep -E "^export" scripts/aem.js

プロジェクトが aem.js からインポートする関数を記録します（例：sampleRUM、loadHeader、loadFooter、decorateBlock、loadBlock、loadCSS）。これにより、開発者は利用可能なコアユーティリティを把握できます。

2.4 scripts/scripts.js（Eager + Lazy フェーズ）を分析する

# Extract imports and key function signatures
grep -E "^import|^export|^function|^async function|buildAutoBlocks|loadTemplate|getLanguage|getSiteRoot|decorateMain|loadEager|loadLazy|loadDelayed" scripts/scripts.js

以下のカスタマイズを記録します：

確認するパターン	記録する内容
import 文	aem.js および utils.js からインポートするもの
loadEager / loadLazy 関数	E-L-D フェーズに追加されたカスタムロジック
buildAutoBlocks 関数	自動ブロック化ロジック
loadTemplate またはテンプレート処理	テンプレートシステム
getLanguage または言語検出	多言語設定
getSiteRoot またはサイト検出	マルチサイト構成（Phase 1.3 も参照）
カスタムの decorateMain への追加	ページ装飾の拡張
外部スクリプトの読み込み	どのフェーズで読み込まれるか — eager で読み込まれる場合はフラグを付ける（パフォーマンスリスク）

E-L-D の確認： LCP に影響する可能性がある、loadEager または loadLazy に追加されたサードパーティスクリプトや重いロジックを記録します。通常、これらは delayed.js に配置する必要があります。

2.5 scripts/delayed.js（Delayed フェーズ）を分析する

# Extract imports and function calls to identify integrations
grep -E "^import|function|google|analytics|gtag|alloy|martech|OneTrust|launch|chatbot|widget" scripts/delayed.js

記録する項目：

• アナリティクス連携（Google Analytics、Adobe Analytics など）
• マーケティングツール（OneTrust、チャットウィジェットなど）
• パフォーマンス監視
• カスタムの遅延機能
• レンダリングに不可欠なコードがこのファイルに含まれていないことを確認します（ページ読み込みの約 3 秒後に読み込まれます）

2.6 ユーティリティ関数を確認する

# Extract exported functions from utils
grep -E "^export|^function" scripts/utils.js 2>/dev/null || echo "No utils.js"

# List all script files
ls scripts/*.js

# Check which blocks/scripts import from utils
grep -rl "utils.js" blocks/ scripts/ 2>/dev/null

記録する項目： 共通ユーティリティ関数、その目的、およびそれらをインポートするブロックやスクリプト。

2.7 外部依存関係を確認する

# Check package.json for dependencies
grep -A 20 '"dependencies"' package.json 2>/dev/null | head -25

# Check for CDN imports in code
grep -r "cdn\|unpkg\|jsdelivr" scripts/ blocks/ --include="*.js" 2>/dev/null

---

フェーズ 3：デザインシステムを記録する

4.1 CSS カスタムプロパティを抽出する

# Get all CSS variables from styles.css
grep -E "^\s*--" styles/styles.css

カテゴリごとに整理します：

カテゴリ	プロパティの例
タイポグラフィ	--body-font-family、--heading-font-family、--font-size-*
色	--primary-color、--background-color、--text-color
余白	--spacing-*、--nav-height、--section-padding
レイアウト	--content-width、--grid-gap

4.2 フォント設定を記録する

# Extract font-face declarations (font names, weights, formats)
grep -E "@font-face|font-family|font-weight|src:" styles/fonts.css 2>/dev/null

# Check fonts directory
ls fonts/ 2>/dev/null

記録する項目：

• フォントファイルと形式
• フォントファミリー名
• 使用可能なフォントウェイト
• フォールバックフォント

4.3 ブレークポイントを記録する

# Find media query breakpoints
grep -E "@media.*min-width|@media.*max-width" styles/styles.css | sort -u

標準的な EDS ブレークポイント：

• モバイル：< 600px
• タブレット：600px - 899px
• デスクトップ：900px+
• 大画面：1200px+

標準からの逸脱があれば記録します。

4.4 セクションスタイルを記録する

# Find section-related styles
grep -A 5 "\.section\." styles/styles.css
grep -A 5 "\.section\[" styles/styles.css

利用可能なセクションスタイルを記録します（dark、highlight、narrow など）。

---

フェーズ 4：ブロック、モデル、テンプレートを記録する

ボイラープレートのフィルタリング（ブロック、モデル、テンプレートに適用）

すべてのフィルタリングはサイレントで実行します — 出力をユーザーに表示しないでください。

• 含める：コミットが 2 件以上あり、かつ「initial commit」後のコミットが 1 件以上ある項目
• 除外する：「Initial commit」または類似のボイラープレート設定のみのコミットが 1 件だけある項目
• 除外する：aem-aemy[bot] のコミットのみの項目（自動生成）
• 「initial commit」だけがある項目はカスタマイズされていません — 記録しないでください。

4.1 カスタマイズされたブロックを特定して分析する

フィルタリングを通過した各ブロックについて、次を実行します：

# Get block purpose from JS comments/structure
head -30 blocks/{blockname}/{blockname}.js

# Get block variants from CSS
grep -E "^\." blocks/{blockname}/{blockname}.css | head -30

# Check for variant handling
grep -E "classList\.contains|classList\.add" blocks/{blockname}/{blockname}.js

カスタマイズされた各ブロックについて記録する項目：

フィールド	記録する内容
名前	ブロックのフォルダー名
目的	コード分析から分かる機能
DOM 入力	CMS から想定される HTML 構造
DOM 出力	装飾後に変換された構造
バリアント	動作を変更する CSS クラス
依存関係	外部ライブラリ、他のブロック、ユーティリティ
主な関数	重要な内部関数

4.2 ブロックの依存関係を記録する

grep "^import" blocks/{blockname}/{blockname}.js

4.3 Universal Editor モデルのドキュメント化（カスタマイズされている場合）

models/*.json にも同じボイラープレートのフィルタリングを適用します。変更されていない標準のボイラープレートモデル（_page.json、_section.json、_button.json、_image.json、_text.json、_title.json）も除外します。すべてのモデルがボイラープレートの場合は、このセクションを出力から省略します。

4.4 カスタマイズされたテンプレートのドキュメント化

templates/*/ にも同じボイラープレートのフィルタリングを適用します。カスタマイズされたテンプレートごとに、目的、適用方法（メタデータ内の template: name）、変更内容を記載します。

---

フェーズ 5：開発者ガイドの生成

出力ファイル：project-guides/DEVELOPER-GUIDE.md

次の構成で Markdown ドキュメントを生成します。

# [Project Name] - Developer Guide

## Quick Reference

| Resource | URL |
|----------|-----|
| Code Repository | {code.owner}/{code.repo} (from Config Service — may be GitHub or Cloud Manager) |
| Preview | https://main--{repo}--{owner}.aem.page/ |
| Live | https://main--{repo}--{owner}.aem.live/ |
| Local Dev | http://localhost:3000 |

## Architecture Overview

### Tech Stack
- Vanilla JavaScript (ES6+)
- CSS3 with Custom Properties
- No build step - files served directly
- Content from Document Authoring (DA)

### Project Structure

├── blocks/ # [X] 個のブロックを実装済み ├── templates/ # [Y] 個のテンプレート（または N/A） ├── scripts/ │ ├── aem.js # コアライブラリ（変更禁止） │ ├── scripts.js # カスタムページ装飾 │ ├── delayed.js # アナリティクス、マーケティングツール │ └── utils.js # 共有ユーティリティ ├── styles/ │ ├── styles.css # 重要なスタイル＋デザイントークン │ ├── fonts.css # フォント定義 │ └── lazy-styles.css # 重要度の低いスタイル └── icons/ # SVG アイコン

### Three-Phase Loading (E-L-D)

Edge Delivery Services uses a strict Eager-Lazy-Delayed loading strategy to achieve a Lighthouse score of 100. Every file and script must be placed in the correct phase.

| Phase | Purpose | What Loads | Performance Impact |
|-------|---------|------------|-------------------|
| **Eager** | Render above-the-fold content as fast as possible (LCP) | `styles/styles.css`, first section's blocks, `scripts/scripts.js` | Blocks LCP — keep minimal |
| **Lazy** | Load remaining page content after first paint | Remaining blocks, header, footer, `fonts.css`, `lazy-styles.css` | Runs after Eager completes — safe for non-critical UI |
| **Delayed** | Load non-essential third-party scripts | `scripts/delayed.js` (analytics, marketing tags, chat widgets) | Runs ~3s after page load — never blocks rendering |

**Rules for developers:**
- **Never add third-party scripts to `scripts.js`** — they block LCP. Always use `delayed.js`.
- **Never load fonts eagerly** — `fonts.css` is loaded lazily to avoid render-blocking.
- Blocks in the first section load eagerly; all others load lazily. This is automatic based on DOM position.
- The header and footer are loaded in the lazy phase via `loadHeader()` / `loadFooter()` from `aem.js`.

### Key Files & How They Connect

| File | Role | Connects To |
|------|------|-------------|
| `scripts/aem.js` | Core library — `loadBlock`, `loadCSS`, `decorateBlock`, `sampleRUM`, `loadHeader`/`loadFooter`. **DO NOT MODIFY.** | Imported by `scripts.js` and blocks |
| `scripts/scripts.js` | Entry point — orchestrates E-L-D phases (`loadEager` → `loadLazy` → `loadDelayed`). Contains `buildAutoBlocks`, `decorateMain`, template loading. | Imports from `aem.js`; may import `utils.js` |
| `scripts/delayed.js` | Loaded last via `loadDelayed()` — analytics, marketing tags, third-party scripts. | Called by `scripts.js` in delayed phase |
| `scripts/utils.js` | Shared helpers used across blocks and scripts. | Imported by blocks and `scripts.js` |
| `styles/styles.css` | Critical CSS + design tokens (CSS custom properties). Loaded eagerly. | Referenced by all blocks and pages |
| `styles/fonts.css` | Font `@font-face` declarations. Loaded lazily. | Font families referenced in `styles.css` |
| `styles/lazy-styles.css` | Non-critical global styles. Loaded lazily. | Supplements `styles.css` |
| `blocks/{name}/{name}.js` | Block logic — exports `default function decorate(block)`. Auto-loaded when the block class appears in DOM. | May import from `utils.js` or `aem.js` |
| `blocks/{name}/{name}.css` | Block styles — auto-loaded alongside block JS. | May use CSS custom properties from `styles.css` |
| `templates/{name}/{name}.js` | Template logic — loaded when page metadata has matching `template` value. Customizes page structure before blocks load. | Called by `scripts.js` via `loadTemplate()` |

**Execution flow:** page load → `scripts.js` → `loadEager()` (first section + eager blocks) → `loadLazy()` (remaining blocks, header, footer, `fonts.css`, `lazy-styles.css`) → `loadDelayed()` (loads `delayed.js`)

## Local Development Setup

### Prerequisites
- Node.js [version from .nvmrc]
- AEM CLI: `npm install -g @adobe/aem-cli`

### Setup Steps
```bash
# Clone repository (use the code repo URL from Config Service)
git clone {code-repo-url}
cd {repo}

# Install dependencies
npm install

# Start local server
aem up

ローカルサーバー

• URL： http://localhost:3000
• ファイルの変更時に自動で再読み込み
• デフォルトでプレビューコンテンツを使用

フェーズ 1.3 で repoless／マルチサイトが検出された場合、次のサブセクションも出力に含めます。

ローカルサーバー — Repoless／マルチサイト

複数のサイトが 1 つのリポジトリを共有する repoless の構成では、ローカルサーバーの起動時にサイトのプレビュー URL を指定する必要があります。

aem up --pages-url=https://main--{site}--{org}.aem.page

{site} と {org} は、Config Service に登録されている実際のサイト名と組織名に置き換えます。

--pages-url を指定しないと、AEM CLI は正しいサイトのコンテンツを解決できず、ローカルプレビューが失敗するか、誤ったコンテンツが表示されます。

標準的なシングルサイト構成の場合、repoless のサブセクション全体を省略します。記載すると、開発者を混乱させるだけです。

リンティング

npm run lint

デザインシステム

CSS カスタムプロパティ

タイポグラフィ

--body-font-family: [value];
--heading-font-family: [value];

色

--primary-color: [value];
--secondary-color: [value];
--background-color: [value];
--text-color: [value];

間隔

--spacing-s: [value];
--spacing-m: [value];
--spacing-l: [value];
--nav-height: [value];

ブレークポイント

名前	最小幅	用途
モバイル	0	デフォルトのスタイル
タブレット	600px	@media (min-width: 600px)
デスクトップ	900px	@media (min-width: 900px)
大画面	1200px	@media (min-width: 1200px)

フォント

ファミリー	ウェイト	用途
[フォント名]	[ウェイト]	[本文／見出し]

ブロックリファレンス

ブロック	目的	バリアント	主な機能
[block-name]	[機能の説明]	variant1、variant2	[重要な詳細、注意点]

[カスタマイズされたブロックごとに 1 行生成]

テンプレート

テンプレート	目的	適用方法	特別な動作
[template-name]	[ページの種類]	template: [name]	[通常と異なる動作]

[カスタマイズされたテンプレートごとに 1 行生成。「initial commit」だけのテンプレートは省略]

よくある開発タスク

新しいブロックの追加

1. blocks/{name}/{name}.js を作成します
2. blocks/{name}/{name}.css を作成します
3. export default function decorate(block) を実装します
4. http://localhost:3000 でローカルテストします
5. フィーチャーブランチにプッシュします

グローバルスタイルの変更

1. styles/styles.css を編集します
2. CSS カスタムプロパティを使用します
3. 複数のページでテストします
4. CLS への影響に注意します

アナリティクス／マーケティングツールの追加

1. scripts/delayed.js に追加します
2. scripts.js には決して追加しないでください（パフォーマンスを低下させます）
3. Network タブで遅延読み込みを確認します

ブロックのデバッグ

1. ブラウザーのコンソールでエラーを確認します
2. DOM を調べ、想定される構造と実際の構造を比較します
3. バリアントクラスが適用されているか確認します
4. CSS の詳細度を確認します

環境

環境	URL パターン	目的
ローカル	http://localhost:3000	開発
フィーチャーブランチ	https://{branch}--{repo}--{owner}.aem.page	PR テスト
プレビュー	https://main--{repo}--{owner}.aem.page	ステージング
ライブ	https://main--{repo}--{owner}.aem.live	本番環境

Git ワークフロー

ブランチ名

• 機能：feature/description
• 修正：fix/description
• 名前は短くしてください（URL の長さに制限があるため）

PR の要件

1. PR の説明にプレビュー URL を含める
2. lint を通過する
3. フィーチャーブランチのプレビューでテストする
4. コンソールエラーがないこと

トラブルシューティング

ブロックが読み込まれない場合

1. ブロックのフォルダー名がクラス名と一致しているか確認します
2. JS で default function decorate がエクスポートされているか確認します
3. ブラウザーの Network タブで 404 がないか確認します

スタイルが適用されない場合

1. CSS の詳細度を確認します
2. ファイルが読み込まれているか（Network タブ）確認します
3. CSS の構文エラーがないか確認します

コンテンツが更新されない場合

1. ブラウザーのキャッシュをクリアします
2. DA でプレビューがトリガーされたか確認します
3. CDN キャッシュが反映されるまで待ちます（1～2 分）

リソース

リソース	URL
EDS ドキュメント	https://www.aem.live/docs/
開発者向けチュートリアル	https://www.aem.live/developer/tutorial
ブロックコレクション	https://www.aem.live/developer/block-collection
E-L-D の読み込み	https://www.aem.live/developer/keeping-it-100
ベストプラクティス	https://www.aem.live/docs/dev-collab-and-good-practices

サポート窓口

[プロジェクト固有の連絡先を追加]

---

### 5.1 Convert to Professional PDF (MANDATORY)

**THIS STEP IS NOT OPTIONAL. YOU MUST GENERATE THE PDF NOW.**

1. Save markdown to: `project-guides/DEVELOPER-GUIDE.md`
   - File MUST start with YAML frontmatter:
     ```yaml
     ---
     title: "[Project Name] - Developer Guide"
     date: "[Full Date - e.g., February 17, 2026]"
     ---
     ```
   - **Date format**: Always use full date with day, month, and year (e.g., "February 17, 2026"), NOT just month and year

2. **IMMEDIATELY after saving the markdown**, invoke the PDF conversion skill:

Skill({ skill: "project-management:whitepaper", args: "project-guides/DEVELOPER-GUIDE.md project-guides/DEVELOPER-GUIDE.pdf" })

3. Wait for PDF generation to complete (whitepaper skill auto-cleans source files)

**DO NOT:**
- Skip the PDF conversion step
- Tell user "PDF will be generated later" — generate it NOW

### 5.2 Deliver to User

After PDF is generated, inform the user:

"✓ Developer guide complete: project-guides/DEVELOPER-GUIDE.pdf"

---

## Output

**FINAL OUTPUT:** `project-guides/DEVELOPER-GUIDE.pdf`

All source files (.md, .html, .plain.html) are deleted after PDF generation. Only the PDF remains.

**Location:** `project-guides/` folder

---

## Success Criteria

**Data Source Validation (CRITICAL):**
- [ ] Config Service API was called (`https://admin.hlx.page/config/{ORG}/sites.json`)
- [ ] Site list came from API response, NOT from fstab.yaml or codebase analysis
- [ ] Repoless/standard determination came from Config Service, NOT inferred from code

**Content Validation:**
- [ ] Quick Reference with all project URLs
- [ ] Architecture overview accurate to project
- [ ] Design system fully documented (tokens, fonts, breakpoints)
- [ ] Project-specific blocks documented
- [ ] Custom scripts.js functions documented
- [ ] delayed.js integrations documented
- [ ] Templates documented (if applicable)
- [ ] Local development setup verified
- [ ] Common tasks have clear instructions
- [ ] Troubleshooting section covers common issues
- [ ] Resources linked

**Output Validation:**
- [ ] PDF generated successfully
- [ ] All source files cleaned up (only PDF remains)

---

## Tips for Clear Documentation

1. **Focus on what's unique** - Document project-specific implementations
2. **Use code examples** - Show actual code from the project
3. **Document the "why"** - Explain reasoning behind custom implementations
4. **Include gotchas** - Note any tricky behavior or edge cases
5. **Test the setup instructions** - Verify they work from scratch
6. **Keep it maintainable** - Don't over-document things that change often