---
name: search
user-invocable: false
description: >
  リポジトリまたはディレクトリのファイル属性と内容を検索する直前に起動する。
---

# 検索手段の選定と出力量の制御

本スキルはファイル属性と内容の検索手段の選定および検索の出力量の制御を提供する。

検索手段は対象の性質から次の順で決める。

1. ファイル名、種類、更新時刻およびディレクトリ構造などの属性探索は、対象を限定した`find`を使う
2. 現在のGit作業ツリー内の管理対象に限定した内容検索と追跡ファイル全体の残存確認は`git grep`を使う
3. 現在のGit作業ツリー外の明示パス、Git管理外の対象、正規表現を使う内容検索および除外設定に従う内容検索には`rg`を使う。作業ツリー外の明示パスが別のGitリポジトリに属する場合も`rg`を選ぶ。隠し対象を母集団に含める場合は`--hidden`を付ける
4. 除外設定を反映したファイル一覧は`rg --files`、構造化した集計と全体件数の上限を要する検索はMCPまたはCLIの`pyfltr grep`等を使う

利用中のホストで手段を利用できない場合も同じ対象性質から代替を選ぶ。
`rg`と`git grep`のいずれかを利用できる場合は、再帰内容検索にその手段を使う。双方を利用できない場合は、`--include`・`--exclude`・`--exclude-dir`で対象を限定した`grep`を用い、出力先ファイルへ保存してから必要な範囲だけを読む。

`git grep`では、固定文字列の`-F`、拡張正規表現の`-E`またはPerl互換正規表現の`-P`を検索意図に応じて明示する。
オプション、pattern、`--`、pathspecの順で引数を置き、patternの解釈を明示したオプションで固定して、`grep.patternType`などのホスト設定から独立させる。
grepとrgの単語境界指定（`-w`・`\b`）は日本語文字を単語構成文字として扱い（GNU grepでは日本語ロケールの場合）、日本語に隣接する英単語へ一致しない。日本語文書の語検索では単語境界指定を使わず、必要な境界はパターン側で表現する。
`grep.lineNumber=true`の下で`-h`を指定しても行番号が残り、`--no-line-number`で抑止される。観測結果は`docs/development/audit-records.md`の「agent-toolkit/rules/02-agent-operations.md：ツール・コマンド運用：2026年9月14日」にある。
Git作業ツリー外のファイルから秘匿値と見られる値の有無、件数、所在、同一性を調べる検索は、`agent-toolkit:secret-files`が定める値を出力しない形で行う。

出力をパイプで後段へ渡す場合は、`pipefail`その他の実行シェルが公式に提供する仕組みで全段の終了状態を取得し、前段の失敗を後段の成功で上書きしない。
`rg`は一致0件を終了コード1で返し、対象パスの不在と引数の誤りを終了コード2と標準エラーで返す。標準エラーを保持すると、一致0件と検索の失敗を見分けられる。`git grep`は一致しないpathspecにも一致0件と同じ終了コード1を返すため、推測したパスやglobを渡す前に`git ls-files`か`rg --files`で実在を確かめる。

コーディングエージェントがリポジトリまたはディレクトリ全体を対象として内容検索する場合は、最初の取得を件数、ファイル名または要約にする（努力目標。一致本文を先に直列化するとコンテキストを消費する）。
検索ツールが提供する件数、ファイル名、要約、出力上限の指定で候補と出力量を先に確認し、必要な候補ファイル、パターン、
ファイルサイズおよび行長へ限定してから本文を取得する。現在のGit作業ツリー内の管理対象では`git grep -l`または`git grep -c`、通常の正規表現検索では
`rg -l`か`rg -c`、構造化した上限と要約を扱える場合は`pyfltr grep`を優先する。
`git grep -c`と`rg -c`が返す値は一致した行の数である。関数、hookなどの実体数として採用する前に、対象の1実体と1一致行が対応することを構造から確認する。定義、import、参照、コメントが混在する場合は実体の境界を読んで数える。出力量の見積もりには一致行数を直接用いる。
利用中のpyfltrがエージェント環境向けの出力量連動要約を提供しない場合は、`summary_mode`、`max_total`、`max_count`および`max_filesize`を明示する。
ファイルサイズと行長の制御には`rg`の`--max-filesize`と`--max-columns`などを使う。
広域検索で巨大な単一行または大量の一致本文を先に直列化すると、結果を限定する前に実行主体のコンテキストを消費する。依存環境、source map、minifiedファイル、生成物に含まれる単一の巨大な行は、一致件数が少なくても同じ消費を起こす。

コードベースの通常の検索はリポジトリrootから実行し、`.gitignore`と各ツール固有の除外を維持する。
除外された対象そのものを調べる要件がある場合だけ範囲を広げる。
ディレクトリまたはglobで対象パスを狭めるのは、探す対象がその範囲にしか存在しないことを別の観測で確定した場合に限る。
見込みで範囲を狭めると、範囲外の一致を検出しないまま結論が確定し、同じ値や文言、識別子などを保持する箇所の一部が未修正で残る。
依存環境と生成物は`.gitignore`とツール固有の除外が母集団から外すため、root全体を対象にしても、その分の出力量は増えずに済む。
除外を持たない手段で広い範囲を走査する場合は、`find`の`-prune`などで対象集合を先に限定する。

網羅性を要する検索では出力量の制御で本文を省かず、分離したコンテキストで実行して要約だけを受け取る。
出力量の制御により走査または本文が省略された結果は、`agent-toolkit/rules/02-agent-operations.md`の切り詰められた出力に関する規定と同じ扱いとする。