content-driven-development

内容驱动开发（CDD）

为 AEM Edge Delivery Services 编排内容驱动开发工作流。此工作流可确保代码基于真实内容构建，并采用便于作者使用的内容模型。

重要：在确定或创建用于测试更改的内容之前，切勿开始编写或修改代码。

何时使用此技能

所有 AEM 开发任务都应使用 CDD：

• ✅ 创建新区块
• ✅ 修改现有区块（结构或功能变更）
• ✅ 更改核心装饰功能
• ✅ 需要验证的错误修复
• ✅ 任何会影响作者创建或组织内容方式的代码

请勿用于：

• 仅修改文档
• 不影响内容创作的配置更改
• 尚不需要进行任何代码更改的研究任务

理念

内容驱动开发优先在编写代码之前创建或确定测试内容，以确保：

• 代码基于真实内容构建
• 内容模型便于作者使用
• 在整个开发过程中进行验证

可选：了解 CDD 原则

如果出现以下情况，请阅读 references/cdd-philosophy.md：

• 用户询问有关内容优先方法的“为什么”
• 你需要了解 CDD 决策背后的原因
• 你不确定应该优先考虑作者体验还是开发者体验

否则：请按照以下工作流步骤操作

步骤 0：创建 TodoList

**第一步：**使用 TodoWrite 工具创建包含以下 8 项任务的待办列表：

1. 启动开发服务器（如果尚未运行）

   • 成功标准：开发服务器正在运行，且可访问 http://localhost:3000

2. 分析并规划

   • 成功标准：记录清晰的理解，并定义验收标准

3. 设计内容模型

   • 成功标准：记录并验证内容结构

4. 确定或创建测试内容

   • 成功标准：可访问的测试内容覆盖所有场景

5. 实施

   • 成功标准：功能在所有视口中均可正常运行

6. Lint 并测试

   • 成功标准：所有检查均通过

7. 最终验证

   • 成功标准：满足所有验收标准，一切正常运行

8. 交付

   • 成功标准：已创建 PR，并附有用于验证的预览链接

**以下情况标记待办事项为已完成：**待办列表已创建，且包含全部 8 项任务

---

步骤 1：启动开发服务器

检查开发服务器是否正在运行：

curl -s -o /dev/null -w "%{http_code}" http://localhost:3000

预期结果：200（服务器正在运行）或连接错误（服务器未运行）

如果服务器未运行，请启动它：

aem up --no-open --forward-browser-logs

注意：

• 尽可能在后台运行（开发服务器需要保持运行）
• 需要全局安装 AEM CLI：npm install -g @adobe/aem-cli
• 替代方案：npx -y @adobe/aem-cli up --no-open --forward-browser-logs

**重要：**检查命令输出中的错误。常见问题：

• 端口 3000 已被占用
• 未安装 AEM CLI
• 配置错误

启动后，确认服务器正在运行：

curl -s -o /dev/null -w "%{http_code}" http://localhost:3000

预期结果：200

成功标准：

• ✅ 开发服务器正在运行
• ✅ http://localhost:3000 返回 200
• ✅ 服务器启动输出中没有错误

**以下情况标记待办事项为已完成：**已确认开发服务器正在运行且可访问

---

步骤 2：分析并规划

**调用：**analyze-and-plan 技能

提供：

• 用户提供的任务描述
• 用于匹配设计的屏幕截图、设计文件或现有 URL（如果有）

analyze-and-plan 技能将：

• 引导你进行针对任务的分析
• 帮助定义验收标准
• 根据需要分析提供的视觉设计稿或模型
• 创建记录分析结果的文档，供后续步骤参考

成功标准：

• ✅ 已分析需求
• ✅ 已定义验收标准
• ✅ 已将分析结果记录到文件中，供后续步骤使用

**以下情况标记待办事项为已完成：**已记录分析结果并定义验收标准

---

步骤 3：设计内容模型

跳过条件： 仅更改 CSS，且不影响内容结构

调用： content-modeling 技能

提供：

• 步骤 2 的分析（内容需求、作者输入）
• 区块名称和用途

content-modeling 技能将：

• 设计表格结构（行、列、语义格式）
• 根据最佳实践进行验证（每行 4 个单元格、语义格式）
• 为作者编写内容模型文档

成功标准：

• ✅ 已设计内容模型（已定义表格结构）
• ✅ 已根据最佳实践验证
• ✅ 已编写内容模型文档

完成条件： 内容模型已设计并编写文档

---

步骤 4：查找或创建测试内容

目标： 完成本步骤时，获取涵盖所有测试场景的可访问测试内容 URL

根据实际情况选择最佳方案：

---

选项 A：用户提供测试 URL

适用情况： 用户已有内容并提供了 URL

操作：

