ツールシステムリファレンス

file_read

機能:

• ファイル内容の全体または特定の行範囲の読み取り
• 変更前にコードを理解するために不可欠
• 行範囲指定により大きなファイルを効率的に処理

ユースケース:

• 編集前の設定ファイルの読み取り
• 既存の実装パターンの理解
• カバレッジを把握するためのテストファイルの確認

例:

# Read entire file
file_read("src/components/Button.tsx")

# Read specific range for large files
file_read("package-lock.json", start_line=1, max_lines=50)

file_edit

機能:

• 完全一致による正確なテキストの置換
• multipleフラグによる複数箇所の置換
• ファイル構造と書式の保持

ユースケース:

• 関数の実装の更新
• 設定値の変更
• ファイル全体にわたる変数名のリファクタリング

ベストプラクティス: 対象を絞った変更に使用します。完全な書き換えには、代わりにfile_writeを使用してください。

file_write

機能:

• 新規ファイルをゼロから作成
• 既存ファイルの内容を完全に置換
• あらゆるテキストベースの形式を処理

ユースケース:

• 新しいコンポーネントやモジュールの生成
• 設定ファイルの作成
• テストファイルの記述

警告: 既存ファイルを完全に上書きします。部分的な変更にはfile_editを使用してください。

glob

機能:

• パターンに一致するファイルを検索: **/*.ts、src/**/*.js
• ディレクトリパスによるフィルタリング
• 除外パターンによる結果の絞り込み
• 結果数の制御

ユースケース:

• プロジェクト内の全コンポーネントの検索
• テストファイルの特定
• ディレクトリをまたいだ設定ファイルの特定

パターンの例:

**/*.tsx          # All TypeScript React files
src/**/*.test.js  # All test files in src
**/config.*       # All config files anywhere

grep_content

機能:

• 正規表現パターンを使ったファイル内容の検索
• 一致箇所の前後のコンテキスト行の表示（-B、-Aフラグ）
• 大文字小文字を区別しない検索
• Glob パターンによるファイルタイプのフィルタリング

ユースケース:

• 関数定義の検索
• APIエンドポイント実装の特定
• 特定のエラーメッセージの検索
• セキュリティパターンの特定

例:

# Find authentication-related code
grep_content("auth.*login", glob="**/*.ts")

# Search with context
grep_content("TODO", glob="src/**", context_before=2, context_after=2)

grep_file

機能:

• パターンに一致するファイルの一覧表示
• ファイルの場所だけが必要な場合はgrep_contentより高速
• 正規表現パターン対応
• ファイルタイプの Glob フィルタリング

ユースケース:

• リファクタリングが必要なファイルの特定
• 特定のモジュールをインポートしているファイルの検索
• 非推奨パターンを含むファイルの特定

ベストプラクティス: まずgrep_fileで関連ファイルを特定し、その後file_readで詳細に調べます。

list_dir

機能:

• ディレクトリ階層の表示
• max_depthパラメータによる深さの制御
• 除外パターンによる出力のフィルタリング

ユースケース:

• プロジェクト構造の理解
• ディレクトリ構成の確認
• 特定のサブディレクトリの検索

bash

機能:

• シェルコマンドの実行
• 最大タイムアウト: 120 秒（2 分、上限）
• 依存関係のあるコマンドを&&で連結
• 分かりやすいように説明的な概要を提供

ユースケース:

• テストの実行
• プロジェクトのビルド
• 依存関係のインストール
• Git操作
• データベースマイグレーション

例:

# Run tests
bash("npm test", timeout=60000, summary="Run Jest test suite")

# Chain dependent commands
bash("npm install && npm run build", timeout=120000)

セキュリティ: コマンドはユーザー権限で実行されます。Manual Accept Modeでコマンドを確認してください。

spawn_subagent

機能:

• 分離されたコンテキストを持つ専門サブエージェントの起動
• タイプ: explorer、verifier、code-reviewer
• メインのコンテキストを汚さずに複雑なタスクを委任
• 効率化のためのサブエージェントの並列実行

ユースケース:

• explorer: 大規模なコードベースからパターンを検索
• verifier: 実装ロジックの検証
• code-reviewer: セキュリティと品質の評価

ベストプラクティス: 探索的な調査は Explorer サブエージェントに委任し、メインの会話のコンテキストを温存します。

todo_update

機能:

• タスクリストの作成と管理
• タスクステータス（pending、in_progress、completed）の更新
• 複雑な実装全体にわたる進捗の追跡

ユースケース:

• 複数ステップの機能の分解
• リファクタリングの進捗追跡
• マイグレーションタスクの管理

web_search

機能:

• インターネット検索エンジンへのクエリ
• 結果数の制御
• 新しさ（直近の日数）によるフィルタリング

ユースケース:

• 馴染みのないAPIのドキュメントの検索
• エラーメッセージの調査
• 現在のベストプラクティスの確認

web_fetch

機能:

• Web ページ内容の取得
• 特定のクエリによるコンテンツの分析
• 構造化された情報の抽出

