content-driven-development

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Content Driven Development (CDD)

内容驱动开发（CDD）

You are an orchestrator of the Content Driven Development workflow for AEM Edge Delivery Services. This workflow ensures code is built against real content with author-friendly content models.

CRITICAL: Never start writing or modifying code without first identifying or creating the content you will use to test your changes.

你是AEM Edge Delivery Services内容驱动开发工作流的协调者。该工作流确保代码基于真实内容构建，并采用便于内容创作者使用的内容模型。

重要提示：在未确定或创建用于测试变更的内容之前，绝对不要开始编写或修改代码。

When to Use This Skill

何时使用该技能

Use CDD for ALL AEM development tasks:

✅ Creating new blocks
✅ Modifying existing blocks (structural or functional changes)
✅ Changes to core decoration functionality
✅ Bug fixes that require validation
✅ Any code that affects how authors create or structure content

Do NOT use for:

Documentation-only changes
Configuration changes that don't affect authoring
Research tasks that don't require making any code changes yet

所有AEM开发任务均需使用CDD：

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

请勿用于：

仅文档变更
不影响内容创作的配置变更
暂无需编写代码的研究任务

Philosophy

核心理念

Content Driven Development prioritizes creating or identifying test content before writing code. This ensures:

Code is built against real content
Author-friendly content models
Validation throughout development

Optional: Understanding CDD Principles

Read

resources/cdd-philosophy.md

if:

User asks "why" questions about content-first approach
You need to understand reasoning behind CDD decisions
You're unsure whether to prioritize author vs developer experience

Otherwise: Follow the workflow steps below

内容驱动开发优先考虑在编写代码之前创建或确定测试内容。这可确保：

代码基于真实内容构建
采用便于内容创作者使用的内容模型
开发全程进行验证

可选：理解CDD原则

若出现以下情况，请阅读

resources/cdd-philosophy.md

：

用户询问关于内容优先方法的“为什么”问题
你需要理解CDD决策背后的逻辑
你不确定应优先考虑创作者体验还是开发者体验

否则：遵循以下工作流步骤

Step 0: Create TodoList

步骤0：创建任务清单

FIRST STEP: Use the TodoWrite tool to create a todo list with the following 8 tasks:

Start dev server (if not running)
- Success: Dev server running, can access http://localhost:3000
Analyze & plan
- Success: Clear understanding documented + acceptance criteria defined
Design content model
- Success: Content structure documented and validated
Identify/create test content
- Success: Test content accessible covering all scenarios
Implement
- Success: Functionality works across all viewports
Lint & test
- Success: All checks pass
Final validation
- Success: All acceptance criteria met, everything works
Ship it
- Success: PR created with preview link for validation

Mark todo complete when: Todo list created with all 8 tasks

第一步： 使用TodoWrite工具创建包含以下8项任务的任务清单：

启动开发服务器（若未运行）
- 成功标志：开发服务器运行，可访问http://localhost:3000
分析与规划
- 成功标志：已记录清晰的需求理解，且定义了验收标准
设计内容模型
- 成功标志：内容结构已记录并验证
确定/创建测试内容
- 成功标志：可访问覆盖所有场景的测试内容
开发实现
- 成功标志：功能在所有视口下正常工作
代码检查与测试
- 成功标志：所有检查项通过
最终验证
- 成功标志：所有验收标准均满足，功能全部正常
提交上线
- 成功标志：创建包含预览链接的PR用于验证

标记任务完成的条件： 已创建包含全部8项任务的清单

Step 1: Start Dev Server

步骤1：启动开发服务器

Check if dev server is running:

bash

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

Expected:

(server running) or connection error (server not running)

If not running, start it:

bash

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

Notes:

Run in background if possible (dev server needs to stay running)
Requires AEM CLI installed globally:
```
npm install -g @adobe/aem-cli
```

Alternative:

npx -y @adobe/aem-cli up --no-open --forward-browser-logs

IMPORTANT: Check the command output for errors. Common issues:

