deepinit

Deep Init Skill

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

在对已有 AGENTS.md 文件或运行时目录的仓库执行操作前，请阅读 references/scope-and-preservation.md。使用 scripts/validate_agents_hierarchy.py 验证结果。

核心概念

AGENTS.md 文件是供 AI 阅读的文档，可帮助 Agent 了解：

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

分层标记系统

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

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

/AGENTS.md                          ← Root (no parent tag)
├── src/AGENTS.md                   ← 
│   ├── src/components/AGENTS.md    ← 
│   └── src/utils/AGENTS.md         ← 
└── docs/AGENTS.md                  ← 

AGENTS.md 模板

# {Directory Name}

## 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}

执行工作流

步骤 1：映射目录结构

Task(subagent_type="explore", model="haiku",
  prompt="List all directories recursively. Exclude runtime/build/cache directories from references/scope-and-preservation.md.")

默认排除项：

• .git/、node_modules/、dist/、build/、coverage/、.next/、.nuxt/、__pycache__/、.venv/、venv/
• 根目录运行时状态：.omc/、.omx/、.survey/、.codex/、.claude/、.gemini/、.agents/、.opencode/、.ouroboros/

将 .agent-skills/ 纳入范围，因为它是仓库源代码，而非运行时状态。

步骤 2：制定工作计划

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

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. 识别各部分：
   • 自动生成的部分（可以更新）
   • 手动编写的部分（`` 保留）
3. 比较：
   • 是否添加了新文件？
   • 是否移除了文件？
   • 结构是否发生变化？
4. 合并：
   • 更新自动生成的内容
   • 保留手动注释
   • 更新时间戳
   • 保留仍然有效的现有说明；将过时说明标记出来，而不是直接删除

步骤 5：验证层级结构

生成后，运行验证检查：

检查项	验证方法	修正操作
父级引用可解析	阅读每个 AGENTS.md，检查 `` 路径是否存在	修正路径或移除孤立引用
没有孤立的 AGENTS.md	将 AGENTS.md 的位置与目录结构进行比较	删除孤立文件
完整性	列出所有目录，检查是否有 AGENTS.md	生成缺失文件
时间戳为最新	检查 `` 日期	重新生成过期文件

验证脚本模式：

python3 .agent-skills/deepinit/scripts/validate_agents_hierarchy.py .

智能委派

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

空目录处理

遇到空目录或内容极少的目录时：

条件	操作
没有文件，也没有子目录	跳过——不要创建 AGENTS.md
没有文件，但有子目录	创建仅列出子目录的最简 AGENTS.md
仅包含生成文件（.min.js、.map）	跳过或创建最简 AGENTS.md
仅包含配置文件	创建说明配置用途的 AGENTS.md

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

# {Directory Name}

## Purpose
Container directory for organizing related modules.

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

并行化规则

1. 同级目录：并行处理
2. 不同级目录：按顺序处理（先父级）
3. 大型目录：为每个目录启动专用 Agent
4. 小型目录：将多个目录合并交由一个 Agent 处理

质量标准

必须包含

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

必须避免

• 通用模板内容
• 错误的文件名
• 错误的父级引用
• 遗漏重要文件
• 将被忽略的运行时状态记录为源架构
• 替换用户编写的手动备注

运行时专属说明

运行时	文档规则
Claude Code / OMC	根目录的 AGENTS.md 可以提及 Claude 工作流，但不要将 .omc/ 状态记录为源
Codex / OMX	根目录的 AGENTS.md 应适用于 Codex 模型指令注入；不要将 .omx/ 状态记录为源
Gemini / Antigravity / OMA	仅当 .agents/ 被有意作为工具源代码纳入版本控制时才对其进行记录；否则将根目录的 .agents/ 视为生成的/运行时状态
.agent-skills/	始终允许作为源；记录技能文件夹、脚本、参考资料、评估和验证命令

输出示例

根目录 AGENTS.md

# my-project

## 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

嵌套 AGENTS.md

# components

## 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

触发更新模式

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

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

性能注意事项

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

参考资料

• 范围与保留
• scripts/validate_agents_hierarchy.py