v2.0.1 to v2.0.2

---

name: domain-init

description: >-

对项目进行全盘扫描，识别领域类型和技术栈，通过多 subAgent 并行扫描多维度，

生成项目知识 docs 与专属 rules、skills 和 agents。使用「自动 baseline + 交互式增强」

的分层模式，结合头脑风暴先扩散后收拢。

触发词：domain-init、领域初始化、生成领域规范、领域扫描

metadata:

author: "devkeel"

---

# Domain Init — 项目领域能力生成器

扫描当前项目 → 识别领域与归属 → 分类维护 docs + rules + skills + agents。

**与 devkeel init 的关系：**

- `devkeel init` 建立执行入口与 `.harness/`，分发通用工作流资产

- `domain-init` 生成「项目专属领域能力」— 基于当前项目代码扫描后定制

**产出位置：** 当前项目 `docs/`、`.harness/rules/`、`.harness/skills/`、`.harness/agents/`；

`AGENTS.md` 维护入口和读取条件。资产分层遵循当前项目执行契约。

## Read First

按需加载以下参考文档：

- `references/detection-signals.md` — 领域检测信号表、降级策略、可用标签

- `references/dimension-pool.md` — 增强维度池（Rules / Skills / Agents）

- `references/project-index.md` — 参考项目索引（GitHub 地址 + 参考内容）

- `references/output-formats.md` — 产出格式规范 + 质量标准

- `references/domain-matrix.md` — 领域适用性矩阵（8 大领域 × 23 维度）

## 何时使用

- 项目已完成 `devkeel init`，需要定制领域能力

- 接手新项目，需要快速建立领域规范

- 项目技术栈升级/迁移，需要更新领域规范

何时**不**使用：

- 新项目应先 `devkeel init`

根项目、普通子项目和 git submodule 均可执行。根项目扫描自身及跨项目关系；子项目扫描自身

领域。先确认目标目录与配置归属，不因存在子模块终止，也不递归改写未获授权的子项目。

## Hard Rules

1. **必须先完成领域检测**（Phase 1），禁止跳过直接生成

2. **Baseline 基于实际扫描** — 采样真实代码，不凭假设生成通用模板话术

3. **覆盖增强策略** — 已存在的同主题 docs/rule/skill/agent 合并项目特征，不丢失已有内容

4. **用户 review 门禁** — 所有生成内容必须经用户 review 后才写入文件系统

5. **参考项目标杆** — 每个维度的 subAgent 在生成前，先用当前可用的页面读取能力获取对应开源参考项目（见 `references/project-index.md`）

6. **领域适用性过滤** — 不同领域生成不同维度组合（见 `references/domain-matrix.md`），不输出领域无关的内容

7. **格式严格遵循** — docs/rules/skills/agents 各自遵循产出格式（见 `references/output-formats.md`）

8. **代码依据** — 事实须有代码、配置或已确认约定支持；扫描发现的惯例不自动升级为硬约束

9. **知识与约束分开** — rules 保留简短执行约束；背景、原理、结构说明和详细示例写入 docs。

按主题复用已有文档，不为每个扫描维度机械创建文件，也不按使用频率移除硬约束

10. **测试资产共用** — R4 与 verify-init 维护同一套测试规则和文档；先定位已有文件，再增量更新。

已有 `testing-strategy.md` 等入口继续复用，不并列新建重复的 `testing.md`

## 流程总览

```

Phase 1: 领域识别 → 检测 + 用户确认

Phase 2: Baseline 生成 → 用户选择维度 → 多 subAgent 并行扫描 → 用户 review → 写入

Phase 3: 交互式增强 → 头脑风暴扩散 → 用户选择+优先级 → 并行生成 → review → 写入

Phase 4: 收尾 → 配置更新 + 链接检查 + 生成报告

```

---

## Phase 1: 领域识别

### 1.1 自动检测

先读取目标作用域的 `AGENTS.md`、相关 rules 和文档入口，定位现有 `docs/` 与配置事实源。

读取 `references/detection-signals.md`，按信号表扫描目标目录，推断领域和技术栈。

根项目识别共享配置与跨项目关系；各子项目按自己的 manifest、代码和已有文档识别，不用主包

技术栈代替所有子项目。OpenSpec 任务和当前规范继续位于主仓库。

检测按优先级从高到低匹配，命中第一个即停止。覆盖：前端、后端、移动端、系统/底层、工具/库/平台、Monorepo。

如果所有信号都未命中，执行降级流程（文件后缀分布 → 入口特征 → README 描述 → 综合推断 → 用户确认）。

### 1.2 用户确认与补充

