深度初始化技能Skill deepinit

---

名称: deepinit 描述: 深度代码库初始化与分层AGENTS.md文档

深度初始化技能

创建全面的、分层AGENTS.md文档覆盖整个代码库。

核心概念

AGENTS.md文件作为AI可读文档，帮助代理理解：

• 每个目录包含什么
• 组件如何相互关联
• 在该区域工作的特殊指令
• 依赖和关系

分层标签系统

每个AGENTS.md（除了根目录）包括一个父引用标签：

<!-- 父级: ../AGENTS.md -->

这创建了一个可导航的层次结构：

/AGENTS.md                          ← 根（无父标签）
├── src/AGENTS.md                   ← <!-- 父级: ../AGENTS.md -->
│   ├── src/components/AGENTS.md    ← <!-- 父级: ../AGENTS.md -->
│   └── src/utils/AGENTS.md         ← <!-- 父级: ../AGENTS.md -->
└── docs/AGENTS.md                  ← <!-- 父级: ../AGENTS.md -->

AGENTS.md模板

<!-- 父级: {relative_path_to_parent}/AGENTS.md -->
<!-- 生成: {timestamp} | 更新: {timestamp} -->

# {目录名称}

## 目的
{一段描述此目录包含内容和其角色的段落}

## 关键文件
{列出每个重要文件及其一行描述}

| 文件 | 描述 |
|------|-------------|
| `file.ts` | 用途简要描述 |

## 子目录
{列出每个子目录及其简要目的}

| 目录 | 目的 |
|-----------|---------|
| `subdir/` | 包含内容（见 `subdir/AGENTS.md`） |

## 对于AI代理

### 在此目录工作
{修改此处文件的AI代理特殊指令}

### 测试要求
{如何测试此目录中的更改}

### 常见模式
{此处使用的代码模式或约定}

## 依赖

### 内部
{对此代码库其他部分的引用依赖}

### 外部
{使用的外部关键包/库}

<!-- 手动: 任何手动添加的注释在此行下保留于重新生成时 -->

执行工作流

步骤1: 映射目录结构

任务(子代理类型="探索", 模型="haiku",
  提示="递归列出所有目录。排除: node_modules, .git, dist, build, __pycache__, .venv, coverage, .next, .nuxt")

步骤2: 创建工作计划

为每个目录生成待办事项，按深度级别组织：

级别0: / (根)
级别1: /src, /docs, /tests
级别2: /src/components, /src/utils, /docs/api
...

步骤3: 逐级生成

重要: 生成父级别前于子级别，以确保父引用有效。

对于每个目录：

1. 读取目录中所有文件
2. 分析目的和关系
3. 生成AGENTS.md内容
4. 写入文件并确保正确父引用

步骤4: 比较和更新（如果存在）

当AGENTS.md已存在时：

1. 读取现有内容
2. 识别部分:
   • 自动生成部分（可更新）
   • 手动部分（<!-- 手动 --> 保留）
3. 比较:
   • 添加了新文件？
   • 删除了文件？
   • 结构更改？
4. 合并:
   • 更新自动生成内容
   • 保留手动注释
   • 更新时间戳

步骤5: 验证层次结构

生成后，运行验证检查：

检查	如何验证	纠正措施
父引用解析	读取每个AGENTS.md，检查 <!-- 父级: --> 路径存在	修复路径或移除孤立
无孤立AGENTS.md	比较AGENTS.md位置与目录结构	删除孤立文件
完整性	列出所有目录，检查AGENTS.md	生成缺失文件
时间戳最新	检查 <!-- 生成: --> 日期	重新生成过时文件

验证脚本模式：

# 查找所有AGENTS.md文件
find . -name "AGENTS.md" -type f

# 检查父引用
grep -r "<!-- 父级:" --include="AGENTS.md" .

智能委派

任务	代理
目录映射	探索
文件分析	architect-low
内容生成	writer
AGENTS.md写入	writer

空目录处理

遇到空或近空目录时：

