handover-developer
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseProject 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 is set in (orchestrator already validated).
allGuides.claude-plugin/project-config.jsonbash
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
fiIf does not exist, tell the user this skill requires an AEM Edge Delivery Services project and stop.
scripts/aem.jsAll subsequent steps operate from project root. Guides are created at .
project-guides/如果中设置了(编排器已验证),则跳过此步骤。
.claude-plugin/project-config.jsonallGuidesbash
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如果不存在,告知用户此技能需要AEM Edge Delivery Services项目并停止操作。
scripts/aem.js后续所有步骤均从项目根目录执行。指南将创建在目录下。
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 PDFmarkdown
- [ ] 阶段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 thepart of your Edge Delivery Services URLs (e.g.,{org}). The org name may differ from your GitHub organization."https://main--site--{org}.aem.page
Ask as a plain text question — not with options. Organization name is mandatory.
AskUserQuestion如果未找到组织名称,询问用户:
"请输入您的Config Service组织名称。这是您Edge Delivery Services URL中的部分(例如:{org})。组织名称可能与您的GitHub组织名称不同。"https://main--site--{org}.aem.page
以纯文本问题形式询问——不要使用带选项的。组织名称为必填项。
AskUserQuestion0.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
fiReplace with the actual organization name.
{ORG_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"
fiIf , invoke the auth skill:
AUTH_REQUIREDSkill({ 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_REQUIREDSkill({ 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 -10Extract: 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 , README, or git remote URLs.
fstab.yamlbash
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.ownercode.repocontent.source.urlcontent.source.typeMultiple sites = repoless setup. Single site = standard setup. Record this — it affects the local dev instructions.
aem upConfig Service API是获取站点信息的唯一可靠来源。请勿使用、README或git远程URL。
fstab.yamlbash
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.ownercode.repocontent.source.urlcontent.source.type多站点设置 = 无代码仓库配置。单站点设置 = 标准配置。记录此信息——它会影响本地开发指令。
aem up1.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.json2.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 History | Action |
|---|---|
| Only "Initial commit" | Skip — boilerplate default, never worked on |
Only | Skip — auto-generated |
| Multiple commits by team | Document — customized |
仅记录实际被自定义的文件。
bash
git log --oneline --follow {file_path} | head -5
git log --format="%an - %s" --follow {file_path} | head -5| Git历史记录 | 操作 |
|---|---|
| 仅有"Initial commit" | 跳过——默认模板文件,未被修改过 |
仅包含 | 跳过——自动生成的文件 |
| 团队多次提交 | 记录——已被自定义 |
2.3 Analyze scripts/aem.js (Core Library)
2.3 分析scripts/aem.js(核心库)
bash
grep -E "^export" scripts/aem.jsDocument which functions the project imports from (e.g., , , , , , ).
aem.jssampleRUMloadHeaderloadFooterdecorateBlockloadBlockloadCSSbash
grep -E "^export" scripts/aem.js记录项目从中导入的函数(例如:、、、、、)。
aem.jssampleRUMloadHeaderloadFooterdecorateBlockloadBlockloadCSS2.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.jsDocument:
| Pattern | What to Document |
|---|---|
| What it imports from |
| Any custom logic added to E-L-D phases |
| Auto-blocking logic |
| Template system |
| Multi-language setup |
| Multi-site configuration |
| External script loading | Which 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记录:
| 模式 | 记录内容 |
|---|---|
| 从 |
| 添加到E-L-D阶段的自定义逻辑 |
| 自动区块化逻辑 |
| 模板系统 |
| 多语言设置 |
| 多站点配置 |
| 外部脚本加载 | 所在阶段——如果在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.jsDocument 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/nullDocument 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/nullbash
grep -A 20 '"dependencies"' package.json 2>/dev/null | head -25
grep -r "cdn\|unpkg\|jsdelivr" scripts/ blocks/ --include="*.js" 2>/dev/nullPhase 3: Document Design System
阶段3:记录设计系统
3.1 Extract CSS Custom Properties
3.1 提取CSS自定义属性
bash
grep -E "^\s*--" styles/styles.cssOrganize 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/nullDocument: 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 -uStandard 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.cssbash
grep -A 5 "\.section\." styles/styles.css
grep -A 5 "\.section\[" styles/styles.cssPhase 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 commits
aem-aemy[bot]
静默运行——不向用户显示输出。
- 包含:有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}.jsDocument for each customized block:
| Field | What to Record |
|---|---|
| Name | Block folder name |
| Purpose | What it does |
| DOM Input | Expected HTML structure from CMS |
| DOM Output | Transformed structure after decoration |
| Variants | CSS classes that modify behavior |
| Dependencies | External 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 . Exclude standard boilerplate models (, , , , , ) if unchanged. Skip section if all models are boilerplate.
models/*.json_page.json_section.json_button.json_image.json_text.json_title.json对应用模板文件过滤。如果标准模板模型(、、、、、)未被修改,则排除。如果所有模型均为模板文件,则跳过此部分。
models/*.json_page.json_section.json_button.json_image.json_text.json_title.json4.3 Document Customized Templates
4.3 记录自定义模板
Apply boilerplate filtering to . For each customized template, document purpose, how it's applied ( in metadata), and what it changes.
templates/*/template: name对应用模板文件过滤。为每个自定义模板记录用途、应用方式(元数据中的)以及修改内容。
templates/*/template: namePhase 5: Generate Developer Guide
阶段5:生成开发者指南
5.1 Output File
5.1 输出文件
Save to (run first).
project-guides/DEVELOPER-GUIDE.mdmkdir -p project-guidesRead for the full document structure. Fill in all sections using data gathered in Phases 1–4 — replace every with actual project values.
resources/developer-guide-template.md[placeholder]保存至(先运行)。
project-guides/DEVELOPER-GUIDE.mdmkdir -p project-guides读取获取完整文档结构。使用阶段1-4收集的数据填充所有部分——将每个替换为实际项目值。
resources/developer-guide-template.md[placeholder]5.2 Convert to Professional PDF
5.2 转换为专业PDF文件
Save the completed markdown to with YAML frontmatter (title, date using full date format e.g., "February 17, 2026"). Then immediately invoke PDF conversion:
project-guides/DEVELOPER-GUIDE.mdSkill({ 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.pdfInform the user: "Developer guide complete: project-guides/DEVELOPER-GUIDE.pdf"
将完成的Markdown文件保存至,并添加YAML前置元数据(标题、完整日期格式,例如:"2026年2月17日")。然后立即调用PDF转换:
project-guides/DEVELOPER-GUIDE.mdSkill({ 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
成功标准
| Category | Check |
|---|---|
| Data Source | Config Service API called ( |
| Data Source | Site list from API response, not fstab.yaml or codebase analysis |
| Data Source | Repoless/standard determination from Config Service, not inferred from code |
| Content | Quick Reference with all project URLs |
| Content | Architecture overview accurate to project |
| Content | Design system fully documented (tokens, fonts, breakpoints) |
| Content | Project-specific blocks documented |
| Content | Custom scripts.js functions documented |
| Content | delayed.js integrations documented |
| Content | Templates documented (if applicable) |
| Content | Local development setup verified |
| Content | Common tasks have clear instructions |
| Content | Troubleshooting section covers common issues |
| Output | PDF generated at |
| Output | All 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 ( |
| 数据源 | 站点列表来自API响应,而非fstab.yaml或代码库分析 |
| 数据源 | 无代码仓库/标准配置的判定来自Config Service,而非从代码推断 |
| 内容 | 快速参考包含所有项目URL |
| 内容 | 架构概述与项目实际情况一致 |
| 内容 | 设计系统已完整记录(令牌、字体、断点) |
| 内容 | 已记录项目特定区块 |
| 内容 | 已记录自定义scripts.js函数 |
| 内容 | 已记录delayed.js集成 |
| 内容 | 已记录模板(如适用) |
| 内容 | 本地开发设置已验证 |
| 内容 | 常见任务有清晰的说明 |
| 内容 | 故障排除部分涵盖常见问题 |
| 输出 | 已在 |
| 输出 | 所有源文件已清理(仅保留PDF) |
沟通要求: 切勿使用"EDS"缩写——在所有输出和文档中始终使用"Edge Delivery Services"或"AEM Edge Delivery Services"。