index-knowledge

index-knowledge

階層的な AGENTS.md ファイルを生成します。ルートと、複雑さをスコア化したサブディレクトリを対象とします。

使い方

--create-new   # Read existing → remove all → regenerate from scratch
--max-depth=2  # Limit directory depth (default: 5)

デフォルト：更新モード（既存ファイルを変更し、必要に応じて新規作成）

---

ワークフロー（概要）

1. 調査と分析（並行して実行）
   • 探索エージェントを並列で起動します（1 回のメッセージで複数の Task 呼び出しを実行）
   • メインセッション：bash による構造分析、LSP コードマップ、既存の AGENTS.md の読み込み
2. スコアリングと決定 - 統合した調査結果から AGENTS.md の配置場所を決定します
3. 生成 - まずルートを生成し、次にサブディレクトリを並列で生成します
4. レビュー - 重複を除去し、内容を絞り、検証します

**すべてのフェーズで TodoWrite を使用してください。リアルタイムで in_progress → completed に更新してください。**

TodoWrite([
  { id: "discovery", content: "Fire explore agents + LSP codemap + read existing", status: "pending", priority: "high" },
  { id: "scoring", content: "Score directories, determine locations", status: "pending", priority: "high" },
  { id: "generate", content: "Generate AGENTS.md files (root + subdirs)", status: "pending", priority: "high" },
  { id: "review", content: "Deduplicate, validate, trim", status: "pending", priority: "medium" }
])

---

フェーズ 1：調査と分析（並行して実行）

「discovery」を in_progress にします。

探索エージェントを並列で起動する

1 回のメッセージで複数の Task 呼び出しを実行すると、並列で実行されます。結果は直接返されます。

// All Task calls in ONE message = parallel execution

Task(
  description="project structure",
  subagent_type="explore",
  prompt="Project structure: PREDICT standard patterns for detected language → REPORT deviations only"
)

Task(
  description="entry points",
  subagent_type="explore",
  prompt="Entry points: FIND main files → REPORT non-standard organization"
)

Task(
  description="conventions",
  subagent_type="explore",
  prompt="Conventions: FIND config files (.eslintrc, pyproject.toml, .editorconfig) → REPORT project-specific rules"
)

Task(
  description="anti-patterns",
  subagent_type="explore",
  prompt="Anti-patterns: FIND 'DO NOT', 'NEVER', 'ALWAYS', 'DEPRECATED' comments → LIST forbidden patterns"
)

Task(
  description="build/ci",
  subagent_type="explore",
  prompt="Build/CI: FIND .github/workflows, Makefile → REPORT non-standard patterns"
)

Task(
  description="test patterns",
  subagent_type="explore",
  prompt="Test patterns: FIND test configs, test structure → REPORT unique conventions"
)

**動的なエージェントの起動**：bash による分析後、プロジェクトの規模に応じて追加の探索エージェントを起動します。

要素	しきい値	追加エージェント
ファイル総数	>100	100 ファイルごとに +1
行数合計	>10k	10k 行ごとに +1
ディレクトリの深さ	≥4	深い階層の探索に +2
大きなファイル（>500 行）	>10 ファイル	複雑な箇所の調査に +1
モノレポ	検出された場合	パッケージ／ワークスペースごとに +1
複数の言語	>1	言語ごとに +1

# Measure project scale first
total_files=$(find . -type f -not -path '*/node_modules/*' -not -path '*/.git/*' | wc -l)
total_lines=$(find . -type f \( -name "*.ts" -o -name "*.py" -o -name "*.go" \) -not -path '*/node_modules/*' -exec wc -l {} + 2>/dev/null | tail -1 | awk '{print $1}')
large_files=$(find . -type f \( -name "*.ts" -o -name "*.py" \) -not -path '*/node_modules/*' -exec wc -l {} + 2>/dev/null | awk '$1 > 500 {count++} END {print count+0}')
max_depth=$(find . -type d -not -path '*/node_modules/*' -not -path '*/.git/*' | awk -F/ '{print NF}' | sort -rn | head -1)

起動例（並列実行のため、すべてを 1 つのメッセージで実行）：

// 500 files, 50k lines, depth 6, 15 large files → spawn additional agents
Task(
  description="large files",
  subagent_type="explore",
  prompt="Large file analysis: FIND files >500 lines, REPORT complexity hotspots"
)

Task(
  description="deep modules",
  subagent_type="explore",
  prompt="Deep modules at depth 4+: FIND hidden patterns, internal conventions"
)

Task(
  description="cross-cutting",
  subagent_type="explore",
  prompt="Cross-cutting concerns: FIND shared utilities across directories"
)
// ... more based on calculation

メインセッション：並行分析

Task エージェントの実行中に、メインセッションでは次を実行します。

1. bash による構造分析

# Directory depth + file counts
find . -type d -not -path '*/\.*' -not -path '*/node_modules/*' -not -path '*/venv/*' -not -path '*/dist/*' -not -path '*/build/*' | awk -F/ '{print NF-1}' | sort -n | uniq -c

# Files per directory (top 30)
find . -type f -not -path '*/\.*' -not -path '*/node_modules/*' | sed 's|/[^/]*$||' | sort | uniq -c | sort -rn | head -30

