🗂️

【Claude Code活用】複数ファイル跨ぎの修正を任せる

に公開
AI
開発ツール
Claude
Claude Code
tech

複数ファイルをまたぐ変更の難しさ

新しいツールをエージェントに追加するとき、通常は以下の複数ファイルを同時に変更する必要があります。

ファイル 変更内容
src/tools/exec_tools.py ツール実装（新規作成）
src/tools/__init__.py エクスポート定義に追加
src/tool_definitions.py LLMへのツール定義に追加
src/dispatcher.py ディスパッチテーブルに追加

これらの変更が一つでも漏れると、ツールは動作しません。人間でもミスしやすいこの作業を Claude Code に任せた体験を紹介します。

実際に任せてみた：run_command ツールの追加

agent01 の Step 10 では run_command（subprocess でコマンドを実行するツール）を追加しました。

Claude Code は実装前に以下の順でファイルを読んで全体構造を把握しました。

  1. src/tools/__init__.py を読む（既存のエクスポート構成を確認）
  2. src/tool_definitions.py を読む（既存のツール定義フォーマットを確認）
  3. src/dispatcher.py を読む（ディスパッチテーブルの構造を確認）
  4. src/tools/file_tools.py を読む（実装スタイルの参照）

その上で4ファイルを順番に変更・新規作成しました。

src/tools/exec_tools.py
def run_command(command: str, cwd: str = ".") -> str:
    """シェルコマンドを実行して結果を返す。

    Args:
        command: 実行するコマンド文字列
        cwd: 作業ディレクトリ（デフォルト：カレントディレクトリ）

    Returns:
        実行結果（stdout / stderr / returncode を含む文字列）
    """
    for dangerous in DANGEROUS_COMMANDS:
        if dangerous.lower() in command.lower():
            return f"エラー：危険なコマンドのため実行を拒否しました: {command}"

    result = subprocess.run(
        command,
        shell=True,
        cwd=str(cwd_path),
        capture_output=True,
        text=True,
        encoding="utf-8",
        errors="replace",
        timeout=TIMEOUT_SECONDS,
    )
    # ...

tool_definitions.py へのツール定義追加も、既存フォーマットに合わせて正確に行われました。

src/tool_definitions.py
{
    "type": "function",
    "function": {
        "name": "run_command",
        "description": "シェルコマンドを実行する。テスト・lint・その他コマンドに使用。必ず人間の確認後に呼び出すこと",
        "parameters": {
            "type": "object",
            "properties": {
                "command": {
                    "type": "string",
                    "description": "実行するコマンド文字列",
                },
                "cwd": {
                    "type": "string",
                    "description": "作業ディレクトリ（省略時はカレントディレクトリ）",
                },
            },
            "required": ["command"],
        },
    },
},

dispatcher.py のインポートとディスパッチテーブルも自動で更新されました。

src/dispatcher.py
from tools import read_file, write_file, list_files, search_text, show_diff, patch_file, run_command

TOOL_REGISTRY: dict = {
    "read_file": read_file,
    # ... 既存ツール ...
    "run_command": run_command,  # ← 自動追加
}

実装指示書での複数ファイル指示の書き方

複数ファイル変更を正確に行わせるために、以下の形式で実装指示書を書きました。

## 作成・更新ファイル一覧

| ファイル | 操作 |
|---|---|
| `src/tools/exec_tools.py` | 新規作成 |
| `src/tools/__init__.py` | run_command を追加 |
| `src/tool_definitions.py` | run_command の定義を追加 |
| `src/dispatcher.py` | import と TOOL_REGISTRY に追加 |

## 各ファイルの変更内容

### src/tools/__init__.py

以下を追加する：

```python
from .exec_tools import run_command
```

### src/dispatcher.py

import 行を更新する（run_command を追加）：
...

「作成・更新ファイル一覧」を冒頭に明示することで、変更漏れを防げました。

気づき

ファイル間の依存関係を自力で把握していた：実装指示書にファイル一覧を書かなかった場合でも、Claude Code は既存コードを読んでから「__init__.py と tool_definitions.py と dispatcher.py も更新が必要です」と判断しました。ただし、指示書に明示した方が確実です。

import の追加漏れは自己修正できた：テスト実行時に ImportError が出た場合、Claude Code はエラーメッセージを読んで原因を特定し、__init__.py のエクスポート定義を自動で修正しました。

ファイル数が多いほど指示書の価値が上がる：3〜4ファイルを同時に変更する場合、指示書に一覧を書いておくことで変更漏れをゼロにできました。人間がレビューするときも変更ファイルが明確で確認しやすくなります。

まとめ

Claude Code は複数ファイルをまたぐ変更を正確に処理できます。実装指示書に「作成・更新ファイル一覧」を明示しておくことで変更漏れを防ぎ、ファイル間の依存関係も自律的に把握して対応します。

次回

B7 では、PROGRESS.md を使ってセッションをまたいだ開発を進める方法を紹介します。13 Step の開発を通じて確立した運用サイクルをお伝えします。

シリーズリンク（Series B）

記事 タイトル
B1 Claude Codeとは・導入と初期設定
B2 ファイル読み書きを任せる
B3 コードベース探索を任せる
B4 差分確認・適用を任せる
B5 テスト実行と結果解釈を任せる
B6 複数ファイル跨ぎの修正を任せる（本記事）
B7 PROGRESS.md駆動開発
B8 Zenn記事をClaude Codeに書かせる

Discussion