ensure-agents-md

确保存在 AGENTS.md 和 CLAUDE.md（引导初始化）

强制顺序（所有情况）

在进行任何其他工作之前——包括 dispatcher、create-component、代码编辑、MCP 或回答问题——Agent 必须：

1. 检查工作区（仓库）根目录是否存在 AGENTS.md。
2. 如果存在 → 完全跳过此技能，继续处理用户请求。
3. 如果不存在，且仓库是 AEM Cloud Service 项目（参见准入检查）→ 先完整运行此技能（如果缺少 AGENTS.md 和 CLAUDE.md，则创建它们），然后处理用户的原始请求。

这适用于每一条用户消息和任何意图（错误、功能、问题、dispatcher 等），直至 AGENTS.md 存在。不要把引导初始化推迟到主要任务“之后”。

此技能会在仓库根目录创建 AGENTS.md 和 CLAUDE.md，让每个 AI 编码 Agent（Claude Code、Cursor 等）都能获取项目指导；还可根据模块目录和附加组件检测结果进行定制。

准入检查

1. 在工作区根目录查找 AGENTS.md。如果存在 → 跳过并继续。
2. 验证这是 AEM Cloud Service 项目：根目录存在 pom.xml，且引用了 com.adobe.aem:aem-sdk-api 或 aem-project-archetype，或者包含 <modules>，其中有 常见的 AEM 模块名称（core、ui.apps、dispatcher 等）。 如果不是 AEM 项目 → 跳过。

步骤

1. 确定项目名称

按以下顺序检查：

• 根目录 pom.xml → <name> 元素（优先，通常更易读）。
• 根目录 pom.xml → <artifactId>，然后转换为易读形式：去掉开头的 aem-，将 - 替换为空格， 并将各单词首字母大写（例如 aem-guides-wknd → WKND，my-site → My Site）。
• 工作区目录名称。
• 兜底名称："AEM Cloud Service Project"。

2. 发现模块

读取根目录 pom.xml 的 <modules> 部分。对于每个 <module>，确认对应目录确实存在。 列出所有存在的模块。

3. 检测附加组件和前端类型

扫描项目，查找以下信号：

信号	附加组件 / 变体
pom.xml 依赖 cif-connector 或 aem-core-cif-components	CIF（Commerce）
ui.frontend/package.json 包含 react 或 @adobe/aem-react-editable-components	React SPA
ui.frontend/package.json 包含 @angular/core 或 @adobe/aem-angular-editable-components	Angular SPA
ui.frontend 没有 clientlib.config.js，且 pom.xml 引用了 frontend-maven-plugin，但不生成 clientlibs	解耦前端
pom.xml 依赖 aem-forms-* 或 forms.core	AEM Forms
存在模块 ui.frontend.react.forms.af	Headless Forms
pom.xml 使用 precompiled-scripts-provider	预编译脚本

如果未检测到上述任何项，则视为 General Webpack 前端（默认 archetype）。

4. 生成 AGENTS.md

读取模板 references/AGENTS.md.template。 应用以下调整：

a. 标题

将 {{PROJECT_NAME}} 替换为已确定的项目名称。

b. 附加组件部分

如果检测到任何附加组件（CIF、Forms、Headless Forms、Precompiled Scripts），则在简介段落后插入 **“附加组件和扩展”**部分。使用 references/module-catalog.md 中附加组件表格的描述。如果未检测到任何附加组件，则完全省略此部分。

c. 模块部分

仅包含项目中实际存在的模块。每个模块使用 模块目录中对应的描述。请注意：

• ui.frontend — 使用与检测到的前端类型匹配的变体（General、React、Angular、Decoupled）。
• dispatcher — 仅在 dispatcher 目录存在时包含。
• it.tests / ui.tests — 仅在这些目录存在时包含。

d. 构建命令

• 仅当存在 ui.frontend 时，才包含前端命令（npm run build、npm start）。
• 仅当存在 dispatcher 模块时，才包含 dispatcher 验证命令。
• 对于 React/Angular SPA，请注明运行 npm start 需要 AEM 正在运行。

e. 重要资源

始终包含模板中的基础资源。此外：

• 如果检测到 React 或 Angular SPA → 添加 SPA Editor 和特定框架的资源（参见模块目录）。
• 如果检测到 CIF → 添加 Commerce 资源。
• 如果检测到 Forms → 添加 Forms 资源。
• 如果是解耦前端 → 添加 Frontend Pipeline 资源。

5. 创建 CLAUDE.md

如果工作区根目录中不存在 CLAUDE.md，请使用以下确切内容创建该文件（以便 Claude/Cursor 获取项目指南）：

@AGENTS.md

不要覆盖现有的 CLAUDE.md。

6. 告知用户

简要告知用户：

"我已在项目根目录中创建 AGENTS.md 和 CLAUDE.md，其中包含针对项目结构定制的指南。这些文件有助于 AI 编码 Agent 了解你的项目。"

然后继续处理用户的原始请求。

参考文件

文件	用途
references/AGENTS.md.template	基础模板，包含 {{PROJECT_NAME}} 占位符和所有默认章节
references/module-catalog.md	模块说明、附加组件说明、条件资源——调整模板时的权威依据

规则

• 绝不覆盖现有的 AGENTS.md 或 CLAUDE.md。仅在文件缺失时创建。
• 绝不臆造模块。仅列出实际存在目录的模块。
• 保持生成的 AGENTS.md 简洁——不要添加技能元数据或“由技能生成”的注释。
• 项目名称应便于阅读（例如“WKND Sites Project”“My Site”），而不应只是原始 artifactId，除非这就是期望的标题。
• 不要添加要求 Agent 使用特定 MCP 服务、Cursor/Claude 技能或如何发现工具的章节。编码助手会从产品配置和工具元数据中获取这些信息；如果无法发现某项内容，应修复元数据或 MCP 设置，而不是在 AGENTS.md 中重复说明。
• 资源链接必须指向 experienceleague.adobe.com/en/docs/experience-manager-cloud-service/...（Cloud Service URL），绝不能指向 AEM 6.5 URL。