展示检测结果，用户确认或纠正。同时收集：

- **领域确认** — 检测结果是否准确？用户可手动指定领域标签

- 团队编码风格偏好（严格/宽松）

- 特殊架构约束（微服务/Monorepo/Monolith）

- 关键业务领域（金融/医疗/电商/教育等 — 影响安全和合规维度权重）

- 已有的团队规范文档（可导入为初始输入）

---

## Phase 2: Baseline 自动生成

### 2.1 Baseline 维度候选

| ID | 维度 | 候选产出 | subAgent 职责 |

|----|------|------|--------------|

| R1 | 编码规范 | rule / docs | 扫描代码风格、格式化配置、lint 规则、导入习惯 |

| R4 | 测试策略 | rule / docs | 扫描测试框架、覆盖模式、测试文件组织、mock 策略 |

| R5 | 错误处理 | rule / docs | 扫描异常模式、日志使用、错误边界、重试策略 |

| R6 | 命名规范 | rule / docs | 扫描文件名、变量名、组件名、常量命名模式 |

| R14 | 依赖管理 | rule / docs | 扫描依赖策略、锁文件、版本范围、准入标准 |

| R16 | 编码哲学 | rule / docs | 提炼团队的 anti-pattern、YAGNI、代码密度惯例 |

| R17 | Git 工作流 | rule / docs | 扫描分支策略、commit 消息格式、PR/MR 流程 |

| R20 | 编辑纪律 | rule / docs | 基于 surgical changes 原则：只改相关代码 |

| A1 | 领域 Code Reviewer | agent | 基于以上扫描结果生成专属审查维度和输出规则 |

### 2.2 用户选择与优先级确认

**在扫描前，必须先让用户确认 baseline 范围和优先级。**

展示 baseline 候选列表，用户可以：

1. **勾选/取消** — 选择需要生成的维度，取消不需要的

2. **调整优先级** — 标记为 `高优先` / `正常` / `低优先`

3. **补充上下文** — 对特定维度补充说明（如「测试策略重点关注集成测试」）

优先级影响：

- **高优先** — 深入采样关键路径、边界和例外

- **正常** — 覆盖代表性模块及其配置

- **低优先** — 仅核对核心事实与约束

优先级决定调查深度，不规定约定数量、篇幅或示例配额。

用户确认后才进入扫描阶段。

### 2.3 subAgent 扫描方法

每个 subAgent 按以下步骤工作：

1. **Fetch 参考标杆** — 按 `references/project-index.md` 读取对应开源项目的关键文件

2. **采样代码** — 从项目中选取代表性文件（数量由优先级决定）

3. **提取模式** — 识别实际代码中的约定（不是理论最佳实践）

4. **标记不一致** — 将冲突和建议提交 review，不把建议写成已生效约束

5. **对比已有产物** — 按主题定位 `docs/`、rules、skills、agents，复用已有文件与事实源

6. **分类生成** — 执行约束进入 rules；背景与示例进入 docs；可复用流程进入 skills；

角色职责进入 agents。按 `references/output-formats.md` 生成，并列出目标文件、依据和引用

### 2.4 Baseline Review

汇总扫描结果，用户逐条 review：

- **确认** — 直接写入

- **修改** — 调整约定内容后写入

- **跳过** — 本次不生成，可在后续重新运行时生成

全部 review 完成后，按确认范围写入 `docs/` 与 `.harness/`，再更新 AGENTS 文档入口。

---

## Phase 3: 交互式增强（头脑风暴）

### 3.1 维度池展示

读取 `references/dimension-pool.md` 和 `references/domain-matrix.md`，基于 Phase 1 识别的领域

过滤不适用维度，再按 Rules / Skills / Agents 三类展示可选增强项。

### 3.2 头脑风暴：扩散

1. 向用户展示过滤后的维度池

2. 用户选择感兴趣的方向

3. 对选中维度做简短讨论：「项目里这个维度的痛点是什么？」

4. 用户可补充自定义维度（不在池中的）

5. 发散阶段不限制数量

### 3.3 收拢：用户选择与优先级确认

**在生成前，必须让用户明确选择要生成的增强项并设定优先级。**

整理发散阶段讨论的所有候选项，向用户展示选择面板（按 Rules / Skills / Agents / 自定义分组），用户可以：

- 勾选/取消任何维度

- 调整优先级（高/正常/低）

- 对特定维度补充范围说明（如「安全规范重点关注 XSS」）

确认规则：

- 必须用户明确确认后才启动生成

- 如果用户取消了所有增强项，跳过 Phase 3.4 直接进入 Phase 4

### 3.4 增强项生成

- 按确认列表并行 subAgent 生成

