Back to Details

code-semantic-search

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Code Semantic Search

代码语义搜索

Overview

概述

Semantic code search using Phase 1 vector embeddings and Phase 2 hybrid search (semantic + structural). Find code by meaning, not just keywords.
Core principle: Search code by what it does, not what it's called.
使用第一阶段向量嵌入和第二阶段混合搜索（语义+结构）的语义代码搜索。根据代码的功能而非仅关键词查找代码。
核心原则： 根据代码的功能而非名称进行搜索。

Phase 2: Hybrid Search

第二阶段：混合搜索

This skill now supports three search modes:
  1. Hybrid (Default):
    • Combines semantic + structural search
    • Best accuracy (95%+)
    • Slightly slower but still <150ms
    • Recommended for all searches
  2. Semantic-Only:
    • Uses only Phase 1 semantic vectors
    • Fastest (<50ms)
    • Good for conceptual searches
    • Use when structure doesn't matter
  3. Structural-Only:
    • Uses only ast-grep patterns
    • Precise for exact matches
    • Best for finding function/class definitions
    • Use when you need exact structural patterns
该Skill现在支持三种搜索模式：
  1. 混合模式（默认）：
    • 结合语义+结构搜索
    • 准确率最高（95%+）
    • 速度稍慢但仍<150ms
    • 推荐用于所有搜索场景
  2. 仅语义模式：
    • 仅使用第一阶段语义向量
    • 速度最快（<50ms）
    • 适合概念性搜索
    • 当代码结构不重要时使用
  3. 仅结构模式：
    • 仅使用ast-grep模式
    • 精确匹配
    • 最适合查找函数/类定义
    • 当需要精确结构模式时使用

Performance Comparison

性能对比

ModeSpeedAccuracyBest For
Hybrid<150ms95%General search
Semantic-only<50ms85%Concepts
Structural-only<50ms100%Exact patterns
Phase 1 only<50ms80%Legacy (fallback)
模式速度准确率最佳适用场景
混合模式<150ms95%通用搜索
仅语义模式<50ms85%概念性搜索
仅结构模式<50ms100%精确模式匹配
仅第一阶段模式<50ms80%遗留模式（降级方案）

When to Use

使用场景

Always:
  • Finding authentication logic without knowing function names
  • Searching for error handling patterns
  • Locating database queries
  • Finding similar code to a concept
  • Discovering implementation patterns
Don't Use:
  • Exact text matching (use Grep instead)
  • File name searches (use Glob instead)
  • Simple keyword searches (use ripgrep instead)
推荐使用场景：
  • 在不知道函数名称的情况下查找认证逻辑
  • 搜索错误处理模式
  • 定位数据库查询代码
  • 查找与某一概念相似的代码
  • 发现实现模式
不推荐使用场景：
  • 精确文本匹配（使用Grep替代）
  • 文件名搜索（使用Glob替代）
  • 简单关键词搜索（使用ripgrep替代）

Usage Examples

使用示例

Hybrid Search (Recommended)

混合搜索（推荐）

javascript
// Basic hybrid search
Skill({ skill: 'code-semantic-search', args: 'find authentication logic' });

// With options
Skill({
  skill: 'code-semantic-search',
  args: 'database queries',
  options: {
    mode: 'hybrid',
    language: 'javascript',
    limit: 10,
  },
});
javascript
// Basic hybrid search
Skill({ skill: 'code-semantic-search', args: 'find authentication logic' });

// With options
Skill({
  skill: 'code-semantic-search',
  args: 'database queries',
  options: {
    mode: 'hybrid',
    language: 'javascript',
    limit: 10,
  },
});

Semantic-Only Search

仅语义搜索

javascript
// Fast conceptual search
Skill({
  skill: 'code-semantic-search',
  args: 'find authentication',
  options: { mode: 'semantic-only' },
});
javascript
// Fast conceptual search
Skill({
  skill: 'code-semantic-search',
  args: 'find authentication',
  options: { mode: 'semantic-only' },
});

Structural-Only Search

仅结构搜索

javascript
// Exact pattern matching
Skill({
  skill: 'code-semantic-search',
  args: 'find function authenticate',
  options: { mode: 'structural-only' },
});
javascript
// Exact pattern matching
Skill({
  skill: 'code-semantic-search',
  args: 'find function authenticate',
  options: { mode: 'structural-only' },
});

Implementation Reference

实现参考

Hybrid Search: 
.claude/lib/code-indexing/hybrid-search.cjs
Query Analysis: 
.claude/lib/code-indexing/query-analyzer.cjs
Result Ranking: 
.claude/lib/code-indexing/result-ranker.cjs
混合搜索： 
.claude/lib/code-indexing/hybrid-search.cjs
查询分析： 
.claude/lib/code-indexing/query-analyzer.cjs
结果排序： 
.claude/lib/code-indexing/result-ranker.cjs

Integration Points

集成场景

  • developer: Code exploration, implementation discovery
  • architect: System understanding, pattern analysis
  • code-reviewer: Finding similar patterns, consistency checks
  • reverse-engineer: Understanding unfamiliar codebases
  • researcher: Research existing implementations
  • 开发者： 代码探索、实现方案发现
  • 架构师： 系统理解、模式分析
  • 代码审核者： 查找相似模式、一致性检查
  • 逆向工程师： 理解陌生代码库
  • 研究者： 研究现有实现方案

Memory Protocol (MANDATORY)

内存协议（强制要求）

Before starting: Read 
.claude/context/memory/learnings.md
After completing:
  • New pattern -> 
    .claude/context/memory/learnings.md
  • Issue found -> 
    .claude/context/memory/issues.md
  • Decision made -> 
    .claude/context/memory/decisions.md
ASSUME INTERRUPTION: If it's not in memory, it didn't happen.
开始前： 阅读 
.claude/context/memory/learnings.md
完成后：
  • 新发现的模式 -> 
    .claude/context/memory/learnings.md
  • 发现的问题 -> 
    .claude/context/memory/issues.md
  • 做出的决策 -> 
    .claude/context/memory/decisions.md
假设可能中断：如果未记录到内存中，则视为未发生。