Back to Details

deepinit

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Deep Init Skill

Deep Init Skill

Creates comprehensive, hierarchical AGENTS.md documentation across the entire codebase.
Read references/scope-and-preservation.md before running on a repository with existing AGENTS.md files or runtime directories. Validate results with 
scripts/validate_agents_hierarchy.py
.
在整个代码库中创建全面的层级化AGENTS.md文档。
运行前请阅读references/scope-and-preservation.md，如果仓库中已有AGENTS.md文件或运行时目录。使用
scripts/validate_agents_hierarchy.py
验证结果。

Core Concept

核心概念

AGENTS.md files serve as AI-readable documentation that helps agents understand:
  • What each directory contains
  • How components relate to each other
  • Special instructions for working in that area
  • Dependencies and relationships
AGENTS.md文件作为AI可读文档，帮助Agent理解：
  • 每个目录包含的内容
  • 组件之间的关联方式
  • 在该区域工作的特殊说明
  • 依赖关系

Hierarchical Tagging System

层级标签系统

Every AGENTS.md (except root) includes a parent reference tag:
markdown
<!-- Parent: ../AGENTS.md -->
This creates a navigable hierarchy:
/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都包含父引用标签：
markdown
<!-- Parent: ../AGENTS.md -->
这会创建一个可导航的层级结构：
/AGENTS.md                          ← 根目录（无父标签）
├── 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

AGENTS.md模板

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

{Directory Name}

{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}
FileDescription
file.ts
Brief description of purpose
{列出每个重要文件并附带一行描述}
文件描述
file.ts
用途的简要描述

Subdirectories

子目录

{List each subdirectory with brief purpose}
DirectoryPurpose
subdir/
What it contains (see 
subdir/AGENTS.md
)
{列出每个子目录并简要说明用途}
目录用途
subdir/
包含内容（详见
subdir/AGENTS.md
）

For AI Agents

面向AI Agent

Working In This Directory

在此目录中工作

{Special instructions for AI agents modifying files here}
{针对AI Agent修改此目录文件的特殊说明}

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: Any manually added notes below this line are preserved on regeneration --> 
undefined
{使用的关键外部包/库}
<!-- MANUAL: 此行以下的手动添加注释在重新生成时会被保留 --> 
undefined

Execution Workflow

执行流程

Step 1: Map Directory Structure

步骤1：映射目录结构

Task(subagent_type="explore", model="haiku",
  prompt="List all directories recursively. Exclude runtime/build/cache directories from references/scope-and-preservation.md.")
Default excludes:
  • .git/
    , 
    node_modules/
    , 
    dist/
    , 
    build/
    , 
    coverage/
    , 
    .next/
    , 
    .nuxt/
    , 
    __pycache__/
    , 
    .venv/
    , 
    venv/
  • Root runtime state: 
    .omc/
    , 
    .omx/
    , 
    .survey/
    , 
    .codex/
    , 
    .claude/
    , 
    .gemini/
    , 
    .agents/
    , 
    .opencode/
    , 
    .ouroboros/
Keep 
.agent-skills/
in scope because it is repository source, not runtime state.
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/
纳入范围，因为它是仓库源码，而非运行时状态。

Step 2: Create Work Plan

步骤2：创建工作计划

Generate todo items for each directory, organized by depth level:
Level 0: / (root)
Level 1: /src, /docs, /tests
Level 2: /src/components, /src/utils, /docs/api
...
生成按深度级别组织的每个目录的待办事项：
Level 0: / (根目录)
Level 1: /src, /docs, /tests
Level 2: /src/components, /src/utils, /docs/api
...

Step 3: Generate Level by Level

步骤3：按层级生成

IMPORTANT: Generate parent levels before child levels to ensure parent references are valid.
For each directory:
  1. Read all files in the directory
  2. Analyze purpose and relationships
  3. Generate AGENTS.md content
  4. Write file with proper parent reference
重要提示：先生成父层级，再生成子层级，确保父引用有效。
针对每个目录：
  1. 读取目录中的所有文件
  2. 分析用途和关联关系
  3. 生成AGENTS.md内容
  4. 写入带有正确父引用的文件

Step 4: Compare and Update (if exists)

步骤4：对比与更新（若已存在）

When AGENTS.md already exists:
  1. Read existing content
  2. Identify sections:
    • Auto-generated sections (can be updated)
    • Manual sections (
      <!-- MANUAL -->
      preserved)
  3. Compare:
    • New files added?
    • Files removed?
    • Structure changed?
  4. Merge:
    • Update auto-generated content
    • Preserve manual annotations
    • Update timestamp
    • Keep existing instructions that are still true; flag stale instructions instead of deleting them silently
当AGENTS.md已存在时：
  1. 读取现有内容
  2. 识别区块：
    • 自动生成区块（可更新）
    • 手动区块（
      <!-- MANUAL -->
      会被保留）
  3. 对比：
    • 是否新增文件？
    • 是否删除文件？
    • 结构是否变化？
  4. 合并：
    • 更新自动生成的内容
    • 保留手动注释
    • 更新时间戳
    • 保留仍然有效的现有说明；标记过时说明而非静默删除

