deepinit

Deep Init Skill

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

核心概念

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

• 每个目录包含什么内容
• 各组件之间如何关联
• 在该区域工作的特殊说明
• 依赖关系和关联关系

分层标记系统

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

**Parent context:** `../AGENTS.md`

这必须是可见的正文，绝不能是 HTML 注释。Claude Code 会在记忆文件到达模型之前剥离 HTML 注释，因此 、 以及被注释掉的 MANUAL 边界对应当对其采取行动的 Agent 来说是不可见的。

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

/AGENTS.md                          ← Root (no parent line)
├── src/AGENTS.md                   ← **Parent context:** `../AGENTS.md`
│   ├── src/components/AGENTS.md    ← **Parent context:** `../AGENTS.md`
│   └── src/utils/AGENTS.md         ← **Parent context:** `../AGENTS.md`
└── docs/AGENTS.md                  ← **Parent context:** `../AGENTS.md`

加载模型

原生 Claude Code 按 basename 发现嵌套的 CLAUDE.md，并且从不加载 嵌套的 AGENTS.md；根目录的 @AGENTS.md 导入也无法到达子目录。 这里生成的嵌套文件由 OMC 的 PostToolUse 目录上下文注入器提供，它会从每个被访问的文件向上遍历，并在每个会话中注入最近的 AGENTS.md/README.md 一次。

这意味着该层级结构需要 OMC 的 hooks 处于激活状态。当 OMC hooks 被 禁用（DISABLE_OMC=1、OMC_SKIP_HOOKS=post-tool-use）或插件未 注册时，请为根文件添加根级 CLAUDE.md 符号链接或 @AGENTS.md 导入，并预期嵌套文件将保持未被读取。

AGENTS.md 模板

# {Directory Name}

**Parent context:** `{relative_path_to_parent}/AGENTS.md`
**Generated:** {timestamp} · **Updated:** {timestamp}

## Purpose
{One-paragraph description of what this directory contains and its role}

## Key Files
{List each significant file with a one-line description}

| File | Description |
|------|-------------|
| `file.ts` | Brief description of purpose |

## Subdirectories
{List each subdirectory with brief purpose}

| Directory | Purpose |
|-----------|---------|
| `subdir/` | What it contains (see `subdir/AGENTS.md`) |

## For AI Agents

### Working In This Directory
{Special instructions for AI agents modifying files here}

### Testing Requirements
{How to test changes in this directory}

### Common Patterns
{Code patterns or conventions used here}

## Dependencies

### Internal
{References to other parts of the codebase this depends on}

### External
{Key external packages/libraries used}

## Manual Notes

Notes under this heading are written by humans and preserved on regeneration.

执行工作流

步骤 1：映射目录结构

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

步骤 2：创建工作计���

为每个目录生成 todo 项，按深度层级组织：

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

步骤 3：逐层生成

重要：先于子层级生成父层级，以确保父级引用有效。

对于每个目录：

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

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

当 AGENTS.md 已存在时：

1. 读取现有内容
2. 识别各部分：
   • 自动生成的部分（可更新）
   • 手动部分（## Manual Notes 标题及其下的所有内容会被保留）
3. 比较：
   • 是否添加了新文件？
   • 是否删除了文件？
   • 结构是否发生了变化？
4. 合并：
   • 更新自动生成的内容
   • 保留手动注释
   • 更新时间戳

步骤 5：验证层级结构

生成后，运行验证检查：

检查项	如何验证	纠正措施
父级引用可解析	读取每个 AGENTS.md，检查 **Parent context:** 路径是否存在	修正路径或删除孤立文件
无孤立的 AGENTS.md	将 AGENTS.md 位置与目录结构进行比较	删除孤立文件
完整性	列出所有目录，检查是否有 AGENTS.md	生成缺失的文件
时间戳为最新	检查 **Generated:** / **Updated:** 日期	重新生成过期的文件

验证脚本模式：

# Find all AGENTS.md files
find . -name "AGENTS.md" -type f

# Check parent references
grep -r "\*\*Parent context:\*\*" --include="AGENTS.md" .

智能委派

任务	Agent
目录映射	explore
文件分析	architect
内容生成	writer
AGENTS.md 写入	writer

空目录处理

当遇到空目录或近乎空的目录时：

情况	操作
无文件、无子目录	跳过 - 不创建 AGENTS.md
无文件、有子目录	创建仅含子目录列表的最小 AGENTS.md
仅有生成的文件（.min.js、.map）	跳过或创建最小 AGENTS.md
仅有配置文件	创建描述配置用途的 AGENTS.md

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

# {Directory Name}

**Parent context:** `../AGENTS.md`

## Purpose
Container directory for organizing related modules.

## Subdirectories
| Directory | Purpose |
|-----------|---------|
| `subdir/` | Description (see `subdir/AGENTS.md`) |

并行化规则

1. 同级目录：并行处理
2. 不同层级：顺序处理（父级优先）
3. 大型目录：为每个目录分配专用 Agent
4. 小型目录：将多个目录批量合并到一个 Agent

质量标准

必须包含

• 准确的文件描述
• 正确的父级引用
• 子目录链接
• AI Agent 指令

必须避免

• 通用样板内容
• 错误的文件名
• 损坏的父级引用
• 遗漏重要文件

示例输出

根 AGENTS.md

# my-project

**Generated:** 2024-01-15 · **Updated:** 2024-01-15

## Purpose
A web application for managing user tasks with real-time collaboration features.

## Key Files
| File | Description |
|------|-------------|
| `package.json` | Project dependencies and scripts |
| `tsconfig.json` | TypeScript configuration |
| `.env.example` | Environment variable template |

## Subdirectories
| Directory | Purpose |
|-----------|---------|
| `src/` | Application source code (see `src/AGENTS.md`) |
| `docs/` | Documentation (see `docs/AGENTS.md`) |
| `tests/` | Test suites (see `tests/AGENTS.md`) |

## For AI Agents

### Working In This Directory
- Always install dependencies after modifying the project manifest
- Use TypeScript strict mode
- Follow ESLint rules

### Testing Requirements
- Run tests before committing
- Ensure >80% coverage

### Common Patterns
- Use barrel exports (index.ts)
- Prefer functional components

## Dependencies

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

## Manual Notes

Custom project notes can be added under this heading.

嵌套 AGENTS.md

# components

**Parent context:** `../AGENTS.md`
**Generated:** 2024-01-15 · **Updated:** 2024-01-15

## Purpose
Reusable React components organized by feature and complexity.

## Key Files
| File | Description |
|------|-------------|
| `index.ts` | Barrel export for all components |
| `Button.tsx` | Primary button component |
| `Modal.tsx` | Modal dialog component |

## Subdirectories
| Directory | Purpose |
|-----------|---------|
| `forms/` | Form-related components (see `forms/AGENTS.md`) |
| `layout/` | Layout components (see `layout/AGENTS.md`) |

## For AI Agents

### Working In This Directory
- Each component has its own file
- Use CSS modules for styling
- Export via index.ts

### Testing Requirements
- Unit tests in `__tests__/` subdirectory
- Use React Testing Library

### Common Patterns
- Props interfaces defined above component
- Use forwardRef for DOM-exposing components

## Dependencies

### Internal
- `src/hooks/` - Custom hooks used by components
- `src/utils/` - Utility functions

### External
- `clsx` - Conditional class names
- `lucide-react` - Icons

## Manual Notes

触发更新模式

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

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

性能注意事项

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