Port 3000 already in use
AEM CLI not installed
Configuration errors

After starting, verify it's running:

bash

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

Expected:

Success criteria:

✅ Dev server running
✅ http://localhost:3000 returns 200
✅ No errors in server startup output

Mark todo complete when: Dev server confirmed running and accessible

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

bash

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

预期结果：

（服务器运行中）或连接错误（服务器未运行）

若未运行，启动服务器：

bash

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
配置错误

启动后，验证服务器是否运行：

bash

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

预期结果：

成功标准：

✅ 开发服务器运行中
✅ http://localhost:3000返回200状态码
✅ 服务器启动输出无错误

标记任务完成的条件： 确认开发服务器已运行且可访问

Step 2: Analyze & Plan

步骤2：分析与规划

Invoke: analyze-and-plan skill

Provide:

Task description from user
Screenshots, design files, or existing URLs to match design from (if available)

The analyze-and-plan skill will:

Guide you through task-specific analysis
Help define acceptance criteria
Optionally analyze visual designs/mockups if provided
Create documented analysis for reference

Success criteria:

✅ Requirements analyzed
✅ Acceptance criteria defined
✅ Analysis documented to file for later steps

Mark todo complete when: Analysis documented and acceptance criteria defined

调用： analyze-and-plan技能

提供信息：

用户的任务描述
截图、设计文件或现有URL（用于匹配设计，若有）

analyze-and-plan技能将：

引导你完成任务特定的分析
帮助定义验收标准
若提供视觉设计/原型，可选择进行分析
创建记录分析结果的文档供参考

成功标准：

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

标记任务完成的条件： 分析结果已记录且验收标准已定义

Step 3: Design Content Model

步骤3：设计内容模型

Skip if: CSS-only changes that don't affect content structure

Invoke: content-modeling skill

Provide:

Analysis from Step 2 (content requirements, author inputs)
Block name and purpose

The content-modeling skill will:

Design table structure (rows, columns, semantic formatting)
Validate against best practices (4 cells/row, semantic formatting)
Document content model for authors

Success criteria:

✅ Content model designed (table structure defined)
✅ Validated against best practices
✅ Content model documented

Mark todo complete when: Content model designed and documented

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

调用： content-modeling技能

提供信息：

步骤2的分析结果（内容需求、创作者输入）
模块名称与用途

content-modeling技能将：

设计表格结构（行、列、语义化格式）
对照最佳实践验证（每行4个单元格、语义化格式）
为内容创作者记录内容模型

成功标准：

✅ 已设计内容模型（定义表格结构）
✅ 已对照最佳实践验证
✅ 内容模型已记录

标记任务完成的条件： 内容模型已设计并记录

Step 4: Identify/Create Test Content

步骤4：确定/创建测试内容

Goal: End this step with accessible test content URL(s) covering all test scenarios

Choose the best ath based on your situation:

目标： 完成此步骤后，需获得可访问的测试内容URL，覆盖所有测试场景

根据你的情况选择最佳路径：

Option A: User Provided Test URL(s)

选项A：用户提供的测试URL

When to use: User already has content and provided URL(s)

What to do:

Validate URL loads:

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

Expected:
```
200
```
status
Document URL(s)
Mark complete

使用场景： 用户已有内容并提供了URL

操作步骤：

验证URL是否可加载：

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

预期结果：
```
200
```
状态码
记录URL
标记任务完成

Option B: New Block (No Existing Content)

选项B：新模块（无现有内容）

When to use: Building a brand new block that doesn't exist yet

What to do:

Skip search (nothing exists yet to find)
Create test content using one of these approaches:

Approach 1: CMS Content (Recommended)

Ask user to create content in their CMS (Google Drive/SharePoint/DA/Universal Editor)
Provide content model from Step 3 as reference
Wait for user to provide URL(s)

Validate:

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

Expected:
```
200
```
status

Approach 2: Local HTML (Temporary)

