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（而非使用正则表达式）
• 准确解析模块
• 追踪跨文件引用
• 感知 Provider 架构

如果安装失败，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：跳过 lint/类型检查（速度更快）
• --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：lint/类型问题（如果存在）

步骤 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 的反向关系）
• 核心模块：导出数量多，且在导入图中处于中心位置
• 实用工具：被许多文件导入，但自身导入较少
• 请求流：从入口到输出追踪 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）
• 高风险资源（blast_radius 中 severity 为 "high" 的数量）
• 已定义与已使用的变量
• 已记录指南过时状态元数据

第 10 步：提出更新 Agent 指令

检查项目根目录中是否存在 CLAUDE.md 或 AGENTS.md。

询问用户：

“要不要我在你的 {CLAUDE.md/AGENTS.md} 文件中添加一条指令，让 Agent 自动使用 CODEBASE.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 文件中：”

## 代码库导航

在探索代码库之前，请先阅读 `.claude/CODEBASE.md`，了解架构概览、关键文件和约定。

输出

.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 速度较快，但使用基于启发式的方法进行解析
• 始终包含过时状态元数据标题——这有助于未来检查内容是否仍然新鲜
• 始终包含分析缺口部分——即使没有缺口，也要记录调用图是完整的