grepai-search-boosting

GrepAI の検索ブースト

このスキルでは、関連するコードパスの優先度を上げ、テスト、ドキュメント、ベンダーコードの優先度を下げるスコアブーストの設定について説明します。

このスキルを使う場面

• テストよりソースコードを優先する
• ベンダーコード／サードパーティーコードにペナルティを設定する
• 重要なディレクトリをブーストする
• 検索結果のランキングをカスタマイズする

ブーストとは？

ブーストは、ファイルパスに基づいて検索スコアを変更します。

Original score: 0.85 (src/auth.go)
Bonus (+10%):   0.935

Original score: 0.85 (tests/auth_test.go)
Penalty (-50%): 0.425

これにより、内容が似ている場合でも、本番コードがテストより上位に表示されます。

設定

基本設定

# .grepai/config.yaml
search:
  boost:
    enabled: true
    penalties:
      - pattern: /tests/
        factor: 0.5
    bonuses:
      - pattern: /src/
        factor: 1.1

全設定

search:
  boost:
    enabled: true

    # Reduce scores (factor < 1.0)
    penalties:
      # Test files
      - pattern: /tests/
        factor: 0.5
      - pattern: /__tests__/
        factor: 0.5
      - pattern: _test.
        factor: 0.5
      - pattern: .spec.
        factor: 0.5
      - pattern: .test.
        factor: 0.5

      # Documentation
      - pattern: /docs/
        factor: 0.6
      - pattern: /documentation/
        factor: 0.6

      # Vendor/third-party
      - pattern: /vendor/
        factor: 0.3
      - pattern: /node_modules/
        factor: 0.3
      - pattern: /third_party/
        factor: 0.3

      # Generated code
      - pattern: /generated/
        factor: 0.4
      - pattern: .gen.
        factor: 0.4
      - pattern: .pb.go
        factor: 0.4

      # Examples and samples
      - pattern: /examples/
        factor: 0.7
      - pattern: /samples/
        factor: 0.7

    # Increase scores (factor > 1.0)
    bonuses:
      # Core source code
      - pattern: /src/
        factor: 1.1
      - pattern: /lib/
        factor: 1.1
      - pattern: /app/
        factor: 1.1
      - pattern: /core/
        factor: 1.2
      - pattern: /internal/
        factor: 1.1

      # Important directories
      - pattern: /services/
        factor: 1.1
      - pattern: /handlers/
        factor: 1.1
      - pattern: /controllers/
        factor: 1.1

係数の仕組み

係数	効果	使用例
0.3	70％減少	強いペナルティ（ベンダー）
0.5	50％減少	中程度のペナルティ（テスト）
0.7	30％減少	軽いペナルティ（サンプル）
1.0	変化なし	中立
1.1	10％増加	軽いブースト（src）
1.2	20％増加	中程度のブースト（core）
1.5	50％増加	強いブースト

パターンマッチング

パターンはファイルパス全体に対してマッチします。

/project/src/auth/middleware.go
         ^^^^
         Matches "/src/" pattern

パターンの種類

パターン	マッチする	マッチしない
/tests/	src/tests/auth.go	tests.go
_test.	auth_test.go	test_auth.go
.spec.	auth.spec.ts	spec/auth.ts
/src/	project/src/main.go	resource/file.go

ランキングへの影響

ブーストなし

Score: 0.85 | tests/auth_test.go:10-30
Score: 0.82 | src/auth/middleware.go:15-45
Score: 0.80 | src/auth/jwt.go:23-55

ブーストあり

penalties:
  - pattern: /tests/
    factor: 0.5
bonuses:
  - pattern: /src/
    factor: 1.1

Score: 0.90 | src/auth/middleware.go:15-45  (0.82 × 1.1)
Score: 0.88 | src/auth/jwt.go:23-55        (0.80 × 1.1)
Score: 0.43 | tests/auth_test.go:10-30     (0.85 × 0.5)

よく使われる設定

標準（推奨）

search:
  boost:
    enabled: true
    penalties:
      - pattern: /tests/
        factor: 0.5
      - pattern: _test.
        factor: 0.5
      - pattern: .spec.
        factor: 0.5
      - pattern: /vendor/
        factor: 0.3
      - pattern: /docs/
        factor: 0.6
    bonuses:
      - pattern: /src/
        factor: 1.1
      - pattern: /lib/
        factor: 1.1

フロントエンドプロジェクト

