agentifind

Agentifind：コードベースインテリジェンスのセットアップ

このスキルでは、次の手順でコードベースインテリジェンスをセットアップします。

1. agentifind CLI を実行してコード構造を抽出します
2. 静的解析では完全に追跡できない動的パターンを検出します
3. 古さのメタデータを含むナビゲーションガイドを作成します

手順

ステップ 1：既存のガイドを確認する（古さの検出）

.claude/CODEBASE.md がすでに存在する場合は、古くなっていないか確認します。

1. CODEBASE.md のメタデータヘッダーを読み取ります。

   Source-Hash: {sha256 of codebase.json when guide was generated}
   Commit: {git commit when generated}
   Stats: {file count, function count, class count}
   

2. 現在の状態と比較します。

   • sha256sum .claude/codebase.json（または同等のコマンド）を実行します
   • git rev-parse HEAD を実行します
   • codebase.json から現在の統計情報を読み取ります

3. メタデータが一致する場合：ガイドは最新です。それでも再生成するか、ユーザーに確認します。

4. メタデータが一致しない、または欠落している場合：ガイドは古くなっています。再生成を進めます。

5. CODEBASE.md が存在しない場合：生成を進めます。

ステップ 2：リポジトリの種類を検出し、必要に応じて LSP をインストールする

Terraform/IaC リポジトリかどうかを確認します。

# Check for .tf files
find . -name "*.tf" -type f | head -1

Terraform ファイルが見つかった場合：

terraform-ls がインストールされているか確認します。インストールされていない場合は、解析精度を高めるためにインストールします。

# Check if terraform-ls exists
which terraform-ls || echo "NOT_INSTALLED"

NOT_INSTALLED の場合は、terraform-ls をインストールします：

# macOS (Homebrew)
brew install hashicorp/tap/terraform-ls

# Or via Go (cross-platform)
go install github.com/hashicorp/terraform-ls@latest

terraform-ls が重要な理由：

• 適切な HCL 解析（正規表現ではありません）
• 正確なモジュール解決
• ファイル間参照の追跡
• プロバイダースキーマの認識

インストールに失敗した場合、agentifind は正規表現による解析にフォールバックします（引き続き機能しますが、精度は下がります）。

ステップ 3：agentifind sync を実行する

CLI を実行してコード構造を抽出します。

npx agentifind@latest sync

抽出方法：

• まず LSP（利用可能な場合）：言語サーバーを使用して、ファイル間の参照を正確に解決します
  • Python：pyright-langserver（インストール：npm i -g pyright）
  • TypeScript：tsserver（TypeScript に同梱）
  • Terraform：terraform-ls（インストール：brew install hashicorp/tap/terraform-ls）
  • 注：大規模なコードベースでは、LSP による抽出に 5～15 分かかることがあります（参照グラフの構築）
• 正規表現／Tree-sitter によるフォールバック：LSP が利用できない場合の高速解析（約 30 秒）

次の情報を含む .claude/codebase.json が作成されます。

• モジュールのインポート／エクスポート
• 関数とクラスの定義
• 呼び出しグラフの関係（LSP を使用すると精度が向上します）
• インポートの依存関係

オプション：

• --skip-validate：リンティング／型チェックをスキップします（高速化）
• --verbose：抽出方法と進行状況を表示します
• --if-stale：ソースファイルに変更があった場合にのみ同期します

ステップ 4：.gitignore を更新する

生成されたファイルを .gitignore に追加します（まだ存在しない場合）。

# Agentifind generated files
.claude/codebase.json
.claude/CODEBASE.md
.claude/.agentifind-checksum

これらのファイルは次の性質があります。

• ソースコードから再生成可能
• サイズが大きい（codebase.json は数 MB になることがあります）
• マシン固有（パスが異なる場合があります）

ステップ 5：抽出したデータを読み取って分析する

.claude/codebase.json を読み取り、次の項目を分析します。

• stats：ファイル／関数／クラスの数
• modules：ファイルごとの構造（インポート、エクスポート、クラス、関数）
• call_graph：各関数が呼び出す関数
• import_graph：モジュールの依存関係
• analysis_gaps：呼び出しグラフの欠落（ステップ 6 を参照）
• validation：リンティング／型チェックの問題（存在する場合）

ステップ 6：解析の欠落を確認する

CLI は、動的パターンを示している可能性のある呼び出しグラフの欠落を自動的に検出します。codebase.json の analysis_gaps を読み取ります。

