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.
为整个代码库创建全面的分层AGENTS.md文档。

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}

{目录名称}

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: node_modules, .git, dist, build, __pycache__, .venv, coverage, .next, .nuxt")
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

步骤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: / (root)
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
当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
undefined
生成完成后，运行验证检查：
检查项验证方式纠正措施
父引用可解析读取每个AGENTS.md，检查 
<!-- Parent: -->
路径是否存在		修复路径或移除孤立文件
无孤立AGENTS.md对比AGENTS.md位置与目录结构删除孤立文件
完整性列出所有目录，检查是否存在AGENTS.md生成缺失文件
时间戳最新检查 
<!-- Generated: -->
日期		重新生成过时文件
验证脚本示例：
bash
undefined

Find all AGENTS.md files

Find all AGENTS.md files

find . -name "AGENTS.md" -type f
find . -name "AGENTS.md" -type f

Check parent references

Check parent references

grep -r "<!-- Parent:" --include="AGENTS.md" .
undefined
grep -r "<!-- Parent:" --include="AGENTS.md" .
undefined

Smart Delegation

智能委派

TaskAgent
Directory mapping
explore
File analysis
architect-low
Content generation
writer
AGENTS.md writes
writer
任务Agent
目录映射
explore
文件分析
architect-low
内容生成
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

Purpose

Container directory for organizing related modules.
Container directory for organizing related modules.

Subdirectories

Subdirectories

DirectoryPurpose
subdir/
Description (see 
subdir/AGENTS.md
)
undefined
DirectoryPurpose
subdir/
Description (see 
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
  • 通用模板内容
  • 错误的文件名
  • 无效的父引用
  • 遗漏重要文件

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

Purpose

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

Key Files

Key Files

FileDescription
package.json
Project dependencies and scripts
tsconfig.json
TypeScript configuration
.env.example
Environment variable template
FileDescription
package.json
Project dependencies and scripts
tsconfig.json
TypeScript configuration
.env.example
Environment variable template

Subdirectories

Subdirectories

DirectoryPurpose
src/
Application source code (see 
src/AGENTS.md
)
docs/
Documentation (see 
docs/AGENTS.md
)
tests/
Test suites (see 
tests/AGENTS.md
)
DirectoryPurpose
src/
Application source code (see 
src/AGENTS.md
)
docs/
Documentation (see 
docs/AGENTS.md
)
tests/
Test suites (see 
tests/AGENTS.md
)

For AI Agents

For AI Agents

Working In This Directory

Working In This Directory

  • Always install dependencies after modifying the project manifest
  • Use TypeScript strict mode
  • Follow ESLint rules
  • Always install dependencies after modifying the project manifest
  • Use TypeScript strict mode
  • Follow ESLint rules

Testing Requirements

Testing Requirements

  • Run tests before committing
  • Ensure >80% coverage
  • Run tests before committing
  • Ensure >80% coverage

Common Patterns

Common Patterns

  • Use barrel exports (index.ts)
  • Prefer functional components
  • Use barrel exports (index.ts)
  • Prefer functional components

Dependencies

Dependencies

External

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 framework
  • TypeScript 5.x - Type safety
  • Vite - Build tool
<!-- MANUAL: Custom project notes can be added below --> 
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

Purpose

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

Key Files

Key Files

FileDescription
index.ts
Barrel export for all components
Button.tsx
Primary button component
Modal.tsx
Modal dialog component
FileDescription
index.ts
Barrel export for all components
Button.tsx
Primary button component
Modal.tsx
Modal dialog component

Subdirectories

Subdirectories

DirectoryPurpose
forms/
Form-related components (see 
forms/AGENTS.md
)
layout/
Layout components (see 
layout/AGENTS.md
)
DirectoryPurpose
forms/
Form-related components (see 
forms/AGENTS.md
)
layout/
Layout components (see 
layout/AGENTS.md
)

For AI Agents

For AI Agents

Working In This Directory

Working In This Directory

  • Each component has its own file
  • Use CSS modules for styling
  • Export via index.ts
  • Each component has its own file
  • Use CSS modules for styling
  • Export via index.ts

Testing Requirements

Testing Requirements

  • Unit tests in 
    __tests__/
    subdirectory
  • Use React Testing Library
  • Unit tests in 
    __tests__/
    subdirectory
  • Use React Testing Library

Common Patterns

Common Patterns

  • Props interfaces defined above component
  • Use forwardRef for DOM-exposing components
  • Props interfaces defined above component
  • Use forwardRef for DOM-exposing components

Dependencies

Dependencies

Internal

Internal

  • src/hooks/
    - Custom hooks used by components
  • src/utils/
    - Utility functions
  • src/hooks/
    - Custom hooks used by components
  • src/utils/
    - Utility functions

External

External

  • clsx
    - Conditional class names
  • lucide-react
    - Icons
<!-- MANUAL: --> 
undefined
  • clsx
    - Conditional class names
  • lucide-react
    - Icons
<!-- 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同时写入不同文件