deepinit

Deep Init Skill

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

既存の AGENTS.md ファイルまたはランタイムディレクトリがあるリポジトリで実行する前に、references/scope-and-preservation.md を読んでください。結果は scripts/validate_agents_hierarchy.py で検証してください。

基本概念

AGENTS.md ファイルはAI が読み取れるドキュメントとして機能し、エージェントが以下を理解するのに役立ちます。

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

階層タグ付けシステム

ルートを除くすべての 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：作業計画を作成する

深さのレベルごとに整理して、各ディレクトリの 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. セクションを特定する：
   • 自動生成されたセクション（更新可能）
   • 手動セクション（`` 保持）
3. 比較する：
   • 新しいファイルが追加されたか？
   • ファイルが削除されたか？
   • 構造が変わったか？
4. マージする：
   • 自動生成された内容を更新する
   • 手動の注釈を保持する
   • タイムスタンプを更新する
   • 現在も有効な既存の指示は保持し、古くなった指示は黙って削除せず、古くなっていることを明示する

ステップ 5：階層を検証する

生成後、検証チェックを実行します。

チェック	確認方法	修正方法
親参照が解決できる	各 AGENTS.md を読み、`` のパスが存在することを確認する	パスを修正するか、親のない項目を削除する
親のない AGENTS.md がない	AGENTS.md の場所をディレクトリ構造と照合する	親のないファイルを削除する
網羅性	すべてのディレクトリを一覧表示し、AGENTS.md があるか確認する	不足しているファイルを生成する
タイムスタンプが最新	`` の日付を確認する	古いファイルを再生成する

検証スクリプトのパターン：

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

スマートな委任

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

品質基準

必ず含める項目

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

避けるべきこと

• 汎用的な定型文
• 誤ったファイル名
• 壊れた親参照
• 重要なファイルの記載漏れ
• 無視されるランタイム状態をソースアーキテクチャとして記載すること
• ユーザーが作成した手動メモの置き換え

ランタイム固有の注意事項

ランタイム	ドキュメント作成ルール
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. 手動セクションを保持しながら更新を適用する

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

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

参考資料

• スコープと保持
• scripts/validate_agents_hierarchy.py