{
  "analysis_gaps": {
    "uncalled_exports": [...],  // Exported functions with no callers
    "unused_imports": [...],    // Imports never referenced
    "orphan_modules": [...]     // Files never imported
  }
}

欠落の解釈方法：

欠落の種類	意味	考えられる原因
uncalled_exports	エクスポートされた関数に、検出された呼び出し元がない	エントリーポイント、CLI コマンド、API ハンドラー、テストフィクスチャ、プラグインフック、シグナルレシーバー、デコレーターによる呼び出し
unused_imports	インポートがコード内で一度も参照されていない	副作用のあるインポート、再エクスポート、型専用のインポート、動的なアクセス
orphan_modules	どこからもインポートされていないファイル	エントリーポイント、スクリプト、設定ファイル、動的に読み込まれるプラグイン

重要なポイント： エクスポートされているのに呼び出されないものや、インポートされているのに使用されないものがある場合、静的解析では追跡できません。こうした箇所で、呼び出しグラフは不完全になります。

手動でのスキャンは不要です。CLI が呼び出しグラフの構造を分析して、自動的に処理します。

ステップ 7：主要なコンポーネントを特定する

データをもとに、次の項目を特定します。

• エントリポイント：インポーターが多いファイル（import_graph の reverse を確認）
• コアモジュール：エクスポート数が多く、インポートグラフの中心にあるモジュール
• ユーティリティ：多くのファイルからインポートされ、自身は少数のファイルのみをインポートするもの
• リクエストフロー：エントリから出力まで call_graph をたどる

ステップ 8：CODEBASE.md を作成する

まず、codebase.json の repo_type を確認します。

• repo_type が "terraform" の場合 → 以下のインフラストラクチャテンプレートを使用します
• repo_type がない場合、またはその他の値の場合 → 以下のアプリケーションテンプレートを使用します

---

アプリケーションテンプレート（デフォルト）

次の構成で .claude/CODEBASE.md を作成します。

# Codebase Guide




## ⚠️ Usage Instructions

This guide provides STARTING POINTS, not absolute truth.

**Before acting on any location:**
1. Verify the file exists with a quick Read
2. Confirm the symbol/function is still there
3. If something seems wrong, the guide may be stale - regenerate with `/agentifind`

**This guide CANNOT see:**
- Runtime behavior (dynamic imports, plugins, DI)
- Configuration-driven logic
- Database queries and their relationships
- External API integrations

## Quick Reference

| Component | Location |
|-----------|----------|
| {name} | `{path}` → `{symbol}` |

## Architecture

### Module Dependencies
{Key relationships from import_graph - focus on core modules}

### Data Flow
{Trace from call_graph if clear pattern exists}

## Analysis Gaps (Potential Dynamic Patterns)

{If analysis_gaps has items, list them here grouped by type}

### Uncalled Exports
{List from analysis_gaps.uncalled_exports - these are likely entry points, API handlers, or dynamically invoked}

| Symbol | File | Reason |
|--------|------|--------|
| {name} | `{file}:{line}` | {reason} |

### Orphan Modules
{List from analysis_gaps.orphan_modules - these are likely entry points or dynamically loaded}

| File | Reason |
|------|--------|
| `{file}` | {reason} |

**What this means:**
- Call graph is incomplete for these symbols/files
- They may be invoked via plugins, signals, decorators, CLI, or configuration
- Always trace execution manually when working in these areas
- Don't assume the call graph shows all callers

{If no gaps found, write: "No analysis gaps detected. Call graph appears complete."}

## Conventions
{Infer from naming patterns, file organization, directory structure}

## Impact Map

| If you change... | Also update... |
|------------------|----------------|
| `{high-dependency file}` | {N} dependent files |

## Known Issues
{From validation.linting/formatting/types if present, otherwise omit section}

---

インフラストラクチャテンプレート（Terraform/IaC リポジトリ用）

repo_type が "terraform" の場合、次の構成で .claude/CODEBASE.md を作成します。

# Infrastructure Guide




## ⚠️ Usage Instructions

This guide provides STARTING POINTS for infrastructure navigation.

**Before making changes:**
1. Verify the resource/module exists
2. Check the blast radius (what depends on this?)
3. Review variable dependencies
4. Consider state implications

**This guide CANNOT see:**
- Remote state data
- Dynamic values from data sources
- Provider-specific behaviors
- Secrets in tfvars files

## Infrastructure Overview