条件	操作
无文件，无子目录	跳过 - 不创建AGENTS.md
无文件，有子目录	创建仅包含子目录列表的最小AGENTS.md
仅生成文件 (*.min.js, *.map)	跳过或最小AGENTS.md
仅配置文件	创建描述配置目的的AGENTS.md

仅包含目录的容器最小AGENTS.md示例：

<!-- 父级: ../AGENTS.md -->
# {目录名称}

## 目的
组织相关模块的容器目录。

## 子目录
| 目录 | 目的 |
|-----------|---------|
| `subdir/` | 描述（见 `subdir/AGENTS.md`） |

并行化规则

1. 同级目录: 并行处理
2. 不同级别: 顺序（父先）
3. 大目录: 每个目录分配专用代理
4. 小目录: 批处理多个到一个代理

质量标准

必须包括

• [ ] 准确文件描述
• [ ] 正确父引用
• [ ] 子目录链接
• [ ] AI代理指令

必须避免

• [ ] 通用模板
• [ ] 不正确文件名
• [ ] 破损父引用
• [ ] 遗漏重要文件

示例输出

根AGENTS.md

<!-- 生成: 2024-01-15 | 更新: 2024-01-15 -->

# 我的项目

## 目的
一个用于管理用户任务并具有实时协作功能的Web应用程序。

## 关键文件
| 文件 | 描述 |
|------|-------------|
| `package.json` | 项目依赖和脚本 |
| `tsconfig.json` | TypeScript配置 |
| `.env.example` | 环境变量模板 |

## 子目录
| 目录 | 目的 |
|-----------|---------|
| `src/` | 应用程序源代码（见 `src/AGENTS.md`） |
| `docs/` | 文档（见 `docs/AGENTS.md`） |
| `tests/` | 测试套件（见 `tests/AGENTS.md`） |

## 对于AI代理

### 在此目录工作
- 修改项目清单后始终安装依赖
- 使用TypeScript严格模式
- 遵循ESLint规则

### 测试要求
- 提交前运行测试
- 确保 >80% 覆盖率

### 常见模式
- 使用桶导出 (index.ts)
- 偏好功能组件

## 依赖

### 外部
- React 18.x - UI框架
- TypeScript 5.x - 类型安全
- Vite - 构建工具

<!-- 手动: 自定义项目注释可添加下方 -->

嵌套AGENTS.md

<!-- 父级: ../AGENTS.md -->
<!-- 生成: 2024-01-15 | 更新: 2024-01-15 -->

# 组件

## 目的
按功能和复杂性组织的可重用React组件。

## 关键文件
| 文件 | 描述 |
|------|-------------|
| `index.ts` | 所有组件的桶导出 |
| `Button.tsx` | 主要按钮组件 |
| `Modal.tsx` | 模态对话框组件 |

## 子目录
| 目录 | 目的 |
|-----------|---------|
| `forms/` | 表单相关组件（见 `forms/AGENTS.md`） |
| `layout/` | 布局组件（见 `layout/AGENTS.md`） |

## 对于AI代理

### 在此目录工作
- 每个组件有自己的文件
- 使用CSS模块进行样式
- 通过index.ts导出

### 测试要求
- `__tests__/` 子目录中的单元测试
- 使用React测试库

### 常见模式
- Props接口定义在组件上方
- 使用forwardRef用于暴露DOM的组件

## 依赖

### 内部
- `src/hooks/` - 组件使用的自定义钩子
- `src/utils/` - 实用函数

### 外部
- `clsx` - 条件类名
- `lucide-react` - 图标

<!-- 手动: -->

触发更新模式

在已有AGENTS.md文件的现有代码库上运行时：

1. 首先检测现有文件
2. 读取和解析现有内容
3. 分析当前目录状态
4. 生成现有和当前之间的差异
5. 应用更新同时保留手动部分

性能考虑

• 缓存目录列表 - 不重新扫描相同目录
• 批处理小目录 - 一次处理多个
• 跳过未更改 - 如果目录未更改，跳过重新生成
• 并行写入 - 多个代理同时写入不同文件