handover-developer

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Project Handover - Development

项目交接 - 开发

Generate a complete technical guide for developers. Analyzes the codebase and produces actionable documentation that enables developers to understand, maintain, and extend the project.

为开发者生成完整的技术指南。分析代码库并生成可执行的文档,帮助开发者理解、维护和扩展项目。

Step 0: Navigate to Project Root (CONDITIONAL)

步骤0:导航至项目根目录(可选)

Skip if
allGuides
is set in
.claude-plugin/project-config.json
(orchestrator already validated).
bash
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
If
scripts/aem.js
does not exist, tell the user this skill requires an AEM Edge Delivery Services project and stop.
All subsequent steps operate from project root. Guides are created at
project-guides/
.

如果
.claude-plugin/project-config.json
中设置了
allGuides
(编排器已验证),则跳过此步骤。
bash
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/
目录下。

Execution Checklist

执行清单

markdown
- [ ] 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

markdown
- [ ] 阶段0:获取组织名称并进行身份验证
- [ ] 阶段1:收集项目信息
- [ ] 阶段2:分析项目架构
- [ ] 阶段3:记录设计系统
- [ ] 阶段4:记录区块、模型和模板
- [ ] 阶段5:生成PDF文件

Phase 0: Get Organization Name and Authenticate

阶段0:获取组织名称并进行身份验证

0.1 Check for Saved Organization

0.1 检查已保存的组织信息

bash
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) {}
"
bash
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 Prompt for Organization Name (If Not Saved)

0.2 提示用户输入组织名称(如果未保存)

If no org name is found, ask the user:
"What is your Config Service organization name? This is the
{org}
part of your Edge Delivery Services URLs (e.g.,
https://main--site--{org}.aem.page
). The org name may differ from your GitHub organization."
Ask as a plain text question — not
AskUserQuestion
with options. Organization name is mandatory.
如果未找到组织名称,询问用户:
"请输入您的Config Service组织名称。这是您Edge Delivery Services URL中的
{org}
部分(例如:
https://main--site--{org}.aem.page
)。组织名称可能与您的GitHub组织名称不同。"
以纯文本问题形式询问——不要使用带选项的
AskUserQuestion
。组织名称为必填项。

0.3 Save Organization Name

0.3 保存组织名称

bash
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
Replace
{ORG_NAME}
with the actual organization name.
bash
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 Check Auth Token

0.4 检查身份验证令牌

bash
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
If
AUTH_REQUIRED
, invoke the auth skill:
Skill({ skill: "aem-project-management:auth" })

bash
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" })

Phase 1: Gather Project Information

阶段1:收集项目信息

1.1 Get Project URLs and Repository

1.1 获取项目URL和代码仓库

bash
git remote -v | head -1
git branch -a | head -10
Extract: repository owner, repo name, main branch name.
bash
git remote -v | head -1
git branch -a | head -10
提取:仓库所有者、仓库名称、主分支名称。

1.2 Check Configuration Method

1.2 检查配置方式

bash
ls helix-config.yaml 2>/dev/null && echo "Uses legacy helix-config" || echo "Uses Config Service (modern)"
bash
ls helix-config.yaml 2>/dev/null && echo "使用传统helix-config配置" || echo "使用Config Service(现代版)"

1.3 Fetch Sites via Config Service API

1.3 通过Config Service API获取站点信息

The Config Service API is the only reliable source for site information. Do not use
fstab.yaml
, README, or git remote URLs.
bash
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(', '));
"
If validation fails, verify the org name is correct, re-authenticate, and retry.
Fetch per-site config:
bash
curl -s -H "x-auth-token: ${AUTH_TOKEN}" \
  "https://admin.hlx.page/config/${ORG}/sites/{site-name}.json"
Extract:
code.owner
,
code.repo
,
content.source.url
,
content.source.type
.
Multiple sites = repoless setup. Single site = standard setup. Record this — it affects the
aem up
local dev instructions.
Config Service API是获取站点信息的唯一可靠来源。请勿使用
fstab.yaml
、README或git远程URL。
bash
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('未返回任何站点信息——请验证组织名称,必要时重新进行身份验证');
    process.exit(1);
  }
  console.log('找到 ' + j.sites.length + ' 个站点:' + j.sites.map(s => s.name).join(', '));
"
如果验证失败,请确认组织名称正确,重新进行身份验证后重试。
获取每个站点的配置:
bash
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
多站点设置 = 无代码仓库配置。单站点设置 = 标准配置。记录此信息——它会影响
aem up
本地开发指令。

1.4 Check Node.js Requirements

1.4 检查Node.js要求

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

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

Phase 2: Analyze Project Architecture

阶段2:分析项目架构

Read site config:
bash
cat .claude-plugin/sites-config.json
读取站点配置:
bash
cat .claude-plugin/sites-config.json

2.1 Map Project Structure

2.1 绘制项目结构

