deepinit

Deep Init Skill

コードベース全体に、包括的で階層的な AGENTS.md ドキュメントを作成します。

基本概念

AGENTS.md ファイルは、エージェントが次の内容を理解するのに役立つ、AI が読み取れるドキュメントです。

• 各ディレクトリに含まれる内容
• コンポーネント同士の関係
• その領域で作業する際の特別な指示
• 依存関係と関連性

階層タグ付けシステム

ルート以外のすべての AGENTS.md には、親を参照する行を含めます。

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

これは必ず通常の文章として表示し、HTML コメントにしてはいけません。Claude Code はメモリファイルがモデルに渡される前に HTML コメントを削除するため、、 、コメントアウトされた MANUAL 境界は、それらに従って動作するはずのエージェントから見えません。

これにより、たどることのできる階層が作成されます。

/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 は、ファイル名を基準にネストされた CLAUDE.md を検出しますが、ネストされた AGENTS.md は読み込みません。また、ルートの @AGENTS.md インポートもサブディレクトリには適用されません。ここで生成されるネストされたファイルは、OMC の PostToolUse ディレクトリコンテキストインジェクターによって提供されます。このインジェクターは、アクセスされたファイルから上位ディレクトリをたどり、最も近い AGENTS.md／README.md をセッションごとに一度読み込みます。

つまり、この階層を利用するには OMC のフックが有効になっている必要があります。OMC のフックが無効になっている場合（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" .

スマートな委任

タスク	エージェント
ディレクトリのマッピング	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. 大きなディレクトリ：ディレクトリごとに専任のエージェントを起動する
4. 小さなディレクトリ：複数をまとめて一つのエージェントに割り当てる

品質基準

含める必要がある項目

• 正確なファイルの説明
• 正しい親ファイルへの参照
• サブディレクトリへのリンク
• AI エージェントへの指示

避ける必要がある項目

• 汎用的な定型文
• 誤ったファイル名
• 壊れた親ファイルへの参照
• 重要なファイルの欠落

出力例

ルートの 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. 手動で記述されたセクションを保持しながら更新を適用します

パフォーマンスに関する考慮事項

• ディレクトリ一覧をキャッシュする - 同じディレクトリを再スキャンしないでください
• 小さなディレクトリをまとめて処理する - 複数のディレクトリを一度に処理します
• 変更がないものはスキップする - ディレクトリに変更がなければ、再生成をスキップします
• 並列書き込み - 複数のエージェントが異なるファイルに同時に書き込みます