Create HTML file in
```
drafts/tmp/{block-name}.plain.html
```
Follow structure from Step 3 content model
Read
```
resources/html-structure.md
```
for local HTML file format guidance

Restart dev server:

aem up --html-folder drafts --no-open --forward-browser-logs

Validate:

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

Expected:
```
200
```
status
Note: User must create CMS content before PR (required for preview link)

使用场景： 开发全新的模块

操作步骤：

跳过搜索（尚无内容可查找）
使用以下方式之一创建测试内容：

方法1：CMS内容（推荐）

请求用户在其CMS（Google Drive/SharePoint/DA/Universal Editor）中创建内容
提供步骤3的内容模型作为参考
等待用户提供URL

验证：

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

预期结果：
```
200
```
状态码

方法2：本地HTML（临时）

在
```
drafts/tmp/{block-name}.plain.html
```
创建HTML文件
遵循步骤3的内容模型结构
阅读
```
resources/html-structure.md
```
获取本地HTML文件格式指南

重启开发服务器：

aem up --html-folder drafts --no-open --forward-browser-logs

验证：

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

预期结果：
```
200
```
状态码
注意： 用户必须在创建PR前在CMS中创建内容（生成预览链接必需）

Option C: Existing Block

选项C：现有模块

When to use: Modifying, fixing, or styling an existing block

What to do:

First: Search for existing content

Invoke find-test-content skill
Provide: block name, dev server URL (optional, defaults to localhost:3000)

What find-test-content will do:

Search for existing content pages containing the block
Automatically detect and report all variants found
Report: URLs with instance counts and variant info

Then: Assess search results

If sufficient content found:

Document URL(s)

Validate URLs load:

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

Expected:
```
200
```
status
Mark complete

If no content found OR insufficient coverage:

Create additional test content using approaches from Option B
Validate URLs load
Mark complete

Success criteria:

✅ Test content accessible at known URL(s)
✅ Content covers all test scenarios (variants, edge cases)
✅ URLs validated (return 200)

Mark todo complete when: Test content identified/created and validated

使用场景： 修改、修复或样式化现有模块

操作步骤：

第一步：搜索现有内容

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

find-test-content技能将：

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

第二步：评估搜索结果

若找到足够内容：

记录URL

验证URL是否可加载：

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

预期结果：
```
200
```
状态码
标记任务完成

若未找到内容或覆盖场景不足：

使用选项B的方法创建额外测试内容
验证URL是否可加载
标记任务完成

成功标准：

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

标记任务完成的条件： 已确定/创建测试内容并验证

Step 5: Implement

步骤5：开发实现

Invoke: building-blocks skill

Provide:

Content model from Step 3 (if applicable)
Test content URL(s) from Step 4
Analysis/requirements from Step 2
Type of changes: new block, existing block modification, CSS-only, etc.

The building-blocks skill will:

Guide implementation approach based on change type
Handle JavaScript decoration (if needed)
Handle CSS styling (mobile-first, responsive)
Ensure iterative testing in browser throughout development

Success criteria:

✅ Code implementation complete
✅ Functionality works across all viewports (mobile, tablet, desktop)
✅ No console errors

Mark todo complete when: building-blocks skill reports implementation complete and working across viewports

调用： building-blocks技能

提供信息：

步骤3的内容模型（若适用）
步骤4的测试内容URL
步骤2的分析/需求
变更类型：新模块、现有模块修改、仅CSS变更等

building-blocks技能将：

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

成功标准：

✅ 代码开发完成
✅ 功能在所有视口（移动端、平板、桌面端）下正常工作
✅ 控制台无错误

标记任务完成的条件： building-blocks技能报告开发完成且在所有视口下正常工作

Step 6: Lint & Test

步骤6：代码检查与测试

What to do:

bash

npm run lint

If lint errors:

Fix issues (use
```
npm run lint:fix
```
for auto-fixable problems)
Re-run lint until clean

Run existing tests:

bash

npm test