1. 验证 URL 是否可加载：curl -s -o /dev/null -w "%{http_code}" http://localhost:3000/path
2. 预期结果：状态码为 200
3. 记录 URL
4. 标记为已完成

---

选项 B：新建区块（没有现有内容）

适用情况： 正在构建一个全新的区块

操作：

1. 跳过搜索（目前没有可查找的内容）
2. 使用以下方法之一创建测试内容：

方法 1：CMS 内容（推荐）

1. 请用户在其 CMS（Google Drive/SharePoint/DA/Universal Editor）中创建内容
2. 提供步骤 3 中的内容模型作为参考
3. 等待用户提供 URL
4. 验证：curl -s -o /dev/null -w "%{http_code}" http://localhost:3000/path
5. 预期结果：状态码为 200

使用 DA： 如果需要以编程方式将 HTML 内容推送到 DA（而不是请用户撰写内容），请先调用 da-auth 技能以获取有效的 DA_TOKEN，然后使用 DA Admin API（POST https://admin.da.live/source/{org}/{repo}/{path}）推送内容并触发预览。

方法 2：本地 HTML（临时）

1. 在 drafts/tmp/{block-name}.plain.html 中创建 HTML 文件
2. 遵循步骤 3 中的内容模型结构
3. 阅读 references/html-structure.md，了解本地 HTML 文件格式指南
4. 重启开发服务器：aem up --html-folder drafts --no-open --forward-browser-logs
5. 验证：curl -s -o /dev/null -w "%{http_code}" http://localhost:3000/drafts/tmp/{block-name}
6. 预期结果：状态码为 200
7. 注意： 用户必须在 PR 前创建 CMS 内容（预览链接所必需）

---

选项 C：现有区块

适用情况： 修改、修复或设置现有区块的样式

操作：

首先：搜索现有内容

1. 调用 find-test-content 技能
2. 提供：区块名称、开发服务器 URL（可选，默认值为 localhost:3000）

find-test-content 将执行以下操作：

• 搜索包含该区块的现有内容页面
• 自动检测并报告找到的所有变体
• 报告：包含实例数量和变体信息的 URL

然后：评估搜索结果

如果找到的内容足够：

1. 记录 URL
2. 验证 URL 是否可加载：curl -s -o /dev/null -w "%{http_code}" http://localhost:3000/path
3. 预期结果：状态码为 200
4. 标记为已完成

如果未找到内容，或覆盖范围不足：

1. 使用选项 B 中的方法创建更多测试内容
2. 验证 URL 是否可加载
3. 标记为已完成

---

成功标准：

• ✅ 可通过已知 URL 访问测试内容
• ✅ 内容涵盖所有测试场景（变体、边缘情况）
• ✅ URL 已验证（返回 200）

完成条件： 测试内容已找到或创建并通过验证

---

第 5 步：实现

调用： building-blocks 技能

提供：

• 第 3 步的内容模型（如适用）
• 第 4 步的测试内容 URL
• 第 2 步的分析／需求
• 更改类型：新建区块、修改现有区块、仅 CSS 等

building-blocks 技能将：

• 根据更改类型指导实现方式
• 处理 JavaScript 装饰（如需要）
• 处理 CSS 样式（移动优先、响应式）
• 确保开发过程中在浏览器中进行迭代测试

成功标准：

• ✅ 代码实现完成
• ✅ 功能在所有视口（手机、平板、桌面）上正常运行
• ✅ 控制台无错误

满足以下条件时，将待办事项标记为完成： building-blocks 技能报告实现已完成，且功能在所有视口上正常运行

---

第 6 步：Lint 和测试

操作内容：

npm run lint

如果存在 lint 错误：

1. 修复问题（对于可自动修复的问题，使用 npm run lint:fix）
2. 重新运行 lint，直到没有错误

运行现有测试：

npm test

注意： 单元测试为可选项，仅逻辑密集型工具需要进行。testing-blocks 技能（由第 5 步中的 building-blocks 调用）负责浏览器测试。此步骤用于检查是否还存在 lint 错误，并运行项目的测试套件。

成功标准：

• ✅ npm run lint 通过且无错误
• ✅ npm test 通过（如果存在测试）

满足以下条件时，将待办事项标记为完成： 所有 lint 和测试检查均通过

---

第 7 步：最终验证

操作内容：

1. 检查第 2 步的验收标准

   • 阅读第 2 步创建的分析文档
   • 检查是否满足每项验收标准

2. 最后进行浏览器基本检查

   • 在浏览器中加载测试内容 URL
   • 检查手机、平板和桌面视口
   • 确认控制台无错误
   • 确认没有视觉回归

3. 确认没有回归

   • 如果修改现有区块：测试现有变体是否仍能正常工作
   • 如果修改核心功能：抽查几个页面

