Claude APIのテキストエディタツールの使い方

テキストエディタツールは、Anthropic があらかじめスキーマを定義しているツールで、Claude にファイルの閲覧・作成・編集を行わせるためのものです。コードのデバッグやリファクタリング、ドキュメント生成などで、Claude が提案するだけでなく実際のファイルに手を入れられるようになります。この記事は Anthropic 公式ドキュメントの非公式日本語訳・要約です。

テキストエディタツールとは

テキストエディタツールは、Claude がテキストファイルを閲覧・編集できるようにする、Anthropic スキーマのツールです。Claude は変更点を口頭で提案するだけでなく、ファイルそのものを直接読み書きできます。主な用途は次のとおりです。

コードのデバッグ: 構文エラーからロジックの不具合まで、Claude が特定して修正します。
リファクタリング: 構造・可読性・性能を、狙いを絞った編集で改善します。
ドキュメント生成: docstring やコメント、README を追加します。
テスト作成: 実装を読み取り、それに基づく単体テストを作成します。

このツールは「クライアントツール」です。Claude 自身がファイルを操作するのではなく、Claude は実行すべきコマンドを返し、実際の閲覧・編集はあなたのアプリケーション側で行って結果を返します。対応モデルはツールのバージョンによって異なるため、公式のツールリファレンスで確認してください。

ツールの指定方法

テキストエディタツールは、Messages API のリクエストに tools として渡します。ツール名は str_replace_based_edit_tool で、type にバージョン識別子を指定します。最新のバージョンは text_editor_20250728 です。

{
  "model": "claude-opus-5",
  "max_tokens": 1024,
  "tools": [
    {
      "type": "text_editor_20250728",
      "name": "str_replace_based_edit_tool"
    }
  ],
  "messages": [
    { "role": "user", "content": "syntax.py のバグを修正して" }
  ]
}

大きなファイルを閲覧する際の切り詰めを制御したい場合は、任意で max_characters パラメータを指定できます。ただし max_characters は text_editor_20250728 以降のバージョンでのみ利用できます。type の識別子はモデルによって対応バージョンが異なるため、使用するモデルに合ったものを公式リファレンスで確認してください。

対応コマンド

テキストエディタツールは、閲覧と編集のためのいくつかのコマンドを持ちます。Claude が返す tool_use ブロックの command フィールドで、どの操作かが示されます。

view: ファイルの内容、またはディレクトリの一覧を表示します。任意の view_range（2つの整数の配列）で行範囲を指定できます。行番号は1始まりで、終端に -1 を指定するとファイル末尾までを読みます。範囲指定はファイル閲覧時のみ有効です。
str_replace: ファイル内の特定の文字列を新しい文字列に置き換えます。old_str（置換対象・空白やインデントも含めて完全一致が必要）と new_str（置換後の文字列）を渡します。精密な編集に使います。
create: 新しいファイルを作成します。file_text に内容を渡します。
insert: 指定した行番号にテキストを挿入します。insert_line と挿入するテキストを渡します。

いずれのコマンドも、対象ファイルの path を伴います。old_str が複数箇所に一致する、あるいはどこにも一致しない場合、str_replace は編集を行いません。置換対象は前後の文脈を含めて一意になるように指定するのが安全です。

実装の流れ

クライアントツールなので、コマンドを実際に実行するのはあなたのアプリケーションです。典型的な流れは次のようになります。

ツールを渡してリクエストする: テキストエディタツールを含めて Messages API を呼び出します。
Claude がコマンドを返す: Claude はまず view でファイルやディレクトリを確認しようとし、レスポンスに tool_use ブロックが含まれます。
コマンドを実行して結果を返す: あなたのアプリがそのコマンド（閲覧・置換・作成・挿入）を実行し、結果を tool_result ブロックとして返します。max_characters を指定していれば、閲覧結果はその長さに切り詰めます。
編集まで繰り返す: Claude は内容を確認したうえで、str_replace や insert などの編集コマンドを返します。あなたのアプリが実行し、また結果を返します。完了まで往復を続けます。

ファイルの実体を扱うのは常にアプリ側です。編集前にバックアップを取る、対象ディレクトリを限定するなど、安全策は実装側で用意します。

利用時の注意点

実行はアプリ側の責任: Claude はコマンドを返すだけで、ファイルを操作するのはあなたのコードです。信頼できないパスを操作しないよう、対象範囲を制限してください。
str_replace は完全一致: old_str は空白・インデントまで含めて厳密に一致する必要があります。一致が0件または複数件だと置換は行われません。
バージョンとモデルの対応: type の識別子（例: text_editor_20250728）は対応モデルが決まっています。古いバージョンではコマンドの構成が異なる場合があるため、使用モデルに合わせて公式リファレンスで確認します。
max_characters はバージョン依存: 閲覧結果の切り詰めに使う max_characters は text_editor_20250728 以降でのみ使えます。

より低レベルにファイル編集をさせる代わりに、コマンドラインを実行させたい場合はbash ツールも参照してください。正確な仕様・対応モデルは必ず公式ドキュメントで確認してください。