handover-admin

プロジェクト引き継ぎ - 管理者ガイド

AEM Edge Delivery Services プロジェクトを引き継ぐ管理者向けの包括的なドキュメントを生成します。Config Service の設定、権限、Admin API の操作、トラブルシューティングを網羅した管理者ガイドを作成します。

---

ステップ 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: Fetch project context from Config Service API
- [ ] Phase 2: Generate admin guide content
- [ ] Phase 3: Customize for project
- [ ] Phase 4: Convert to 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) {}
")
echo "auth=${AUTH_TOKEN:+set}"

有効なトークンが存在しない場合は、認証スキルを呼び出します。

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

0.5 認証を確認

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) {}
")
ORG=$(cat .claude-plugin/project-config.json | node -e "
  const d = require('fs').readFileSync(0,'utf8');
  console.log(JSON.parse(d).org || '');
")
STATUS=$(curl -s -w "%{http_code}" -o /dev/null \
  -H "x-auth-token: ${AUTH_TOKEN}" \
  "https://admin.hlx.page/config/${ORG}/sites.json")
echo "Auth check: HTTP $STATUS"

200 以外の場合は、続行する前に認証スキルを再実行します。

---

フェーズ 1：プロジェクトのコンテキストを収集

1.1 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(', '));
"

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

1.2 サイトごとの設定を取得

各サイトについて、設定を取得します。

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

次の情報を抽出します。

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

複数のサイトがある場合はリポジトリなしの構成です。サイトが 1 つの場合は標準構成です。

コンテキストを構築します。

Organization: {org}
Site(s): {site1}, {site2}, ...
Setup: {repoless | standard}
Code Repo: {owner}/{repo}
Preview: https://main--{site}--{org}.aem.page/
Live: https://main--{site}--{org}.aem.live/
Login: https://admin.hlx.page/login/{org}/{site}
Config: https://admin.hlx.page/config/{org}/

---

フェーズ 2：管理者ガイドを生成

出力ファイル：project-guides/ADMIN-GUIDE.md（最初に mkdir -p project-guides を実行します）。

---
title: "[Project Name] - Admin Guide"
date: "[Full Date — e.g., February 17, 2026]"
---

# [Project Name] - Admin Guide

Complete administration guide for managing this Edge Delivery Services project.

## Quick Reference

### URLs

| Purpose | URL |
|---------|-----|
| **Login** | https://admin.hlx.page/login/{org}/{site} |
| **Config Service** | https://admin.hlx.page/config/{org}/ |
| **Preview** | https://main--{site}--{org}.aem.page/ |
| **Live** | https://main--{site}--{org}.aem.live/ |

### Sites (if multi-site/repoless)

| Site | Content Source | Preview | Live |
|------|----------------|---------|------|
| {site1} | [from site config] | https://main--{site1}--{org}.aem.page/ | https://main--{site1}--{org}.aem.live/ |

## Authentication

### Login

1. Open: https://admin.hlx.page/login/{org}/{site}
2. Sign in with your credentials

### Logout

```bash
curl -X POST -H "x-auth-token: $AUTH_TOKEN" \
  "https://admin.hlx.page/logout/{org}/{site}/main"

ユーザー管理

現在のアクセス権を表示

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

ユーザーを追加

役割	コマンド
管理者	POST /config/{org}/sites/{site}/access/admin.json with {"users": ["email"]}
作成者	POST /config/{org}/sites/{site}/access/author.json with {"users": ["email"]}

ユーザーを削除

curl -X DELETE -H "x-auth-token: $AUTH_TOKEN" \
  "https://admin.hlx.page/config/{org}/sites/{site}/access/admin/{email}.json"

コンテンツ操作

操作	エンドポイント
ページをプレビュー	POST /preview/{org}/{site}/main/{path}
一括プレビュー	POST /preview/{org}/{site}/main/*
ページを公開	POST /live/{org}/{site}/main/{path}
一括公開	POST /live/{org}/{site}/main/*
公開を取り消す	DELETE /live/{org}/{site}/main/{path}
キャッシュを消去	POST /cache/{org}/{site}/main/{path}
すべて消去	POST /cache/{org}/{site}/main/*

コード操作

コードを同期

curl -X POST -H "x-auth-token: $AUTH_TOKEN" \
  "https://admin.hlx.page/code/{owner}/{repo}/main"

よくあるタスク

タスク	手順
新しい管理者を追加	/config/{org}/sites/{site}/access/admin.json に POST
サイトを再公開	/preview/{org}/{site}/main/* に POST してから /live/{org}/{site}/main/* に POST
すべてのキャッシュを消去	/cache/{org}/{site}/main/* に POST
コードの変更をデプロイ	/code/{owner}/{repo}/main に POST

トラブルシューティング

問題	解決策
401 Unauthorized	トークンの有効期限が切れています — 再度ログインしてください
403 Forbidden	権限が不足しています — 役割を確認してください
404 Not Found	組織名／サイト名／パスのスペルを確認してください
429 Rate Limited	待ってから再試行してください
キャッシュが消去されない	forceUpdate: true を指定して試してください
コードが同期されない	手動で同期します：/code/{owner}/{repo}/main に POST

リソース

リソース	URL
管理 API ドキュメント	https://www.aem.live/docs/admin.html
Config Service	https://www.aem.live/docs/config-service-setup

---

## Phase 3: Customize for Project

Replace all placeholders with values from the Config Service API:
- `{org}` → actual organization name
- `{site}` → actual site name(s)
- `{owner}` / `{repo}` → code owner and repo from site config

If multi-site (repoless), add a section listing all sites with their preview URL, live URL, and content source.

Check for and document project-specific configurations:
- Custom headers: `/config/{org}/sites/{site}/headers.json`
- CDN configuration
- Any project-specific admin procedures

---

## Phase 4: Convert to Professional PDF

Save the completed markdown to `project-guides/ADMIN-GUIDE.md`. The file must start with YAML frontmatter:

```yaml
---
title: "[Project Name] - Admin Guide"
date: "[Full Date — e.g., February 17, 2026]"
---

すぐに PDF 変換を実行します。

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

ホワイトペーパーのスキルがソースファイルを自動的にクリーンアップします。最終出力：project-guides/ADMIN-GUIDE.pdf。

ユーザーに「管理ガイドが完成しました：project-guides/ADMIN-GUIDE.pdf」と伝えます。

---

成功基準

カテゴリ	確認項目
データソース	Config Service API（https://admin.hlx.page/config/{ORG}/sites.json）が呼び出されている
データソース	サイト一覧が fstab.yaml やコードベースの分析ではなく、API の応答から取得されている
データソース	コードリポジトリの情報が git remote ではなく、サイト設定 API から取得されている
コンテンツ	すべての組織／サイトの値が Config Service API から入力されている
コンテンツ	ログイン URL が正しい
コンテンツ	すべての API エンドポイントで組織／サイトが正しい
コンテンツ	該当する場合、複数サイトについて記載されている
コンテンツ	一般的なタスクが正しいパスとともに記載されている
出力	PDF が project-guides/ADMIN-GUIDE.pdf に生成されている
出力	すべてのソースファイルがクリーンアップされている（PDF のみが残っている）

---

コミュニケーション： 省略形の「Edge Delivery Services」は使用せず、すべての出力およびドキュメントで「Edge Delivery Services」または「AEM Edge Delivery Services」と表記してください。