find-similar-functions

類似関数の検索

既存のヘルパーと重複する可能性のある JavaScript または TypeScript のコードを書く前に、このスキルを使用してください。目的は、重複する動作を新たに作るのではなく、再利用または拡張できるよう、関連する関数、メソッド、定数、型、インターフェースを早い段階で見つけることです。

truffler は、あいまい検索に対応したシンボル検索ツールです。探索レイヤーとして使ってください。再利用できそうなシンボルを提示しますが、再利用できるかどうかを判断する前に、コードを確認する必要があります。

ワークフロー

1. 実装しようとしている動作を、数語で説明します。
2. 実装する動作から、検索クエリを 3～6 個作成します。
   • 提案する関数名またはクラス名
   • symbol、path、file、route、token、config などのドメイン名詞
   • parse、normalize、discover、scan、format、rank、score、resolve、validate などの動詞
   • button の btn、config の cfg など、一般的な略語や同義語
3. まず最も関連性の高いルートで truffler を実行し、必要に応じて範囲を広げます。
4. 編集する前に、通常のコード閲覧ツールで上位の検索結果を確認します。
5. 動作が大きく一致する既存コードは、再利用、拡張、または移動を優先します。適切な既存シンボルがないことを検索で確認してから、新しいコードを作成します。
6. 最終回答では、見つかったものと、それを再利用したか、意図的に新しい実装を追加したかを簡潔に述べます。

コマンド例

対象プロジェクトに truffler がインストールされている場合：

truffler "normalize path" src --kind function,method,constant,type --limit 20
truffler "score" src --kind function,method --format json --limit 15

この truffler リポジトリ内で作業する場合：

bun src/cli.ts "discover file" src --kind function,method,constant,type --limit 20
bun src/cli.ts "format result" src --kind function,method --format json --limit 15

プロジェクトにバイナリがインストールされておらず、依存関係を追加すべきでない場合は、環境でネットワークやパッケージの実行が許可されていれば bunx を使用します。

bunx @rayhanadev/truffler "parse config" src --kind function,method,type --limit 20

truffler を実行できない場合は、その旨を伝え、リポジトリで利用できる検索ツールに切り替えてください。実装前に検索するという、同じ重複回避の方針に従ってください。

検索戦略

再利用可能な動作を表している可能性が最も高いシンボルから検索を始めます。

truffler "<query>" <root> --kind function,method,constant,type,interface --limit 20

ランキング、場所、シグネチャ、自動化のために構造化フィールドが必要な場合は、JSON 出力を使用します。

truffler "<query>" <root> --format json --limit 20

意図的に検索範囲を広げます。

• 具体的な関数名で一致しない場合は、ドメイン名詞と動詞を別々に検索します。
• ユーティリティが src/ 以外にある可能性がある場合は、既知のライブラリ、パッケージ、アプリ、テストのルートも試します。
• 検索結果が多い場合は、関係のない結果を流し読みせず、--kind を限定してルートを絞ります。
• 上位の検索結果が近そうな場合は、判断する前に実装と関連するテストまたは呼び出し箇所を確認します。

再利用の判断ガイド

既存のシンボルが同じ入力形式、副作用、エラー処理、戻り値の形式に対応している場合、または小さな拡張で現在の契約を維持できる場合は、再利用を検討してください。

名前が似ているという理由だけでシンボルを再利用するのは避けてください。あいまい検索では無関係なコードが見つかることがあります。変更する前に、シグネチャ、実装、呼び出し元、テストを確認してください。

適切なシンボルがない場合は、関連する最も近いモジュールの近くに新しい実装を置き、そのモジュールの命名規則、エラー処理、テストのスタイルに合わせます。

報告テンプレート

検索結果が実装に影響した場合は、次のような短いメモを使用してください。

I checked for existing symbols with `truffler` using queries like `normalize`, `path`, and `resolve`. The closest match was `normalizePath` in `src/files.ts`, so I reused that behavior instead of adding a separate helper.

関連するものが見つからなかった場合：

I searched with `truffler` for `parse`, `config`, and `loadConfig` across `src/`; the matches were unrelated, so I added a new helper in the nearest module.