ユースケース:

• ドキュメントページの読み取り
• APIドキュメントの分析
• チュートリアルからの例の抽出

データ形式

ビルドとパッケージファイル

file_read の効率化

ベストプラクティス:

• 500 行を超えるファイルでは行範囲を使い、コンテキストの過負荷を避ける
• タスクに必要な箇所のみを読み取る
• 大きなファイルでは、まずgrep_contentで関連する行番号を特定する

# Good: Read specific section
file_read("large-config.json", start_line=100, max_lines=50)

# Less efficient: Read entire large file
file_read("large-config.json")  # May consume excessive context

file_edit の精度

ベストプラクティス:

• 編集の失敗を避けるため、文字列を完全に一致させる
• 類似した複数の変更には、multiple=trueフラグを使用する
• 編集前にファイルパスを確認する

file_write の安全性

ベストプラクティス:

• 誤った上書きを防ぐため、パスを再確認する
• 新規ファイルまたは完全な書き換えにのみ使用する
• 変更には安全のためfile_editを優先する

glob パターンの具体性

ベストプラクティス:

• スコープを絞るため具体的なパターンを使用する: **/*ではなくsrc/**/*.ts
• 除外パターンでディレクトリを除外する: !**/node_modules/**
• 出力が膨大にならないよう結果を制限する

# Good: Specific scope
glob("src/components/**/*.tsx", max_results=50)

# Less efficient: Too broad
glob("**/*")  # Returns thousands of results

grep 戦略

推奨ワークフロー:

1. grep_fileで関連ファイルを特定する
2. file_readで特定のファイルを読み取る
3. 周辺のコンテキストが必要な場合はgrep_contentを使用する

パフォーマンスのヒント:

• 正規表現パターンはリテラル文字列より時間がかかる場合がある
• 大文字小文字を区別しない検索は遅くなる
• コンテキスト行（-A、-B）は必要な分に制限する

bash のベストプラクティス

安全なコマンド実行:

• コマンドの説明には明確な概要を提供する
• 長時間実行される操作には適切なタイムアウトを設定する
• 依存関係のあるコマンドは&&で連結する
• 破壊的なコマンド（rm、drop、truncate）は慎重に確認する

# Good: Clear summary, reasonable timeout
bash("npm run build", timeout=120000, summary="Build production bundle")

# Good: Chained dependencies
bash("npm install && npm run test", timeout=180000)

セキュリティに関する考慮事項

重要な安全ルール:

• コマンドはユーザー権限で実行される
• 信頼できないコマンドは決して実行しない
• 共有コードベースではManual Accept Modeを使ってレビューする
• 認証情報や機密データを露出するコマンドは避ける

サブエージェント委任の効率化

サブエージェントを使うべき場面:

• Explorer: コードベースの検索、アーキテクチャに関する質問（メインのコンテキストを節約）
• Verifier: 素早い検証チェック（分離された検証）
• Code-reviewer: セキュリティと品質のレビュー（詳細な分析）
• General: 複雑な複数ステップのタスク（並列実行）

ベストプラクティス: 探索や調査のタスクをサブエージェントに委任し、アクティブな開発作業のためにメインの会話のコンテキストを温存します。

コンテキスト管理

戦略的なツールの使用:

• ファイルは戦略的に読み取る — 必要なものだけ
• バックグラウンドの調査にはサブエージェントを使う
• 長いセッション中はコンテキストの消費を監視する
• 複雑な操作は todo_update でステップに分解する

効率的なワークフロー:

1. 計画: glob/grep でスコープを特定する
2. 読み取り: 関連するファイル/箇所のみを読み取る
3. 実行: 適切な場合はサブエージェントに委任する
4. 検証: Verifier サブエージェントで素早くチェックする

ファイルサイズの制限

大きなファイルの扱い: 非常に大きなファイル（10,000 行超）は、以下を避けるためにセクションに分けて読み取る必要があります。

• コンテキストウィンドウの枯渇
• 応答の遅延
• メモリの問題

ツールのタイムアウトのデフォルト

ツールの制限:

• Bash のタイムアウト: 最大 120 秒（2 分）
• ファイル操作: サイズ制限なし（大きなファイルは自動的にバッチで読み取られる）
• 大きなファイルの扱い: 256KB を超えるファイルは最初の 256KB の内容のみを返す
• 検索結果: globやgrep_contentの結果に制限なし
• 並行サブエージェント: 並列実行に制限なし

タイムアウトの設定:

• 長時間実行される操作には明示的なタイムアウトを設定する
• ハングするプロセスを監視する
• 2 分のタイムアウトを超えるコマンドは終了される

並行操作

並列実行: 複数のサブエージェントを並列実行することで、複雑な操作をより高速に行えます。メインエージェントが調整を自動的に処理します。

パフォーマンス上の利点:

• 複数ステップのタスクの総実行時間の短縮
• 効率的なリソース利用
• 自動的なタスクのオーケストレーション
• 並行サブエージェント数に制限なし