---
name: deepinit
description: 使用分层 AGENTS.md 文档进行深度代码库初始化
level: 4
---

# Deep Init Skill

在整个代码库中创建全面、分层的 `AGENTS.md` 文档。

## Core Concept

`AGENTS.md` 文件充当**供 AI 读取的文档**，帮助 agent 理解：
- 每个目录包含什么
- 各组件之间如何关联
- 在该区域工作时的特殊说明
- 依赖关系与关联

## Hierarchical Tagging System

每个 `AGENTS.md`（根目录除外）都包含一个父级引用标签：

```markdown
<!-- Parent: ../AGENTS.md -->
```

这会创建一个可导航的层级结构：
```
/AGENTS.md                          ← Root (no parent tag)
├── src/AGENTS.md                   ← <!-- Parent: ../AGENTS.md -->
│   ├── src/components/AGENTS.md    ← <!-- Parent: ../AGENTS.md -->
│   └── src/utils/AGENTS.md         ← <!-- Parent: ../AGENTS.md -->
└── docs/AGENTS.md                  ← <!-- Parent: ../AGENTS.md -->
```

## AGENTS.md Template

```markdown
<!-- Parent: {relative_path_to_parent}/AGENTS.md -->
<!-- Generated: {timestamp} | Updated: {timestamp} -->

# {Directory Name}

## Purpose
{关于此目录包含内容及其角色的一段说明}

## Key Files
{列出每个重要文件，并附上一行说明}

| File | Description |
|------|-------------|
| `file.ts` | 用途的简要说明 |

## Subdirectories
{列出每个子目录及其简要用途}

| Directory | Purpose |
|-----------|---------|
| `subdir/` | 它包含的内容（见 `subdir/AGENTS.md`） |

## For AI Agents

### Working In This Directory
{AI agent 在此修改文件时的特殊说明}

### Testing Requirements
{如何测试此目录中的变更}

### Common Patterns
{此处使用的代码模式或约定}

## Dependencies

### Internal
{引用代码库中其所依赖的其他部分}

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

<!-- MANUAL: Any manually added notes below this line are preserved on regeneration -->
```

## Execution Workflow

### Step 1: Map Directory Structure

```
Task(subagent_type="explore", model="haiku",
  prompt="List all directories recursively. Exclude: node_modules, .git, dist, build, __pycache__, .venv, coverage, .next, .nuxt")
```

### Step 2: Create Work Plan

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

```
Level 0: / (root)
Level 1: /src, /docs, /tests
Level 2: /src/components, /src/utils, /docs/api
...
```

### Step 3: Generate Level by Level

**IMPORTANT**：必须先生成父级层，再生成子级层，以确保父引用有效。

对于每个目录：
1. 读取该目录中的所有文件
2. 分析其用途和关联关系
3. 生成 `AGENTS.md` 内容
4. 写入文件并附上正确的父级引用

### Step 4: Compare and Update (if exists)

当 `AGENTS.md` 已存在时：

1. **读取现有内容**
2. **识别各部分**：
   - 自动生成部分（可更新）
   - 手动部分（保留 `<!-- MANUAL -->`）
3. **比较**：
   - 是否新增了文件？
   - 是否删除了文件？
   - 结构是否变化？
4. **合并**：
   - 更新自动生成内容
   - 保留手动注释
   - 更新时间戳

### Step 5: Validate Hierarchy

生成后，运行校验检查：

| Check | How to Verify | Corrective Action |
|-------|--------------|-------------------|
| Parent references resolve | 读取每个 `AGENTS.md`，检查 `<!-- Parent: -->` 路径是否存在 | 修复路径或移除孤立项 |
| No orphaned AGENTS.md | 将 `AGENTS.md` 位置与目录结构进行比对 | 删除孤立文件 |
| Completeness | 列出所有目录，检查是否存在 `AGENTS.md` | 生成缺失文件 |
| Timestamps current | 检查 `<!-- Generated: -->` 日期 | 重新生成过期文件 |

Validation script pattern:
```bash
# Find all AGENTS.md files
find . -name "AGENTS.md" -type f

# Check parent references
grep -r "<!-- Parent:" --include="AGENTS.md" .
```

## Smart Delegation