search:
  boost:
    enabled: true
    penalties:
      - pattern: /__tests__/
        factor: 0.5
      - pattern: .test.
        factor: 0.5
      - pattern: .spec.
        factor: 0.5
      - pattern: /node_modules/
        factor: 0.3
      - pattern: .stories.
        factor: 0.6
      - pattern: /storybook/
        factor: 0.6
    bonuses:
      - pattern: /src/
        factor: 1.1
      - pattern: /components/
        factor: 1.1
      - pattern: /hooks/
        factor: 1.1

Go プロジェクト

search:
  boost:
    enabled: true
    penalties:
      - pattern: _test.go
        factor: 0.5
      - pattern: _mock.go
        factor: 0.5
      - pattern: /testdata/
        factor: 0.5
      - pattern: /vendor/
        factor: 0.3
      - pattern: .pb.go
        factor: 0.4
    bonuses:
      - pattern: /internal/
        factor: 1.1
      - pattern: /cmd/
        factor: 1.1
      - pattern: /pkg/
        factor: 1.1

Python プロジェクト

search:
  boost:
    enabled: true
    penalties:
      - pattern: /tests/
        factor: 0.5
      - pattern: test_
        factor: 0.5
      - pattern: _test.py
        factor: 0.5
      - pattern: /conftest
        factor: 0.5
      - pattern: /fixtures/
        factor: 0.6
    bonuses:
      - pattern: /src/
        factor: 1.1
      - pattern: /app/
        factor: 1.1
      - pattern: /core/
        factor: 1.2

モノレポ

search:
  boost:
    enabled: true
    penalties:
      - pattern: /tests/
        factor: 0.5
      - pattern: _test.
        factor: 0.5
      - pattern: /packages/deprecated/
        factor: 0.3
      - pattern: /packages/legacy/
        factor: 0.4
    bonuses:
      - pattern: /packages/core/
        factor: 1.2
      - pattern: /packages/api/
        factor: 1.1
      - pattern: /packages/shared/
        factor: 1.1

ブーストを無効にする

ブーストを完全に無効にするには、次のようにします。

search:
  boost:
    enabled: false

または、設定から boost セクションを削除します。

ブーストと無視の違い

方法	効果	使用例
無視	完全に除外	依存関係、ビルド出力
ペナルティ	検索可能なまま、順位を下げる	テスト、ドキュメント、サンプル
中立	デフォルトのランキング	通常のソースコード
ボーナス	順位を上げる	コアビジネスロジック

無視とペナルティの使い分け

• 無視： 検索対象にしたくないファイル（node_modules、.git）
• ペナルティ： ほとんど検索しないものの、必要になる場合があるファイル（tests、docs）

設定をテストする

ブーストを設定した後、次のようにします。

# Search and observe rankings
grepai search "authentication"

# Check if tests are properly deprioritized
grepai search "test authentication"  # Should still find tests, but ranked lower

ベストプラクティス

1. ペナルティから始める： まずテスト／ベンダーの優先度を下げます
2. ボーナスは控えめに追加する： 本当に重要なパスにのみ適用します
3. 実際のクエリでテストする： 結果が妥当であることを確認します
4. ペナルティを強くしすぎない： テストには通常 0.5 で十分です
5. 選択理由を記録する： 設定にコメントを追加します

よくある問題

❌ 問題： テストが常に最初に表示される
✅ 解決策： テストの命名規則に合ったパターンを追加してペナルティを設定します

❌ 問題： ペナルティ対象のパスにあるコードが見つからない
✅ 解決策： ペナルティは順位を下げますが、非表示にはしません。完全に除外するには ignore を使います。

❌ 問題： 1.0 を超えるスコアがおかしいように見える
✅ 解決策： ボーナスによってスコアが 1.0 を超えることがあります。これは正常です。

❌ 問題： パターンがマッチしない
✅ 解決策： パターンがパス全体に含まれていることを確認します（tests だけでなく /tests/ を使います）。

出力形式

ブースト設定のステータス：

✅ Search Boosting Configured

   Status: Enabled

   Penalties (5):
   - /tests/      → 0.5 (50% reduction)
   - _test.       → 0.5
   - .spec.       → 0.5
   - /vendor/     → 0.3 (70% reduction)
   - /docs/       → 0.6

   Bonuses (3):
   - /src/        → 1.1 (10% boost)
   - /lib/        → 1.1
   - /core/       → 1.2 (20% boost)

   Effect: Source code ranks higher than tests with similar content