# Code concentration by extension
find . -type f \( -name "*.py" -o -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.go" -o -name "*.rs" \) -not -path '*/node_modules/*' | sed 's|/[^/]*$||' | sort | uniq -c | sort -rn | head -20

# Existing AGENTS.md / CLAUDE.md
find . -type f \( -name "AGENTS.md" -o -name "CLAUDE.md" \) -not -path '*/node_modules/*' 2>/dev/null

2. 既存の AGENTS.md を読む

For each existing file found:
  Read(filePath=file)
  Extract: key insights, conventions, anti-patterns
  Store in EXISTING_AGENTS map

--create-new の場合：まず既存ファイルをすべて読み込み（コンテキストを保持）→ その後すべて削除 → 再生成します。

3. LSP コードマップ（利用可能な場合）

lsp_servers()  # Check availability

# Entry points (parallel)
lsp_document_symbols(filePath="src/index.ts")
lsp_document_symbols(filePath="main.py")

# Key symbols (parallel)
lsp_workspace_symbols(filePath=".", query="class")
lsp_workspace_symbols(filePath=".", query="interface")
lsp_workspace_symbols(filePath=".", query="function")

# Centrality for top exports
lsp_find_references(filePath="...", line=X, character=Y)

LSP のフォールバック：利用できない場合は、探索エージェントと AST-grep を活用します。

bash + LSP + 既存ファイル + Task エージェントの結果を統合します。「discovery」を completed にします。

---

フェーズ 2：スコアリングと配置場所の決定

「scoring」を in_progress にします。

スコアリング基準

要素	重み	高スコアのしきい値	情報源
ファイル数	3x	>20	bash
サブディレクトリ数	2x	>5	bash
コードの割合	2x	>70%	bash
固有のパターン	1x	独自の設定がある	explore
モジュール境界	2x	index.ts/init.py がある	bash
シンボル密度	2x	>30 個のシンボル	LSP
エクスポート数	2x	>10 個のエクスポート	LSP
参照の中心性	3x	>20 件の参照	LSP

決定ルール

スコア	アクション
ルート（.）	必ず作成
>15	AGENTS.md を作成
8-15	明確に異なる領域の場合に作成
<8	スキップ（親ディレクトリでカバー）

出力

AGENTS_LOCATIONS = [
  { path: ".", type: "root" },
  { path: "src/hooks", score: 18, reason: "high complexity" },
  { path: "src/api", score: 12, reason: "distinct domain" }
]

「scoring」を completed にします。

---

フェーズ 3：AGENTS.md の生成

「generate」を in_progress にします。

ルートの AGENTS.md（全体を詳しく記述）

# PROJECT KNOWLEDGE BASE

**Generated:** {TIMESTAMP}
**Commit:** {SHORT_SHA}
**Branch:** {BRANCH}

## OVERVIEW
{1-2 sentences: what + core stack}

## STRUCTURE
\`\`\`
{root}/
├── {dir}/    # {non-obvious purpose only}
└── {entry}
\`\`\`

## WHERE TO LOOK
| Task | Location | Notes |
|------|----------|-------|

## CODE MAP
{From LSP - skip if unavailable or project <10 files}

| Symbol | Type | Location | Refs | Role |

## CONVENTIONS
{ONLY deviations from standard}

## ANTI-PATTERNS (THIS PROJECT)
{Explicitly forbidden here}

## UNIQUE STYLES
{Project-specific}

## COMMANDS
\`\`\`bash
{dev/test/build}
\`\`\`

## NOTES
{Gotchas}

品質ゲート：50～150 行。汎用的な助言や自明な情報は含めません。

サブディレクトリの AGENTS.md（並列）

各配置場所に対して汎用エージェントを起動します。並列実行のため、1 回のメッセージで実行します。

// All in single message = parallel
Task(
  description="AGENTS.md for src/hooks",
  subagent_type="general",
  prompt="Generate AGENTS.md for: src/hooks
    - Reason: high complexity
    - 30-80 lines max
    - NEVER repeat parent content
    - Sections: OVERVIEW (1 line), STRUCTURE (if >5 subdirs), WHERE TO LOOK, CONVENTIONS (if different), ANTI-PATTERNS
    - Write directly to src/hooks/AGENTS.md"
)

Task(
  description="AGENTS.md for src/api",
  subagent_type="general",
  prompt="Generate AGENTS.md for: src/api
    - Reason: distinct domain
    - 30-80 lines max
    - NEVER repeat parent content
    - Sections: OVERVIEW (1 line), STRUCTURE (if >5 subdirs), WHERE TO LOOK, CONVENTIONS (if different), ANTI-PATTERNS
    - Write directly to src/api/AGENTS.md"
)
// ... one Task per AGENTS_LOCATIONS entry

結果は直接返されます。「generate」を completed にします。

---

フェーズ 4：レビューと重複の除去

「review」を in_progress にします。

生成した各ファイルについて：

• 汎用的な助言を削除する
• 親ディレクトリと重複する内容を削除する
• サイズ制限に合わせて内容を絞る
• 電文調のスタイルになっているか確認する

「review」を completed にします。

---

最終レポート

=== index-knowledge Complete ===

Mode: {update | create-new}

Files:
  ✓ ./AGENTS.md (root, {N} lines)
  ✓ ./src/hooks/AGENTS.md ({N} lines)

Dirs Analyzed: {N}
AGENTS.md Created: {N}
AGENTS.md Updated: {N}

Hierarchy:
  ./AGENTS.md
  └── src/hooks/AGENTS.md

---

アンチパターン

• エージェント数を固定する：プロジェクトの規模や深さに応じて、エージェント数を必ず変える
• 逐次実行する：必ず並列実行する（1 回のメッセージで複数の Task 呼び出しを実行）
• 既存ファイルを無視する：--create-new を指定した場合も、必ず最初に既存ファイルを読む
• 文書化しすぎる：すべてのディレクトリに AGENTS.md が必要とは限らない
• 冗長にする：子ディレクトリでは親の内容を繰り返さない
• 汎用的な内容を含める：すべてのプロジェクトに当てはまる内容は削除する
• 冗長な文体にする：電文調にすること