Step 5: Validate Hierarchy

步骤5：验证层级结构

After generation, run validation checks:
CheckHow to VerifyCorrective Action
Parent references resolveRead each AGENTS.md, check 
<!-- Parent: -->
path exists		Fix path or remove orphan
No orphaned AGENTS.mdCompare AGENTS.md locations to directory structureDelete orphaned files
CompletenessList all directories, check for AGENTS.mdGenerate missing files
Timestamps currentCheck 
<!-- Generated: -->
dates		Regenerate outdated files
Validation script pattern:
bash
python3 .agent-skills/deepinit/scripts/validate_agents_hierarchy.py .
生成完成后，运行验证检查：
检查项验证方式纠正措施
父引用可解析读取每个AGENTS.md，检查
<!-- Parent: -->
路径是否存在		修复路径或移除孤立文件
无孤立AGENTS.md对比AGENTS.md位置与目录结构删除孤立文件
完整性列出所有目录，检查是否存在AGENTS.md生成缺失文件
时间戳最新检查
<!-- Generated: -->
日期		重新生成过时文件
验证脚本示例：
bash
python3 .agent-skills/deepinit/scripts/validate_agents_hierarchy.py .

Smart Delegation

智能委派

TaskAgent
Directory mapping
explore
File analysis
architect
Content generation
writer
AGENTS.md writes
writer
任务Agent
目录映射
explore
文件分析
architect
内容生成
writer
AGENTS.md写入
writer

Empty Directory Handling

空目录处理

When encountering empty or near-empty directories:
ConditionAction
No files, no subdirectoriesSkip - do not create AGENTS.md
No files, has subdirectoriesCreate minimal AGENTS.md with subdirectory listing only
Has only generated files (*.min.js, *.map)Skip or minimal AGENTS.md
Has only config filesCreate AGENTS.md describing configuration purpose
Example minimal AGENTS.md for directory-only containers:
markdown
<!-- Parent: ../AGENTS.md -->
遇到空目录或近乎空的目录时：
条件操作
无文件且无子目录跳过 - 不创建AGENTS.md
无文件但有子目录创建仅包含子目录列表的极简AGENTS.md
仅包含生成文件（*.min.js, *.map）跳过或创建极简AGENTS.md
仅包含配置文件创建描述配置用途的AGENTS.md
仅包含目录的容器的极简AGENTS.md示例：
markdown
<!-- Parent: ../AGENTS.md -->

{Directory Name}

{Directory Name}

Purpose

用途

Container directory for organizing related modules.
用于组织相关模块的容器目录。

Subdirectories

子目录

DirectoryPurpose
subdir/
Description (see 
subdir/AGENTS.md
)
undefined
目录用途
subdir/
描述（详见
subdir/AGENTS.md
）
undefined

Parallelization Rules

并行化规则

  1. Same-level directories: Process in parallel
  2. Different levels: Sequential (parent first)
  3. Large directories: Spawn dedicated agent per directory
  4. Small directories: Batch multiple into one agent
  1. 同级目录：并行处理
  2. 不同层级：顺序处理（先父后子）
  3. 大型目录：为每个目录分配专属Agent
  4. 小型目录：批量分配给单个Agent

Quality Standards

质量标准

Must Include

必须包含

  • Accurate file descriptions
  • Correct parent references
  • Subdirectory links
  • AI agent instructions
  • 准确的文件描述
  • 正确的父引用
  • 子目录链接
  • AI Agent操作说明

Must Avoid

必须避免

  • Generic boilerplate
  • Incorrect file names
  • Broken parent references
  • Missing important files
  • Documenting ignored runtime state as source architecture
  • Replacing user-authored manual notes
  • 通用模板内容
  • 错误的文件名
  • 无效的父引用
  • 遗漏重要文件
  • 将被忽略的运行时状态记录为源码架构
  • 替换用户编写的手动注释

Runtime-Specific Notes

运行时特定说明

RuntimeDocumentation rule
Claude Code / OMCRoot 
AGENTS.md
may mention Claude workflow, but do not document 
.omc/
state as source
Codex / OMXRoot 
AGENTS.md
should be suitable for Codex model instruction injection; do not document 
.omx/
state as source
Gemini / Antigravity / OMADocument 
.agents/
only when it is intentionally checked in as harness source; otherwise treat root 
.agents/
as generated/runtime state
.agent-skills/
Always allowed as source; document skill folders, scripts, references, evals, and validation commands
运行环境文档规则
Claude Code / OMC根目录
AGENTS.md
可提及Claude工作流，但不得将
.omc/
状态记录为源码
Codex / OMX根目录
AGENTS.md
需适合Codex模型指令注入；不得将
.omx/
状态记录为源码
Gemini / Antigravity / OMA仅当
.agents/
被有意提交为 harness 源码时才记录；否则将根目录
.agents/
视为生成/运行时状态
.agent-skills/
始终视为源码；记录技能文件夹、脚本、参考文献、评估和验证命令

