# index1 + Claude Code 搜索协作策略

## 核心原则

index1 和 Claude Code 原生工具（Grep/Glob）**互补使用**，不是二选一。

```
index1  = 语义雷达（先扫描方向）
Grep    = 精确制导（再定位代码）
```

## 推荐工作流

### 流程一：语义先行（推荐，适合大多数场景）

```
用户提问
    │
    ▼
① index1 docs_search（语义搜索，~100ms，~460 tokens）
    │  → 返回 top-5 相关文件和代码片段
    │  → 确定"在哪个文件、哪个模块"
    │
    ▼
② Grep/Glob（精确定位，~4ms，~100 tokens）
    │  → 在 ① 找到的文件里精确搜索
    │  → 获取具体行号和上下文
    │
    ▼
③ Read（读取代码，按需）
    → 读取相关函数/类的完整代码
```

**示例**：

```
用户: "搜索功能是怎么实现的？"

① index1: docs_search("搜索是怎么实现的")
   → search.py, db.py, indexer.py 是核心文件

② Grep: 在 search.py 里搜 "async def search"
   → search.py:97 找到入口函数

③ Read: 读取 search.py:97-200
   → 完整理解搜索实现逻辑
```

**消耗**：~460 + ~100 = **~560 tokens**
**对比纯 Grep**：搜 "search" 全项目 = **~35,895 tokens**（节省 98%）

### 流程二：精确直达（适合已知标识符）

```
用户提问（包含具体函数名/类名/文件名）
    │
    ▼
直接 Grep/Glob（~4ms）
    → 精确匹配，无需语义搜索
```

**示例**：

```
用户: "_has_cjk 函数在哪？"

直接 Grep: "_has_cjk"
→ search.py:52  精确命中
```

### 流程三：跨语言查询（必须用 index1）

```
中文提问 → 英文代码
    │
    ▼
只有 index1 能做（Grep 不支持跨语言）
```

**示例**：

```
用户: "向量搜索怎么做的？"

index1: docs_search("向量搜索怎么做的")
→ embed.py（向量生成）, db.py:vector_search（向量查询）, search.py（融合排序）
```

## 决策速查表

| 场景 | 先用什么 | 再用什么 | 原因 |
|------|---------|---------|------|
| "XXX 功能怎么实现的" | index1 | Grep | 语义定位 → 精确查找 |
| "class Foo 在哪" | Grep | — | 已知标识符，直接查 |
| "import bar" | Grep | — | 精确字符串匹配 |
| "中文问题查英文代码" | index1 | Grep | 只有 index1 支持跨语言 |
| "这个模块的作用" | index1 | Read | 理解性查询 |
| "*.py 有哪些文件" | Glob | — | 文件模式匹配 |
| 高频关键词（search, config） | index1 | Grep | Grep 返回太多，浪费上下文 |
| 低频关键词（_rrf_fusion） | Grep | — | 匹配行少，Grep 更快 |

## 实际效果对比

以 index1 项目自身为例（45 文档, 17,725 chunks）：

| 方法 | 查 "搜索怎么实现" | 上下文消耗 | 准确度 |
|------|-----------------|-----------|--------|
| 纯 Grep | 搜 "search" → 881 行 | ~35,895 tokens | 低（大量噪声） |
| 纯 index1 | 5 条结果 | ~460 tokens | 中（方向对，不够精确） |
| **index1 → Grep** | 5 条定位 → 精确搜索 | **~560 tokens** | **高（方向+精度）** |

## 对 Claude Code 项目的配置建议

在项目的 `.claude/CLAUDE.md` 中添加以下指引，让 Claude Code 自动遵循搜索策略：

```markdown
## 搜索策略

本项目已配置 index1 MCP Server（docs_search 等 5 个工具）。

搜索代码时遵循以下优先级：
1. 已知函数名/类名/文件名 → 直接 Grep/Glob
2. 探索性/理解性问题 → 先 index1 docs_search 定位方向，再 Grep 精确查找
3. 中文查英文代码 → 必须用 index1 docs_search
4. 高频关键词（匹配 > 50 行） → 优先 index1（节省上下文）
```
