# AGENTS.md
## 言語
ユーザーとのやり取りは日本語で行うこと。
このリポジトリで作成・編集するドキュメントも、原則として日本語で書くこと。対象ファイルの性質上、英語が自然な場合に限り英語を使ってよいが、その場合も判断理由が分かるようにすること。
ソースコード中の識別子、CLIオプション、エラーメッセージ、公開パッケージ名などは、通常の慣習に従って英語でよい。
## プロジェクトの目的
このリポジトリでは、コーディングエージェント向けの安全な検索CLIと、それを使うためのSkillsを開発する。
詳細な目的、制約、非目標は次のファイルを正とする。
* `docs/goals_and_condition.md`
設計や実装で迷った場合は、まずこのファイルを確認すること。AGENTS.mdには詳細仕様を重複して書かないこと。
## 作業方針
最初の実装は、小さく、堅牢で、検証しやすいものにすること。
大きな設計を先に作り込みすぎない。まずは最小限のCLI、最小限のSkill、最小限のテストをそろえ、そこから反復的に改善すること。
複雑な作業では、編集前にリポジトリ構成と既存ドキュメントを確認し、簡潔な作業計画を立てること。
## TDD・検証方針
このプロジェクトでは、CLIの挙動をできるだけテストで固定すること。
特に次の性質は、実装前または実装と同時にテストを追加すること。
* 出力行数や出力サイズが上限を超えないこと
* ヒットが多すぎる場合に全文を表示せず、要約や絞り込み要求に切り替わること
* `scout`、`sample`、`terms`、`count`、`show` の基本的な挙動
* `.git`、`target`、ログ、JSONL/XML、生成物、scratch領域などのノイズを既定で避けること
* エージェントが読んでも安全な、短く決定的な出力になること
ただし、探索中の試作まで厳密なTDDを要求しない。ユーザー価値の大きい挙動や、後から壊れやすい境界条件を優先してテストすること。
## 検索と出力の規律
このプロジェクト自体が、広域検索によるトークン浪費を防ぐためのものである。作業中も同じ規律を守ること。
リポジトリ全体に対する無制限の `rg`、`grep -R`、`find ... -exec grep`、巨大ファイルへの `cat` は避けること。
検索が必要な場合は、次の順序を優先する。
1. ありそうなディレクトリやファイルを絞る
2. 件数や分布を確認する
3. 代表的な一致だけを少量サンプルする
4. 候補となる識別子や検索語を抽出する
5. その後で小さな範囲の本文だけを見る
ログ、生成物、JSONL/XML、テスト出力などをそのまま大量に表示しないこと。必要な部分だけ抽出・要約してから確認すること。
## ドキュメントの自己改善
作業中に、今後のエージェントにも共有すべき規約や注意点が見つかった場合は、関連するドキュメントを更新してよい。
ただし、AGENTS.mdは短く保つこと。詳細な設計、仕様、背景説明は `docs/` 以下に分離すること。
AGENTS.mdを更新する場合は、将来の作業全体に効く恒久的な規約だけを追加すること。
## 完了条件
実装を完了したと主張する前に、関連する最小限の検証を実行すること。
検証できなかった場合は、何を確認できて、何が未確認なのかを明示すること。