成功标准：

• ✅ 满足第 2 步的所有验收标准
• ✅ 在所有视口上正常运行
• ✅ 控制台无错误
• ✅ 现有功能无回归

满足以下条件时，将待办事项标记为完成： 已验证所有验收标准，且未发现回归

---

第 8 步：交付

要做的事：

1. 创建功能分支（如果当前还不在功能分支上）：

   git checkout -b block-name
   

2. 仅暂存指定文件：

   git add blocks/{block-name}/{block-name}.js blocks/{block-name}/{block-name}.css
   # Add only files you worked on - NEVER use `git add .`
   

3. 使用 Conventional Commits 格式提交：

   git commit -m "feat(block-name): add new block"
   

   在提交消息中包含相关详情，并在页脚注明 Agent 署名（Agent 会添加 Co-authored-by: cursor <[email protected]>）

4. 推送到功能分支：

   git push origin HEAD
   

5. 创建包含预览链接的 PR：

   • 分支预览 URL 格式：https://{branch}--{repo}--{owner}.aem.page/{path}
   • 示例：https://carousel--aem-skills-demo--shsteimer.aem.page/
   • **必需：**在 PR 描述中包含预览链接（自动化 PSI 检查会使用该链接）
   • 如有需要，添加多个预览链接（例如，不同变体、边缘情况）

   确定是否需要创建草稿 PR：

   在以下情况下创建草稿 PR：

   • ✅ 新功能/变体仅有本地测试内容
   • ✅ 测试内容展示了 CMS 中尚不存在的新功能
   • ✅ 最终验证前需要用户创建 CMS 内容

   在以下情况下创建普通 PR：

   • ✅ CMS 中已有所有测试内容，且可供预览
   • ✅ 更改只影响现有内容（可使用现有 CMS 内容测试回归问题）

   草稿 PR 工作流：

   1. 使用 gh pr create --draft 创建草稿 PR
   2. 添加现有内容的预览链接（如适用，可用于回归测试）
   3. 在 PR 描述中添加后续步骤（参见下方模板）：
      • 说明本地使用的测试内容及其覆盖的场景
      • 建议创建并预览相同或类似内容，然后将链接添加到 PR
      • 步骤应简短且便于任何审阅者执行
   4. 指示用户按照以下步骤创建 CMS 内容：
      • 在浏览器中打开本地测试内容：http://localhost:3000/drafts/tmp/[test-file]
      • 右键点击 AEM Sidekick 扩展
      • 点击“查看文档源”选项
      • 使用复制按钮复制文档内容
      • 粘贴到 Word/Google Docs/Document Authoring 中（对于 UE：将其作为指南，直接复制/粘贴无法使用）
      • 预览 CMS 内容
   5. 用户将预览 URL 添加到 PR 描述中，并将 PR 标记为可供审阅（也可由 Agent 根据用户意见操作）

PR 描述模板：

所有 PR 都使用此模板，并包含所有相关预览链接；可根据需要调整：

## Description
Brief description of changes

[If an issue exists]
Fix #<gh-issue-id>

Test URLs:

[Repeat for all relevant test urls]
- Before: https://main--{repo}--{owner}.aem.page/{path}
- After: https://{branch}--{repo}--{owner}.aem.page/{path} 

[If only local test content (draft PR):]

This PR is currently a **draft** pending creation of CMS test content.

### Next Steps to Complete PR:

[add relevant steps here]

成功标准：

• ✅ 已按正确格式提交更改并注明署名
• ✅ 已推送到功能分支（而非 main）
• ✅ 已创建 PR，且描述中包含预览链接

**以下情况可将待办事项标记为完成：**PR 已创建并可供审阅

---

相关技能

• analyze-and-plan：在第 2 步调用，用于需求分析和验收标准
• content-modeling：在第 3 步调用，用于设计内容模型
• da-auth：在将内容推送到 DA 或以编程方式触发 DA 预览之前，获取有效的 Adobe IMS 令牌；使用 DA 时，在第 4 步开始时调用
• find-test-content：在第 4 步的选项 C 中调用，用于查找现有内容
• building-blocks：在第 5 步调用，用于实现
• testing-blocks：由 building-blocks 调用，用于浏览器测试
• block-collection-and-party：用于查找相似区块和参考实现

应避免的反模式

违反 CDD 原则的常见错误：

• ❌ 未理解内容模型就开始编写代码
• ❌ 未查看真实示例就假设内容结构
• ❌ 创建对开发者友好、但对作者不友好的内容模型
• ❌ 为了“节省时间”而跳过内容创建（之后反而会花更多时间）

资源

• 理念：references/cdd-philosophy.md - 内容优先为何重要
• HTML 结构：references/html-structure.md - 创建本地 HTML 测试文件的指南