handover-developer

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

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

---

ステップ 0：プロジェクトルートへ移動（条件付き）

.claude-plugin/project-config.json で allGuides が設定されている場合はスキップします（オーケストレーターによる検証は完了しています）。

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
  cd "$(git rev-parse --show-toplevel)"
  ls scripts/aem.js
fi

scripts/aem.js が存在しない場合は、このスキルには AEM Edge Delivery Services プロジェクトが必要であることをユーザーに伝え、終了します。

以降のすべてのステップはプロジェクトルートから実行します。ガイドは project-guides/ に作成します。

---

実行チェックリスト

- [ ] Phase 0: Get org name and authenticate
- [ ] 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 PDF

---

フェーズ 0：組織名の取得と認証

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

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 組織名を保存する

mkdir -p .claude-plugin
grep -qxF '.claude-plugin/' .gitignore 2>/dev/null || echo '.claude-plugin/' >> .gitignore

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} を実際の組織名に置き換えます。

0.4 認証トークンを確認する

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

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

AUTH_REQUIRED の場合は、認証スキルを呼び出します。

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

---

フェーズ 1：プロジェクト情報を収集する

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

git remote -v | head -1
git branch -a | head -10

次の情報を抽出します：リポジトリの所有者、リポジトリ名、メインブランチ名。

1.2 設定方法を確認する

ls helix-config.yaml 2>/dev/null && echo "Uses legacy helix-config" || echo "Uses Config Service (modern)"

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

サイト情報の信頼できる唯一の情報源は Config Service API です。fstab.yaml、README、git のリモート URL は使用しないでください。

ORG=$(cat .claude-plugin/project-config.json | node -e "
  const d = require('fs').readFileSync(0,'utf8');
  console.log(JSON.parse(d).org || '');
")
AUTH_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.authToken || '');
  } catch (e) {}
")

curl -s -H "x-auth-token: ${AUTH_TOKEN}" -H "Accept: application/json" \
  "https://admin.hlx.page/config/${ORG}/sites.json" > .claude-plugin/sites-config.json

node -e "
  const d = require('fs').readFileSync('.claude-plugin/sites-config.json', 'utf8');
  const j = JSON.parse(d);
  if (!j.sites || !j.sites.length) {
    console.error('No sites returned — verify org name and re-authenticate if needed');
    process.exit(1);
  }
  console.log('Found ' + j.sites.length + ' site(s): ' + j.sites.map(s => s.name).join(', '));
"

検証に失敗した場合は、組織名が正しいことを確認し、再認証してから再試行します。

サイトごとの設定を取得します。

curl -s -H "x-auth-token: ${AUTH_TOKEN}" \
  "https://admin.hlx.page/config/${ORG}/sites/{site-name}.json"

次の情報を抽出します：code.owner、code.repo、content.source.url、content.source.type。

複数のサイトがある場合は repoless セットアップ、単一のサイトの場合は標準セットアップです。この情報を記録してください。aem up のローカル開発手順に影響します。

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

cat .nvmrc 2>/dev/null || cat package.json | grep -A2 '"engines"'

---

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

サイト設定を読み込みます。

cat .claude-plugin/sites-config.json

2.1 プロジェクト構造を把握する

ls -la && ls -la blocks/ && ls -la scripts/ && ls -la styles/
ls -la templates/ 2>/dev/null || echo "No templates folder"

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

実際にカスタマイズされたファイルのみをドキュメントに記載します。

git log --oneline --follow {file_path} | head -5
git log --format="%an - %s" --follow {file_path} | head -5

Git の履歴	対応
「Initial commit」のみ	スキップ — ボイラープレートのデフォルトであり、作業されたことがない
aem-aemy[bot] によるコミットのみ	スキップ — 自動生成されたもの
チームによる複数のコミット	記載 — カスタマイズ済み

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

grep -E "^export" scripts/aem.js

プロジェクトが aem.js からインポートしている関数（例：sampleRUM、loadHeader、loadFooter、decorateBlock、loadBlock、loadCSS）を記載します。

2.4 scripts/scripts.js を分析する

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 / サイト検出	マルチサイト設定
外部スクリプトの読み込み	読み込みフェーズ — eager にある場合はフラグを付ける（パフォーマンスリスク）

2.5 scripts/delayed.js を分析する

grep -E "^import|function|google|analytics|gtag|alloy|martech|OneTrust|launch|chatbot|widget" scripts/delayed.js

分析、マーケティングツール、パフォーマンス監視との連携を記載します。レンダリングに不可欠なコードがこのファイルにないことを確認します。

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