- 每个 subAgent 先 fetch 参考项目 → 再扫描代码 → 最后生成

- 每项生成后展示给用户 review

- 确认后按内容归属写入 `docs/` 与 `.harness/`

---

## Phase 4: 收尾

### 4.1 更新配置

- 确认 manifest 一致性

### 4.2 平台链接检查

确认以下 symlink 正常（如适用）：

- `.claude/rules` → `.harness/rules`

- `.claude/agents` → `.harness/agents`

- `.cursor/rules` → `.harness/rules`

### 4.3 子模块 Skills 同步（含 git submodule 的项目）

**为什么需要同步？**

Claude Code / Cursor 等 Coding Agent 启动时，只扫描主仓库的 `.claude/skills/`（通过 symlink

指向 `.harness/skills/`）。子模块的 `.harness/skills/` 不在扫描范围内，生成的 skills 不会自动加载。

同步的作用是将子模块的 skills 通过 symlink 平铺到主仓库的 `.harness/skills/`，形成完整的加载链路：

```

子模块/.harness/skills/xxx/

↓ symlink (sync-submodule-skills.mjs)

主仓库/.harness/skills/xxx/

↓ symlink (devkeel init 创建)

主仓库/.claude/skills/xxx/

↓ 启动时自动扫描

Claude Code / Coding Agent 运行环境

```

只有完成这条链路，Agent 才能在运行时自动发现和使用子模块中的 skills。

**使用方式：**

```bash

node .harness/skills/domain-init/scripts/sync-submodule-skills.mjs --dry-run # 预览

node .harness/skills/domain-init/scripts/sync-submodule-skills.mjs # 执行

node .harness/skills/domain-init/scripts/sync-submodule-skills.mjs --prune # 执行 + 清理失效链接

```

脚本自动发现所有 git submodule，无需手动配置子模块路径。

**何时使用：**

- 在子模块中运行了 domain-init 生成 skills 后

- 子模块新增/删除了 skills 后

**何时不使用：**

- 单体项目（无 submodule）

- 子模块没有 `.harness/skills/`

### 4.4 生成报告

输出本次生成的完整清单（类型、文件、状态、参考项目），标记新增 vs 增强，建议后续完善方向，提醒用户 review 后 commit。

### 4.5 更新文档与 AGENTS 入口

根项目和子项目执行同一流程：

1. 按主题增量维护已存在的项目文档；没有对应文档时再创建 `docs/` 下的必要文件。

2. 将项目背景、技术栈、模块职责、开发说明写入 docs；测试知识与 verify-init 共用已有测试文档，

缺失时使用 `docs/testing.md`。命令、门槛和参数引用实际配置或 scripts，不维护第二份值。

3. 更新 AGENTS 的文档链接与读取条件，规则和能力通过最小触发矩阵发现；不要求全量读取 docs。

4. 填充完成后删除该槽位成对的 `<!-- harness:user:... -->` / `<!-- /harness:user:... -->`

边界注释与已用完的占位提示，保留正文及相邻框架内容。未填槽位保留占位；已有正文不重加标记。

5. 核对相对链接、规则触发范围和事实来源。后续实施改变已验证的项目事实时，同步相关文档。

| 用户槽位 | 内容 |

|----------|------|

| `harness:user:routing` | 任务信号到适用 rules、skills、agents 的路由 |

| `harness:user:verification` | 开发与测试文档的链接及读取条件 |

| `harness:user:project` | 项目概览、架构、业务边界及其他文档的链接与读取条件 |

例如，只有对应文件已存在时，才在项目知识入口添加正文：

```markdown

- 判断业务归属时读取 [项目概览](docs/project.md)。

- 调整模块依赖时读取 [架构说明](docs/architecture.md)。

```

写入复用 Phase 2/3 已确认的范围；新内容与迁移差异统一展示 review。已有用户内容按差异合并，

不覆盖未知内容。项目知识入口统一使用 `project`；旧 `domain` 内容合并到 `project` 后移除旧

槽位，不重新创建。标记已清理时按对应章节更新正文，不重复追加入口；必要入口缺失时只展示

最小新增差异，保留执行契约。

迁移已有正文时，先写入目标 docs 或 rules 并核对语义与链接，再将原正文替换为引用；执行约束、

权限及失败恢复条件必须保留在可发现的执行入口。任务草案不转写为当前项目事实。

---

## 通用能力沉淀

在 Phase 3 交互中，如果发现某个生成的 rule/skill/agent 具有跨项目通用性：

- 标记为「候选通用能力」

- 建议用户后续向 devkeel 提交通用模板提案

- **不自动操作**，只做建议