| Task | Agent |
|------|-------|
| Directory mapping | `explore` |
| File analysis | `architect` |
| Content generation | `writer` |
| AGENTS.md writes | `writer` |

## Empty Directory Handling

遇到空目录或几乎为空的目录时：

| Condition | Action |
|-----------|--------|
| No files, no subdirectories | **跳过** - 不创建 `AGENTS.md` |
| No files, has subdirectories | 创建最小化 `AGENTS.md`，仅列出子目录 |
| Has only generated files (*.min.js, *.map) | 跳过或创建最小化 `AGENTS.md` |
| Has only config files | 创建说明配置用途的 `AGENTS.md` |

仅作为目录容器时的最小化 `AGENTS.md` 示例：
```markdown
<!-- Parent: ../AGENTS.md -->
# {Directory Name}

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

## Subdirectories
| Directory | Purpose |
|-----------|---------|
| `subdir/` | 说明（见 `subdir/AGENTS.md`） |
```

## Parallelization Rules

1. **Same-level directories**：并行处理
2. **Different levels**：串行处理（父级优先）
3. **Large directories**：为每个目录启动专用 agent
4. **Small directories**：将多个目录批量交给一个 agent

## Quality Standards

### Must Include
- [ ] 准确的文件说明
- [ ] 正确的父级引用
- [ ] 子目录链接
- [ ] 面向 AI agent 的说明

### Must Avoid
- [ ] 通用样板内容
- [ ] 错误的文件名
- [ ] 失效的父级引用
- [ ] 遗漏重要文件

## Example Output

### Root AGENTS.md
```markdown
<!-- Generated: 2024-01-15 | Updated: 2024-01-15 -->

# my-project

## Purpose
一个用于管理用户任务并支持实时协作功能的 Web 应用。

## Key Files
| File | Description |
|------|-------------|
| `package.json` | 项目依赖与脚本 |
| `tsconfig.json` | TypeScript 配置 |
| `.env.example` | 环境变量模板 |

## Subdirectories
| Directory | Purpose |
|-----------|---------|
| `src/` | 应用源码（见 `src/AGENTS.md`） |
| `docs/` | 文档（见 `docs/AGENTS.md`） |
| `tests/` | 测试套件（见 `tests/AGENTS.md`） |

## For AI Agents

### Working In This Directory
- 修改项目清单后始终安装依赖
- 使用 TypeScript strict mode
- 遵循 ESLint 规则

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

### Common Patterns
- 使用 barrel exports (`index.ts`)
- 优先使用函数式组件

## Dependencies

### External
- React 18.x - UI framework
- TypeScript 5.x - Type safety
- Vite - Build tool

<!-- MANUAL: Custom project notes can be added below -->
```

### Nested AGENTS.md
```markdown
<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2024-01-15 | Updated: 2024-01-15 -->

# components

## Purpose
按功能和复杂度组织的可复用 React 组件。

## Key Files
| File | Description |
|------|-------------|
| `index.ts` | 所有组件的 barrel export |
| `Button.tsx` | 主按钮组件 |
| `Modal.tsx` | 模态对话框组件 |

## Subdirectories
| Directory | Purpose |
|-----------|---------|
| `forms/` | 与表单相关的组件（见 `forms/AGENTS.md`） |
| `layout/` | 布局组件（见 `layout/AGENTS.md`） |

## For AI Agents

### Working In This Directory
- 每个组件都有自己的文件
- 使用 CSS modules 进行样式编写
- 通过 `index.ts` 导出

### Testing Requirements
- 单元测试位于 `__tests__/` 子目录
- 使用 React Testing Library

### Common Patterns
- Props interface 定义在组件上方
- 对暴露 DOM 的组件使用 `forwardRef`

## Dependencies

### Internal
- `src/hooks/` - 组件使用的自定义 hooks
- `src/utils/` - 工具函数

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

<!-- MANUAL: -->
```

## Triggering Update Mode

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

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

## Performance Considerations

- **Cache directory listings** - 不要重复扫描相同目录
- **Batch small directories** - 一次处理多个目录
- **Skip unchanged** - 如果目录未变化，则跳过重新生成
- **Parallel writes** - 多个 agent 同时写入不同文件