bash
ls -la && ls -la blocks/ && ls -la scripts/ && ls -la styles/
ls -la templates/ 2>/dev/null || echo "No templates folder"
bash
ls -la && ls -la blocks/ && ls -la scripts/ && ls -la styles/
ls -la templates/ 2>/dev/null || echo "无templates文件夹"

2.2 Identify Boilerplate vs Custom Files

2.2 区分模板文件与自定义文件

Only document files that were actually customized.
bash
git log --oneline --follow {file_path} | head -5
git log --format="%an - %s" --follow {file_path} | head -5
Git HistoryAction
Only "Initial commit"Skip — boilerplate default, never worked on
Only
aem-aemy[bot]
commits
Skip — auto-generated
Multiple commits by teamDocument — customized
仅记录实际被自定义的文件。
bash
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 Analyze scripts/aem.js (Core Library)

2.3 分析scripts/aem.js(核心库)

bash
grep -E "^export" scripts/aem.js
Document which functions the project imports from
aem.js
(e.g.,
sampleRUM
,
loadHeader
,
loadFooter
,
decorateBlock
,
loadBlock
,
loadCSS
).
bash
grep -E "^export" scripts/aem.js
记录项目从
aem.js
中导入的函数(例如:
sampleRUM
loadHeader
loadFooter
decorateBlock
loadBlock
loadCSS
)。

2.4 Analyze scripts/scripts.js

2.4 分析scripts/scripts.js

bash
grep -E "^import|^export|^function|^async function|buildAutoBlocks|loadTemplate|getLanguage|getSiteRoot|decorateMain|loadEager|loadLazy|loadDelayed" scripts/scripts.js
Document:
PatternWhat to Document
import
statements
What it imports from
aem.js
and
utils.js
loadEager
/
loadLazy
Any custom logic added to E-L-D phases
buildAutoBlocks
Auto-blocking logic
loadTemplate
/ template handling
Template system
getLanguage
/ language detection
Multi-language setup
getSiteRoot
/ site detection
Multi-site configuration
External script loadingWhich phase — flag if in eager (performance risk)
bash
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 Analyze scripts/delayed.js

2.5 分析scripts/delayed.js

bash
grep -E "^import|function|google|analytics|gtag|alloy|martech|OneTrust|launch|chatbot|widget" scripts/delayed.js
Document analytics integrations, marketing tools, performance monitoring. Confirm no render-critical code is in this file.
bash
grep -E "^import|function|google|analytics|gtag|alloy|martech|OneTrust|launch|chatbot|widget" scripts/delayed.js
记录分析集成、营销工具、性能监控。确认此文件中没有渲染关键代码。

2.6 Check for Utility Functions

2.6 检查工具函数

bash
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
Document shared utility functions and which blocks/scripts import them.
bash
grep -E "^export|^function" scripts/utils.js 2>/dev/null || echo "无utils.js文件"
ls scripts/*.js
grep -rl "utils.js" blocks/ scripts/ 2>/dev/null
记录共享工具函数以及哪些区块/脚本导入了这些函数。

2.7 Check for External Dependencies

2.7 检查外部依赖

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

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

Phase 3: Document Design System

阶段3:记录设计系统

3.1 Extract CSS Custom Properties

3.1 提取CSS自定义属性

bash
grep -E "^\s*--" styles/styles.css
Organize into categories: Typography, Colors, Spacing, Layout.
bash
grep -E "^\s*--" styles/styles.css
按类别整理:排版、颜色、间距、布局。

3.2 Document Font Setup

3.2 记录字体设置

bash
grep -E "@font-face|font-family|font-weight|src:" styles/fonts.css 2>/dev/null
ls fonts/ 2>/dev/null
Document: font files and formats, family names, weights, fallback fonts.
bash
grep -E "@font-face|font-family|font-weight|src:" styles/fonts.css 2>/dev/null
ls fonts/ 2>/dev/null
记录:字体文件及格式、字体族名称、字重、备用字体。

3.3 Document Breakpoints

3.3 记录断点

bash
grep -E "@media.*min-width|@media.*max-width" styles/styles.css | sort -u
Standard breakpoints: Mobile < 600px, Tablet 600-899px, Desktop 900px+, Large 1200px+. Document any deviations.
bash
grep -E "@media.*min-width|@media.*max-width" styles/styles.css | sort -u
标准断点:移动端 < 600px,平板端 600-899px,桌面端 900px+,大屏端 1200px+。记录任何偏差。

3.4 Document Section Styles

3.4 记录区块样式

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

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

Phase 4: Document Blocks, Models, and Templates

阶段4:记录区块、模型和模板

Boilerplate Filtering

模板文件过滤

Run silently — do not show output to user.
  • Include: Items with 2+ commits and at least one after "Initial commit"
  • Exclude: Items with only "Initial commit" or only
    aem-aemy[bot]
    commits
静默运行——不向用户显示输出。
  • 包含:有2次以上提交且至少有一次提交在"Initial commit"之后的项
  • 排除:仅有"Initial commit"或仅包含
    aem-aemy[bot]
    提交的项

4.1 Identify and Analyze Customized Blocks

4.1 识别并分析自定义区块

bash
head -30 blocks/{blockname}/{blockname}.js
grep -E "^\." blocks/{blockname}/{blockname}.css | head -30
grep -E "classList\.contains|classList\.add" blocks/{blockname}/{blockname}.js
Document for each customized block:
FieldWhat to Record
NameBlock folder name
PurposeWhat it does
DOM InputExpected HTML structure from CMS
DOM OutputTransformed structure after decoration
VariantsCSS classes that modify behavior
DependenciesExternal libraries, other blocks, utils
bash
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 Document Universal Editor Models (If Customized)

4.2 记录Universal Editor模型(如果已自定义)

Apply boilerplate filtering to
models/*.json
. Exclude standard boilerplate models (
_page.json
,
_section.json
,
_button.json
,
_image.json
,
_text.json
,
_title.json
) if unchanged. Skip section if all models are boilerplate.
models/*.json
应用模板文件过滤。如果标准模板模型(
_page.json
_section.json
_button.json
_image.json
_text.json
_title.json
)未被修改,则排除。如果所有模型均为模板文件,则跳过此部分。

4.3 Document Customized Templates

4.3 记录自定义模板

Apply boilerplate filtering to
templates/*/
. For each customized template, document purpose, how it's applied (
template: name
in metadata), and what it changes.

