filesystem

ファイルシステム

すべてのファイルおよびディレクトリ操作には、Claude Code に組み込まれたツールを使用します。MCP サーバーは不要です。ネイティブツールはより高速で高機能であり、アイドル時にコンテキストトークンを消費しません。

クイックリファレンス

ファイルシステム MCP ツール	代替手段	備考
read_file(path)	Read ツール	行オフセットと上限を指定できます
read_multiple_files(paths)	複数の並列 Read 呼び出し	順次実行する MCP 呼び出しより高速です
write_file(path, content)	Write ツール	ファイル全体を上書きします
edit_file(path, edits)	Edit ツール	文字列を正確に置換します。必要な箇所だけを編集できます
list_directory(path)	Glob または Bash ls	パターン検索には Glob、簡単な一覧表示には ls を使います
directory_tree(path)	Bash fd または Glob **/*	fd が最速です。パターンで絞り込むには Glob を使います
search_files(pattern, path)	Grep ツール	正規表現、ファイルタイプによる絞り込み、前後の行に対応します
create_directory(path)	Bash mkdir -p	-p は中間ディレクトリも作成します
move_file(src, dst)	Bash mv	名前の変更にも使用できます
get_file_info(path)	Bash stat または Bash ls -la	サイズ、権限、タイムスタンプ
list_allowed_directories	該当なし	Claude Code は作業ディレクトリ内で動作します。サンドボックスの制限はありません

---

ファイルの読み取り

1 つのファイルを読み取る

絶対パスを指定して Read ツールを使用します。

Read: /path/to/file.py

大きなファイルの場合は、オフセットと上限を指定して特定の範囲を読み取ります。

Read: /path/to/file.py (offset: 100, limit: 50)

これは 100 行目から 50 行を読み取ります。数千行あるファイルでコンテキストが大量に消費されるのを防ぐために使用してください。

複数のファイルを並列で読み取る

1 回の応答で複数の Read 呼び出しを行います。Claude Code はそれらを同時に実行します。

Read: /path/to/file1.py
Read: /path/to/file2.py
Read: /path/to/file3.py

並列読み取りは、内部で逐次実行される MCP の read_multiple_files より高速です。

画像と PDF を読み取る

Read ツールはバイナリ形式にも対応しています。

• 画像（PNG、JPG、SVG）：画像として表示されます
• PDF：テキストが抽出されます。大きなドキュメントでは pages: "1-5" を指定してください（1 回の呼び出しにつき最大 20 ページ）

---

ファイルの書き込みと編集

新しいファイルを書き込む

Write ツールを使用して、新しいファイルを作成するか、既存のファイルを上書きします。

Write: /path/to/new-file.py
Content: <full file content>

既存のファイルに書き込む場合は、先にファイルを読み取る必要があります。新しいファイルは、そのまま書き込めます。

既存のファイルを編集する

必要な箇所だけを変更するには、Edit ツールを使用して、文字列を完全一致で置換します。

Edit: /path/to/file.py
old_string: "def old_function():"
new_string: "def new_function():"

old_string がファイル内で一意でない場合、Edit ツールは失敗します。一致箇所を一意に特定できるよう、前後の文脈を十分に指定するか、ファイル全体で検索と置換を行う場合は replace_all: true を使用してください。

既存のファイルでは、Write よりも Edit を優先してください。Edit は変更箇所以外を保持し、差分を明確に表示します。Write はファイル全体を置き換えます。

---

ファイルを探す

名前のパターンで探す（Glob）

Glob: **/*.py           → all Python files recursively
Glob: src/**/*.ts       → TypeScript files under src/
Glob: *.md              → Markdown files in current directory
Glob: **/test_*.py      → test files anywhere in the tree

結果は更新日時の新しい順に並べ替えられます。

コンテンツ別（Grep）

Grep: pattern="def process_data" type="py"
Grep: pattern="TODO|FIXME" glob="*.py"
Grep: pattern="class.*Controller" output_mode="content" -C=2

Grep パラメーター	目的
pattern	一致させる正規表現パターン
type	ファイル形式フィルター（py、js、ts、rust、go など）
glob	Glob パターンフィルター（*.tsx、src/**/*.py）
output_mode	files_with_matches（デフォルト）、content、count
-C、-A、-B	コンテキスト行：一致箇所の前後、後、前
-i	大文字と小文字を区別しない検索

ディレクトリ一覧

シンプルな一覧：

ls -la /path/to/directory