Example Output

示例输出

Root AGENTS.md

根目录AGENTS.md

markdown
<!-- Generated: 2024-01-15 | Updated: 2024-01-15 -->
markdown
<!-- Generated: 2024-01-15 | Updated: 2024-01-15 -->

my-project

my-project

Purpose

用途

A web application for managing user tasks with real-time collaboration features.
一款具备实时协作功能的用户任务管理Web应用。

Key Files

关键文件

FileDescription
package.json
Project dependencies and scripts
tsconfig.json
TypeScript configuration
.env.example
Environment variable template
文件描述
package.json
项目依赖和脚本
tsconfig.json
TypeScript配置
.env.example
环境变量模板

Subdirectories

子目录

DirectoryPurpose
src/
Application source code (see 
src/AGENTS.md
)
docs/
Documentation (see 
docs/AGENTS.md
)
tests/
Test suites (see 
tests/AGENTS.md
)
目录用途
src/
应用源码（详见
src/AGENTS.md
）
docs/
文档（详见
docs/AGENTS.md
）
tests/
测试套件（详见
tests/AGENTS.md
）

For AI Agents

面向AI Agent

Working In This Directory

在此目录中工作

  • Always install dependencies after modifying the project manifest
  • Use TypeScript strict mode
  • Follow ESLint rules
  • 修改项目清单后务必安装依赖
  • 使用TypeScript严格模式
  • 遵循ESLint规则

Testing Requirements

测试要求

  • Run tests before committing
  • Ensure >80% coverage
  • 提交前运行测试
  • 确保覆盖率>80%

Common Patterns

常见模式

  • Use barrel exports (index.ts)
  • Prefer functional components
  • 使用桶导出（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 --> 
undefined
  • React 18.x - UI框架
  • TypeScript 5.x - 类型安全
  • Vite - 构建工具
<!-- MANUAL: 可在下方添加自定义项目注释 --> 
undefined

Nested AGENTS.md

嵌套AGENTS.md

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

components

components

Purpose

用途

Reusable React components organized by feature and complexity.
按功能和复杂度组织的可复用React组件。

Key Files

关键文件

FileDescription
index.ts
Barrel export for all components
Button.tsx
Primary button component
Modal.tsx
Modal dialog component
文件描述
index.ts
所有组件的桶导出
Button.tsx
主按钮组件
Modal.tsx
模态对话框组件

Subdirectories

子目录

DirectoryPurpose
forms/
Form-related components (see 
forms/AGENTS.md
)
layout/
Layout components (see 
layout/AGENTS.md
)
目录用途
forms/
表单相关组件（详见
forms/AGENTS.md
）
layout/
布局组件（详见
layout/AGENTS.md
）

For AI Agents

面向AI Agent

Working In This Directory

在此目录中工作

  • Each component has its own file
  • Use CSS modules for styling
  • Export via index.ts
  • 每个组件单独存放在一个文件中
  • 使用CSS模块进行样式管理
  • 通过index.ts导出

Testing Requirements

测试要求

  • Unit tests in 
    __tests__/
    subdirectory
  • Use React Testing Library
  • 单元测试位于
    __tests__/
    子目录
  • 使用React Testing Library

Common Patterns

常见模式

  • Props interfaces defined above component
  • Use forwardRef for DOM-exposing components
  • 组件上方定义Props接口
  • 对暴露DOM的组件使用forwardRef

Dependencies

依赖

Internal

内部

  • src/hooks/
    - Custom hooks used by components
  • src/utils/
    - Utility functions
  • src/hooks/
    - 组件使用的自定义hooks
  • src/utils/
    - 工具函数

External

外部

  • clsx
    - Conditional class names
  • lucide-react
    - Icons
<!-- MANUAL: --> 
undefined
  • clsx
    - 条件类名
  • lucide-react
    - 图标库
<!-- MANUAL: --> 
undefined

Triggering Update Mode

触发更新模式

When running on an existing codebase with AGENTS.md files:
  1. Detect existing files first
  2. Read and parse existing content
  3. Analyze current directory state
  4. Generate diff between existing and current
  5. Apply updates while preserving manual sections
在已有AGENTS.md文件的现有代码库上运行时：
  1. 先检测现有文件
  2. 读取并解析现有内容
  3. 分析当前目录状态
  4. 生成现有内容与当前状态的差异
  5. 应用更新同时保留手动区块

Performance Considerations

性能考量

  • Cache directory listings - Don't re-scan same directories
  • Batch small directories - Process multiple at once
  • Skip unchanged - If directory hasn't changed, skip regeneration
  • Parallel writes - Multiple agents writing different files simultaneously
  • 缓存目录列表 - 不要重复扫描相同目录
  • 批量处理小型目录 - 同时处理多个目录
  • 跳过未更改内容 - 如果目录未发生变化，跳过重新生成
  • 并行写入 - 多个Agent同时写入不同文件

References

参考资料

  • Scope and preservation
  • scripts/validate_agents_hierarchy.py
  • 范围与保留规则
  • scripts/validate_agents_hierarchy.py