templates/*/
应用模板文件过滤。为每个自定义模板记录用途、应用方式(元数据中的
template: name
)以及修改内容。

Phase 5: Generate Developer Guide

阶段5:生成开发者指南

5.1 Output File

5.1 输出文件

Save to
project-guides/DEVELOPER-GUIDE.md
(run
mkdir -p project-guides
first).
Read
resources/developer-guide-template.md
for the full document structure. Fill in all sections using data gathered in Phases 1–4 — replace every
[placeholder]
with actual project values.
保存至
project-guides/DEVELOPER-GUIDE.md
(先运行
mkdir -p project-guides
)。
读取
resources/developer-guide-template.md
获取完整文档结构。使用阶段1-4收集的数据填充所有部分——将每个
[placeholder]
替换为实际项目值。

5.2 Convert to Professional PDF

5.2 转换为专业PDF文件

Save the completed markdown to
project-guides/DEVELOPER-GUIDE.md
with YAML frontmatter (title, date using full date format e.g., "February 17, 2026"). Then immediately invoke PDF conversion:
Skill({ skill: "aem-project-management:whitepaper", args: "project-guides/DEVELOPER-GUIDE.md project-guides/DEVELOPER-GUIDE.pdf" })
The whitepaper skill auto-cleans source files. Final output:
project-guides/DEVELOPER-GUIDE.pdf
.
Inform the user: "Developer guide complete: project-guides/DEVELOPER-GUIDE.pdf"

将完成的Markdown文件保存至
project-guides/DEVELOPER-GUIDE.md
,并添加YAML前置元数据(标题、完整日期格式,例如:"2026年2月17日")。然后立即调用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"

Success Criteria

成功标准

CategoryCheck
Data SourceConfig Service API called (
https://admin.hlx.page/config/{ORG}/sites.json
)
Data SourceSite list from API response, not fstab.yaml or codebase analysis
Data SourceRepoless/standard determination from Config Service, not inferred from code
ContentQuick Reference with all project URLs
ContentArchitecture overview accurate to project
ContentDesign system fully documented (tokens, fonts, breakpoints)
ContentProject-specific blocks documented
ContentCustom scripts.js functions documented
Contentdelayed.js integrations documented
ContentTemplates documented (if applicable)
ContentLocal development setup verified
ContentCommon tasks have clear instructions
ContentTroubleshooting section covers common issues
OutputPDF generated at
project-guides/DEVELOPER-GUIDE.pdf
OutputAll source files cleaned up (only PDF remains)

Communication: Never use "EDS" as an acronym — always write "Edge Delivery Services" or "AEM Edge Delivery Services" in all output and documentation.
类别检查项
数据源已调用Config Service API (
https://admin.hlx.page/config/{ORG}/sites.json
)
数据源站点列表来自API响应,而非fstab.yaml或代码库分析
数据源无代码仓库/标准配置的判定来自Config Service,而非从代码推断
内容快速参考包含所有项目URL
内容架构概述与项目实际情况一致
内容设计系统已完整记录(令牌、字体、断点)
内容已记录项目特定区块
内容已记录自定义scripts.js函数
内容已记录delayed.js集成
内容已记录模板(如适用)
内容本地开发设置已验证
内容常见任务有清晰的说明
内容故障排除部分涵盖常见问题
输出已在
project-guides/DEVELOPER-GUIDE.pdf
生成PDF文件
输出所有源文件已清理(仅保留PDF)

沟通要求: 切勿使用"EDS"缩写——在所有输出和文档中始终使用"Edge Delivery Services"或"AEM Edge Delivery Services"。