Note: Unit tests are optional and only needed for logic-heavy utilities. The testing-blocks skill (invoked by building-blocks in Step 5) handles browser testing. This step catches any remaining lint issues and runs the project's test suite.

Success criteria:

✅
```
npm run lint
```
passes with no errors
✅
```
npm test
```
passes (if tests exist)

Mark todo complete when: All lint and test checks pass

操作步骤：

bash

npm run lint

若存在代码检查错误：

修复问题（使用
```
npm run lint:fix
```
自动修复可修复问题）
重新运行代码检查，直到无错误

运行现有测试：

bash

npm test

注意： 单元测试为可选，仅适用于逻辑复杂的工具类代码。步骤5中building-blocks技能调用的testing-blocks技能负责浏览器测试。此步骤用于捕获剩余的代码检查问题并运行项目测试套件。

成功标准：

✅
```
npm run lint
```
无错误通过
✅
```
npm test
```
通过（若存在测试）

标记任务完成的条件： 所有代码检查和测试均通过

Step 7: Final Validation

步骤7：最终验证

What to do:

Review acceptance criteria from Step 2
- Read the analysis document created in Step 2
- Check each acceptance criterion is met
Final browser sanity check
- Load test content URL(s) in browser
- Check mobile, tablet, and desktop viewports
- Verify no console errors
- Confirm no visual regressions
Verify no regressions
- If modifying existing block: test existing variants still work
- If modifying core functionality: spot-check a few pages

Success criteria:

✅ All acceptance criteria from Step 2 met
✅ Works across all viewports
✅ No console errors
✅ No regressions on existing functionality

Mark todo complete when: All acceptance criteria verified and no regressions found

操作步骤：

回顾步骤2的验收标准
- 阅读步骤2创建的分析文档
- 检查每项验收标准是否满足
最终浏览器 sanity 检查
- 在浏览器中加载测试内容URL
- 检查移动端、平板和桌面端视口
- 确认控制台无错误
- 确认无视觉回归
验证无回归问题
- 若修改现有模块：测试现有变体是否仍正常工作
- 若修改核心功能：抽查部分页面

成功标准：

✅ 步骤2的所有验收标准均满足
✅ 在所有视口下正常工作
✅ 控制台无错误
✅ 现有功能无回归问题

标记任务完成的条件： 所有验收标准已验证且无回归问题

Step 8: Ship It

步骤8：提交上线

What to do:

Create feature branch (if not already on one):
bash
```
git checkout -b block-name
```

Stage specific files only:

bash

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

Commit with conventional commit format:
bash
```
git commit -m "feat(block-name): add new block"
```
Include revelevant details in commit message and agent attribution in footer (agent adds
```
Co-authored-by: cursor <noreply@cursor.com>
```
)
Push to feature branch:
bash
```
git push origin HEAD
```
Create PR with preview link:
- Branch preview URL format:
```
https://{branch}--{repo}--{owner}.aem.page/{path}
```
- Example:
```
https://carousel--aem-skills-demo--shsteimer.aem.page/
```
- REQUIRED: Include preview link in PR description (used for automated PSI checks)
- Add multiple preview links if needed (e.g., different variants, edge cases)
Determining if you need a draft PR:

Create a draft PR when:
- ✅ Only local test content exists for NEW functionality/variants
- ✅ Test content demonstrates new features not yet in CMS
- ✅ You need user to create CMS content before final validation
Create a regular PR when:
- ✅ All test content exists in CMS and is previewable
- ✅ Changes only affect existing content (regressions can be tested with existing CMS content)
Workflow for draft PRs:
1. Create the PR as a draft using
```
gh pr create --draft
```
2. Include existing content preview links (for regression testing if applicable)
3. Include next steps in PR description (see template below):
  - Describe the test content used locally and what scenarios it covered
  - Suggest that same/similar content be created and previewed, and links added to PR
  - Keep steps brief but actionable for any reviewer
4. Instruct the user to create CMS content following the steps:
  - Open local test content in browser:
```
http://localhost:3000/drafts/tmp/[test-file]
```
  - Right-click AEM Sidekick extension
  - Click "View document source" option
  - Use the copy button to copy the document content
  - Paste into Word/Google Docs/Document Authoring (for UE: use as guide, copy/paste won't work directly)
  - Preview the CMS content
5. User adds preview URL(s) to PR description and marks PR ready for review (or agent does with user's input)

PR Description Template:

Use this template for all PRs, including all relevant preview links and adapting as needed:

markdown

undefined

操作步骤：

创建功能分支（若尚未在分支上）：
bash
```
git checkout -b block-name
```

仅暂存特定文件：

bash

git add blocks/{block-name}/{block-name}.js blocks/{block-name}/{block-name}.css
# 仅添加你修改的文件——绝对不要使用`git add .`

使用规范提交格式提交：
bash
```
git commit -m "feat(block-name): add new block"
```
提交信息中包含相关细节，并在页脚添加代理署名（代理会自动添加
```
Co-authored-by: cursor <noreply@cursor.com>
```
）
推送到功能分支：
bash
```
git push origin HEAD
```
创建包含预览链接的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/文档创作工具（对于UE：仅作为参考，无法直接复制粘贴）
  - 预览CMS内容
5. 用户将预览URL添加到PR描述后，标记PR为可审阅状态（或代理根据用户输入完成）

PR描述模板：

所有PR均使用此模板，需包含所有相关预览链接并按需调整：

markdown

undefined

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.

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]


**Success criteria:**
- ✅ Changes committed with proper message format and attribution
- ✅ Pushed to feature branch (not main)
- ✅ PR created with preview link in description

**Mark todo complete when:** PR created and ready for review

---

[add relevant steps here]


**成功标准：**
- ✅ 变更已使用正确格式和署名提交
- ✅ 已推送到功能分支（而非主分支）
- ✅ 已创建PR且描述中包含预览链接

**标记任务完成的条件：** PR已创建且可进行审阅

---

Related Skills

Anti-Patterns to Avoid

需避免的反模式

Common mistakes that violate CDD principles:

❌ Starting with code before understanding the content model
❌ Making assumptions about content structure without seeing real examples
❌ Creating developer-friendly but author-hostile content models
❌ Skipping content creation "to save time" (costs more time later)

违反CDD原则的常见错误：

❌ 在未理解内容模型的情况下开始编写代码
❌ 在未查看真实示例的情况下假设内容结构
❌ 创建便于开发者但不便于内容创作者的内容模型
❌ 为“节省时间”跳过内容创建（后续会花费更多时间）

Resources

资源

Philosophy:
```
resources/cdd-philosophy.md
```
- Why content-first matters
HTML Structure:
```
resources/html-structure.md
```
- Guide for creating local HTML test files

核心理念：
```
resources/cdd-philosophy.md
```
——内容优先的重要性
HTML结构：
```
resources/html-structure.md
```
——创建本地HTML测试文件指南

content-driven-development

Original

Translation

Content Driven Development (CDD)

内容驱动开发（CDD）

When to Use This Skill

何时使用该技能

Philosophy

核心理念

Step 0: Create TodoList

步骤0：创建任务清单

Step 1: Start Dev Server

步骤1：启动开发服务器

Step 2: Analyze & Plan

步骤2：分析与规划

Step 3: Design Content Model

步骤3：设计内容模型

Step 4: Identify/Create Test Content

步骤4：确定/创建测试内容

Option A: User Provided Test URL(s)

选项A：用户提供的测试URL

Option B: New Block (No Existing Content)

选项B：新模块（无现有内容）

Option C: Existing Block

选项C：现有模块

Step 5: Implement

步骤5：开发实现

Step 6: Lint & Test

步骤6：代码检查与测试

Step 7: Final Validation

步骤7：最终验证

Step 8: Ship It

步骤8：提交上线

Description

Description

Next Steps to Complete PR:

Next Steps to Complete PR:

Related Skills

相关技能

Anti-Patterns to Avoid

需避免的反模式

Resources

资源