grep -E "^export|^function" scripts/utils.js 2>/dev/null || echo "No utils.js"
ls scripts/*.js
grep -rl "utils.js" blocks/ scripts/ 2>/dev/null

共有ユーティリティ関数と、それらをインポートしているブロックやスクリプトを記載します。

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

grep -A 20 '"dependencies"' package.json 2>/dev/null | head -25
grep -r "cdn\|unpkg\|jsdelivr" scripts/ blocks/ --include="*.js" 2>/dev/null

---

フェーズ 3：デザインシステムをドキュメント化する

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

grep -E "^\s*--" styles/styles.css

タイポグラフィ、色、間隔、レイアウトのカテゴリに分類します。

3.2 フォントの設定を記載する

grep -E "@font-face|font-family|font-weight|src:" styles/fonts.css 2>/dev/null
ls fonts/ 2>/dev/null

次の項目を記載します：フォントファイルと形式、ファミリー名、ウェイト、フォールバックフォント。

3.3 ドキュメントのブレークポイント

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

標準のブレークポイント：モバイル 600px 未満、タブレット 600〜899px、デスクトップ 900px 以上、大画面 1200px 以上です。異なる設定がある場合は記録してください。

3.4 セクションスタイルのドキュメント化

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

---

フェーズ 4：ブロック、モデル、テンプレートのドキュメント化

ボイラープレートのフィルタリング

サイレントに実行してください。ユーザーには出力を表示しないでください。

• 含める項目：コミットが 2 件以上あり、少なくとも 1 件が「Initial commit」より後にある項目
• 除外する項目：「Initial commit」のみ、または aem-aemy[bot] によるコミットのみの項目

4.1 カスタマイズされたブロックの特定と分析

head -30 blocks/{blockname}/{blockname}.js
grep -E "^\." blocks/{blockname}/{blockname}.css | head -30
grep -E "classList\.contains|classList\.add" blocks/{blockname}/{blockname}.js

カスタマイズされた各ブロックについて、以下を記録してください。

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

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

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

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

templates/*/ にボイラープレートのフィルタリングを適用します。カスタマイズされた各テンプレートについて、目的、適用方法（メタデータ内の template: name）、および変更内容を記録してください。

---

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

5.1 出力ファイル

project-guides/DEVELOPER-GUIDE.md に保存します（最初に mkdir -p project-guides を実行してください）。

resources/developer-guide-template.md を読み、ドキュメント全体の構成を確認してください。フェーズ 1〜4 で収集したデータを使ってすべてのセクションを埋め、すべての [placeholder] をプロジェクトの実際の値に置き換えてください。

5.2 プロフェッショナルな PDF への変換

完成した Markdown を、YAML フロントマター（タイトル、完全な日付形式（例：「February 17, 2026」）の日付を含む）とともに project-guides/DEVELOPER-GUIDE.md に保存します。その後、直ちに PDF 変換を実行してください。

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

ホワイトペーパーのスキルによってソースファイルは自動的にクリーンアップされます。最終出力：project-guides/DEVELOPER-GUIDE.pdf。

ユーザーに次のように伝えてください：「開発者ガイドが完成しました：project-guides/DEVELOPER-GUIDE.pdf」

---

成功基準

カテゴリー	確認項目
データソース	Config Service API が呼び出されている（https://admin.hlx.page/config/{ORG}/sites.json）
データソース	サイト一覧は fstab.yaml やコードベースの分析ではなく、API のレスポンスから取得している
データソース	Repoless／標準の判定はコードから推測せず、Config Service に基づいている
コンテンツ	すべてのプロジェクト URL を含むクイックリファレンス
コンテンツ	プロジェクトに即した正確なアーキテクチャの概要
コンテンツ	デザインシステムを完全に記録している（トークン、フォント、ブレークポイント）
コンテンツ	プロジェクト固有のブロックを記録している
コンテンツ	カスタムの scripts.js 関数を記録している
コンテンツ	delayed.js の連携を記録している
コンテンツ	テンプレートを記録している（該当する場合）
コンテンツ	ローカル開発環境のセットアップを検証している
コンテンツ	一般的なタスクについて明確な手順がある
コンテンツ	トラブルシューティングのセクションで一般的な問題を扱っている
出力	PDF が project-guides/DEVELOPER-GUIDE.pdf に生成されている
出力	すべてのソースファイルがクリーンアップされている（PDF のみが残っている）

---

コミュニケーション：「EDS」という略語は使用しないでください。出力とドキュメントでは、必ず「Edge Delivery Services」または「AEM Edge Delivery Services」と記載してください。