grepai-search-basics

GrepAI 検索の基本

このスキルでは、GrepAI によるセマンティックコード検索の基本を説明します。

このスキルを使う場面

• GrepAI 検索を学ぶ
• 基本的なコード検索を行う
• セマンティック検索とテキスト検索の違いを理解する
• 検索結果を解釈する

前提条件

1. GrepAI が初期化されている（grepai init）
2. インデックスが作成されている（grepai watch）
3. 埋め込みプロバイダーが実行中である（Ollama など）

セマンティック検索とは？

従来のテキスト検索（grep、ripgrep）とは異なり、GrepAI は意味に基づいて検索します。

種類	仕組み	例
テキスト検索	文字列の完全一致	"login" → "login" を検索
セマンティック検索	意味の類似性	"authenticate user" → login、auth、signin のコードを検索

基本的な検索コマンド

grepai search "your query here"

例

grepai search "user authentication flow"

出力：

Score: 0.89 | src/auth/middleware.go:15-45
──────────────────────────────────────────
func AuthMiddleware() gin.HandlerFunc {
    return func(c *gin.Context) {
        token := c.GetHeader("Authorization")
        if token == "" {
            c.AbortWithStatus(401)
            return
        }
        claims, err := ValidateToken(token)
        if err != nil {
            c.AbortWithStatus(401)
            return
        }
        c.Set("user", claims.UserID)
        c.Next()
    }
}

Score: 0.82 | src/auth/jwt.go:23-55
──────────────────────────────────────────
func ValidateToken(tokenString string) (*Claims, error) {
    token, err := jwt.Parse(tokenString, func(t *jwt.Token) (interface{}, error) {
        return []byte(secretKey), nil
    })
    if err != nil {
        return nil, err
    }
    if claims, ok := token.Claims.(*Claims); ok && token.Valid {
        return claims, nil
    }
    return nil, errors.New("invalid token")
}

Score: 0.76 | src/handlers/login.go:10-35
──────────────────────────────────────────
func HandleLogin(c *gin.Context) {
    var req LoginRequest
    if err := c.ShouldBindJSON(&req); err != nil {
        c.JSON(400, gin.H{"error": "invalid request"})
        return
    }
    user, err := userService.Authenticate(req.Email, req.Password)
    // ...
}

検索結果の見方

結果の形式

Score: 0.89 | src/auth/middleware.go:15-45
──────────────────────────────────────────
[code content]

項目	意味
スコア	類似度（0.0～1.0。値が大きいほど関連性が高い）
ファイルパス	コードの場所
行番号	チャンクの開始行と終了行
内容	実際のコード

スコアの解釈

スコア	意味
0.90+	非常に一致度が高い
0.80-0.89	一致度が高い
0.70-0.79	関連あり
0.60-0.69	関連性が低い
<0.60	一致度が低い

結果数の制限

デフォルトでは、GrepAI は10件の結果を返します。--limit で調整できます。

# Get only top 3 results
grepai search "database queries" --limit 3

# Get more results
grepai search "error handling" --limit 20

インデックスの状態確認

検索する前に、インデックスを確認します。

grepai status

出力：

✅ GrepAI Status

   Index:
   - Files: 245
   - Chunks: 1,234
   - Last updated: 2 minutes ago

   Ready for search.

検索と grep の比較

従来の grep

grep -r "authenticate" .

• テキスト「authenticate」と完全一致するものを検索する
• 同義語（login、signin、auth）は見つからない
• 一致したものを順位付けせずにすべて返す

GrepAI 検索

grepai search "authenticate user credentials"

• 意味的に類似したコードを検索する
• 関連する概念も含める
• 関連性の高い順に結果を並べる

適切なクエリとは

適切なクエリ ✅

意図や動作を説明します。

grepai search "validate user credentials"
grepai search "handle HTTP request errors"
grepai search "connect to the database"
grepai search "send email notification"
grepai search "parse JSON configuration"

効果の低いクエリ ❌

短すぎる、または一般的すぎるものです。

grepai search "auth"           # Too vague
grepai search "function"       # Too generic
grepai search "getUserById"    # Exact name (use grep)

自然言語でのクエリ

GrepAI は自然言語を理解します。

# Ask questions
grepai search "how are users authenticated"
grepai search "where is the database connection configured"

# Describe behavior
grepai search "code that sends emails to users"
grepai search "functions that validate input data"

複数の単語とフレーズ

どちらも使えますが、フレーズのほうが良い結果を得られることがよくあります。

# Multiple words (OR-like behavior)
grepai search "login password validation"

# Phrase (describes specific intent)
grepai search "validate user login credentials"

すぐに使えるヒント

1. 英語を使う： モデルは英語でトレーニングされています
2. 具体的にする： 「validation」よりも「JWT token validation」
3. 意図を説明する： コードの呼び名ではなく、コードが行うことを説明する
4. 3～7語を使う： 十分なコンテキストを含めつつ、冗長にならないようにする
5. 繰り返し調整する： 結果に基づいてクエリを改善する

よく使う検索パターン

エントリーポイントを見つける

grepai search "main entry point"
grepai search "application startup"
grepai search "HTTP server initialization"

エラー処理を見つける

grepai search "error handling and logging"
grepai search "exception handling"
grepai search "error response to client"

データアクセスを見つける

grepai search "database query execution"
grepai search "fetch user from database"
grepai search "save data to storage"

ビジネスロジックを見つける

grepai search "calculate order total"
grepai search "process payment transaction"
grepai search "validate business rules"

トラブルシューティング

❌ 問題： 結果が見つからない ✅ 解決策：

• インデックスが存在するか確認します：grepai status
• インデックスが空の場合は grepai watch を実行します
• クエリを簡潔にします

❌ 問題： 関連性のない結果が表示される ✅ 解決策：

• より具体的にします
• 別の単語を使います
• コードベースにコードが存在するか確認します

❌ 問題： 想定したコードが見つからない ✅ 解決策：

• ファイルが設定で無視されていないか確認します
• ファイル拡張子がサポートされていることを確認します
• インデックスを再作成します：rm .grepai/index.gob && grepai watch

出力形式

基本検索が成功した場合：

Query: "user authentication flow"
Results: 5 matches

Score: 0.89 | src/auth/middleware.go:15-45
──────────────────────────────────────────
[relevant code...]

Score: 0.82 | src/auth/jwt.go:23-55
──────────────────────────────────────────
[relevant code...]

[additional results...]

Tip: Use --limit to adjust number of results
     Use --json for machine-readable output