fd を使った再帰的なツリー：

fd . /path/to/directory --type f

深さを制限したツリー：

fd . /path/to/directory --type f --max-depth 2

拡張子で絞り込む：

fd -e py /path/to/directory

---

ファイル操作

ディレクトリの作成

mkdir -p /path/to/new/directory

-p フラグを指定すると、中間ディレクトリがすべて作成されます。必ず先に ls で親パスが存在することを確認してください。

移動／名前変更

mv /path/to/source.py /path/to/destination.py

ファイルの名前を変更する（同じディレクトリ内）：

mv /path/to/old-name.py /path/to/new-name.py

ディレクトリを移動する：

mv /path/to/source-dir /path/to/destination-dir

コピー

cp /path/to/source.py /path/to/destination.py
cp -r /path/to/source-dir /path/to/destination-dir

削除

rm /path/to/file.py
rm -r /path/to/directory

ファイルやディレクトリを削除する前に、必ずユーザーに確認してください。

ファイルのメタデータ

stat /path/to/file.py
ls -la /path/to/file.py
wc -l /path/to/file.py

コマンド	取得内容
stat	サイズ、権限、タイムスタンプ、inode
ls -la	権限、所有者、サイズ、更新日
wc -l	行数
file	MIME タイプの判定

---

よくあるワークフロー

ファイルをまたいだ検索と置換

# Find all files containing the old string
Grep: pattern="old_function_name" type="py" output_mode="files_with_matches"

# Then Edit each file
Edit: /path/to/file1.py (old_string → new_string, replace_all: true)
Edit: /path/to/file2.py (old_string → new_string, replace_all: true)

不慣れなコードベースを調べる

1. プロジェクト構成を確認する：fd . --type f --max-depth 2
2. 設定を読む：Read: package.json または Read: pyproject.toml
3. エントリーポイントを探す：Grep: pattern="def main|if __name__" type="py"
4. 上で特定した主要なファイルを読む

大きなファイルを探す

fd --type f --exec stat -f '%z %N' {} \; | sort -rn | head -20

---

エラー処理

エラー	原因	解決方法
Read: file not found	パスが正しくないか、ファイルが削除されている	ls または Glob で確認する
Edit: old_string not unique	ファイル内に複数の一致箇所がある	前後のコンテキストを追加して一意にする
Edit: old_string not found	前回読み取ってから内容が変更されている	ファイルを再読み込みし、最新の内容で再試行する
Write: file not read first	読み込まずに上書きしようとしている	先にファイルを読み込んでから Write を実行する
Permission denied	OS の権限が不十分	ls -la で確認し、適切であれば chmod を使う
Glob: no files found	パターンが制限されすぎている	パターンを広げ、パスのスペルを確認する

---

制限事項

• Read はデフォルトで最大 2000 行を返します。大きなファイルには offset/limit を指定してください。
• Read は 2000 文字を超える行を切り詰めます。
• Edit では文字列の完全一致が必要です。空白とインデントも正確に一致させる必要があります。
• Write はファイル全体を上書きします。追記モードはありません。追記するには、先に読み込んでから、結合した内容を書き込んでください。
• Glob はファイルのみを検索し、ディレクトリは対象外です。ディレクトリを一覧表示するには Bash ls または fd を使ってください。
• PDF の読み込みは 1 回の呼び出しにつき 20 ページまでです。大きなドキュメントではページ範囲を指定してください。

---

キャリブレーションルール

1. 編集する前に読む。 ファイルは必ず編集する前に読み込んでください。Edit ツールはこの操作を強制します。
2. 既存ファイルには Write ではなく Edit を使う。 Edit は変更箇所を限定し、差分を表示します。Write はファイル全体を置き換えるため、新規ファイルまたは全面的な書き換えにのみ使用してください。
3. ファイル検索には Bash ではなく Glob を使う。 Glob はパターンマッチングに最適化されています。Glob では表現できない検索（サイズや日付による絞り込み）に限り、fd または find を使用してください。
4. 内容検索には Bash ではなく Grep を使う。 Grep は適切な権限設定で ripgrep による検索を行うよう最適化されています。Bash 経由で grep または rg を使用しないでください。
5. 複数ファイルを並行して読み込む。 並行実行できるよう、すべての Read 呼び出しを1回の応答で行ってください。
6. 常に絶対パスを使う。 Claude Code ツールでは絶対パスが必要です。Read、Write、Edit に相対パスを渡さないでください。