| Provider | Resources | Modules |
|----------|-----------|---------|
{For each provider in stats.providers, count resources}

## Module Structure

{List from modules array, show source and dependencies}

modules/ ├── {module.name}/ → {module.source} │ └── inputs: {list key variables}

## Resource Inventory

{Group resources by type from resources object}

### {Provider} Resources
| Type | Name | File | Dependencies |
|------|------|------|--------------|
| {type} | {name} | `{file}:{line}` | {dependencies.length} deps |

## Variable Flow

{List from variables array}

| Variable | Type | Used By | Default |
|----------|------|---------|---------|
| {name} | {type} | {used_by.length} resources | {default or "required"} |

## Blast Radius (High Risk)

{List from blast_radius where severity is "high" or "medium"}

⚠️ **Changing these resources affects many dependents:**

| Resource | Affected | Severity |
|----------|----------|----------|
| {target} | {affected_resources.length} resources | {severity} |

**Before modifying high-risk resources:**
- Run `terraform plan` to preview changes
- Consider using `terraform state mv` for refactoring
- Check if changes will force recreation

## Outputs

{List from outputs array}

| Output | Value | Referenced |
|--------|-------|------------|
| {name} | {value} | {references} |

## Dependency Graph

{Describe key relationships from dependency_graph}

Key dependencies:
- `{resource A}` → depends on → `{resource B}`

ステップ 9：完了を確認する

アプリケーションリポジトリの場合は、次の項目を報告します。

• 分析したファイル数（stats.files の値）
• 抽出したシンボル数（stats.functions + stats.classes の値）
• 使用した抽出方法（LSP または tree-sitter）
• 特定した主要なエントリポイント
• 検出された分析の不足箇所（uncalled_exports と orphan_modules の数）
• 見つかった検証上の問題
• 記録したガイドの古さに関するメタデータ

Terraform/IaC リポジトリの場合は、次の項目を報告します。

• 分析したファイル数（stats.files の値）
• 抽出したリソース数（stats.resources の値）
• 検出したモジュール数（stats.modules の値）
• 使用しているプロバイダー（stats.providers の値）
• 高リスクのリソース（severity が "high" の blast_radius の数）
• 定義された変数と使用された変数
• 記録したガイドの古さに関するメタデータ

ステップ 10：エージェントへの指示の更新を提案する

プロジェクトのルートに CLAUDE.md または AGENTS.md があるか確認します。

ユーザーに次のように尋ねます。

「エージェントがナビゲーションに CODEBASE.md を自動的に使用するよう、{CLAUDE.md/AGENTS.md} ファイルに指示を追加しますか？」

ユーザーが承諾した場合：

次のセクションをファイルに追記します（どちらも存在しない場合は AGENTS.md を作成します）。

## Codebase Navigation

Before exploring the codebase, read `.claude/CODEBASE.md` for architecture overview, key files, and conventions. This file is auto-generated by agentifind and provides:
- Quick reference to key components
- Module dependencies and data flow
- Dynamic patterns that static analysis can't trace
- Coding conventions
- Impact map for changes

**Important:** The guide provides starting points. Always verify locations before making changes.

CLAUDE.md と AGENTS.md の両方が存在する場合は、CLAUDE.md を更新します（こちらが優先されます）。

ユーザーが断った場合：

次のように応答します。

「問題ありません！気が変わった場合は、次の内容を CLAUDE.md または AGENTS.md ファイルに追加してください。」

## Codebase Navigation

Before exploring the codebase, read `.claude/CODEBASE.md` for architecture overview, key files, and conventions.

出力

.claude/
├── codebase.json         # Structured extraction (CLI output)
├── CODEBASE.md           # Navigation guide (this skill's output)
└── .agentifind-checksum  # Staleness detection

注記

• すべての記述は抽出したデータに基づかせ、関係性を捏造しないでください
• ガイドは簡潔に保ち、説明よりもナビゲーションを重視してください
• 「なぜ」や「どのように」よりも、「何」や「どこ」を優先してください
• codebase.json がすでに存在し、最新の場合は、ステップ 2 を省略してください
• LSP による抽出は遅くなりますが、ファイル間参照の精度が高くなります
• Tree-sitter は高速ですが、ヒューリスティックに基づいて解決します
• 必ず古さに関するメタデータヘッダーを含めてください。今後の鮮度チェックに使用されます
• 必ず分析の不足箇所のセクションを含めてください。該当するものがない場合も、呼び出しグラフが完全であることを記載してください