Claude Code:ターミナルからAIコーディングエージェントを実行して開発を自動化し大規模プロジェクトをリファクタリングする

AI tutorial - IT technology blog
AI tutorial - IT technology blog

現在のAIコーディングツールの問題点

ほとんどのAIコーディングアシスタントは、IDEのサイドバーチャットとして存在しています。コードを貼り付け、提案を読み、コピーして戻す——この繰り返しは20行の関数なら問題ありませんが、40ファイルのPythonパッケージをリファクタリングしたり、レガシーAPIを移行したり、テストを念頭に置いて設計されていなかったコードにテストを書いたりする場合には、まったく機能しません。

根本的な原因は、これらのツールがアシストするだけで、実行しないことです。テキストを渡してくれるだけで、残りはあなたがやらなければなりません。

Claude Codeは違います。ターミナルで動作し、実際のファイルを読み込み、シェルコマンドを実行し、タスクが完了するまで自律的に作業を繰り返します。

実際の経験から言えば、ソフトウェア開発においてAIから本格的な恩恵を得たいなら、習得必須のスキルの一つです。10,000行のコードベースを読み込んで数十ファイルにわたって的確な編集を行えるエージェント型ツールを一度使うと、サイドバーチャットに戻るのは、スプレッドシートが必要なのに電卓を使うような感覚に陥ります。

クイックスタート:5分で動かす

Claude CodeにはNode.js 18以上とAnthropicアカウントが必要です。npmでグローバルにインストールします:

npm install -g @anthropic-ai/claude-code

インストールが完了したら、任意のプロジェクトディレクトリに移動してセッションを開始します:

cd ~/my-project
claude

初回起動時にAnthropicのAPIキーを求められます(もしくはClaude.ai MaxサブスクリプションでOAuth認証することも可能)。その後、プロジェクト内でインタラクティブなプロンプトが表示されます:

✓ Claudeに接続しました (claude-sonnet-4-6)
~/my-project $ 

すぐにシンプルなタスクを試して、動作確認をしましょう:

> このプロジェクトの概要を説明し、主要なモジュールを一覧表示して

Claude Codeはファイル(README.md、package.json、pyproject.tomlなど見つかったもの)を読み込んで、構造化されたサマリーを提供します。コピー&ペーストは不要です。初めて触れるコードベースでも、これだけで数分の節約になります。

インタラクティブモードに入らずに単発のタスクを実行するには、-pフラグを使います:

claude -p "src/ディレクトリ内のTODOコメントをすべて列挙して"

詳細解説:Claude Codeの仕組み

テキストだけでなくツールを持つ

チャットインターフェースとは異なり、Claude Codeは自律的に呼び出せる一連のツールにアクセスできます:

  • Read — プロジェクト内の任意のファイルを読み込む
  • Edit / Write — 正確な文字列置換や新規ファイルの作成を行う
  • Bash — シェルコマンドを実行する(grep、pytest、git diffなど)
  • Glob — パターンでファイルを検索する
  • Grep — 正規表現でファイル内容を検索する

タスクを与えると、どのツールを呼び出すかを計画し、実行し、出力を読み取り、次の行動を決定します——タスクが完了するか、入力が必要になるまで、このループを繰り返します。

パーミッションモデル

デフォルトでは、Claude Codeはシェルコマンドの実行やファイルへの書き込みの前に許可を求めます。これは意図的な設計です——実際に何が実行されるかはあなたがコントロールします。信頼できるタスクで完全自律操作をしたい場合は--dangerously-skip-permissionsを使えますが、本番コードに触れる作業ではデフォルトのままにすることをおすすめします。

# デフォルト:書き込み/bash実行のたびに確認を求める
claude

# 自律モード(慎重に使用すること)
claude --dangerously-skip-permissions -p "src/内の全パブリック関数にdocstringを追加して"

コンテキストとメモリ

プロジェクトルートにCLAUDE.mdファイルがあれば、Claude Codeはそれを読み込みます。これはプロジェクト固有のルール、コーディング規約、ファイル構造のメモなど、セッションをまたいでClaude Codeに記憶させたいことを書く永続的な指示レイヤーです。

# CLAUDE.mdを自動生成する
claude /init

/initを実行すると、Claude Codeがプロジェクトを探索して、アーキテクチャ、主要ファイル、観察した規約をまとめたCLAUDE.mdを作成します。その後、自分のルールを追記してください。

応用:大規模プロジェクトのリファクタリング

複数ファイルにまたがるリネームと構造変更

これこそClaude Codeの真価が発揮される場面です。25個の異なるファイルで呼ばれている関数をリネームする必要があり、引数の順序変更によっていくつかの呼び出し箇所で微妙な調整が必要な場合を考えてみましょう。手動の検索置換では壊れてしまいます。Claude Codeならこう指示するだけです:

> `process_data()`を`transform_records()`にリネームして。新しいシグネチャは`(data, schema)`の代わりに`(records, schema, strict=False)`を取ります。すべての呼び出し箇所を適宜更新し、テストを実行して壊れていないか確認して。

すべての呼び出し箇所をgrepで検索し、的確な編集を行い、テストスイートを実行します——テストが失敗した場合は、エラー出力を読み取って残りの問題の修正を試みます。

テストのないコードへのテスト作成

> src/billing/invoice.pyを見て。すべてのパブリックメソッドに対してpytestユニットテストを書いて。データベース呼び出しにはモックを使うこと。テストはtests/billing/test_invoice.pyに配置して、すべて通ることを確認して。

Claude Codeはソースファイルを読み込み、メソッドを特定し、テストファイルを作成し、pytestを実行し、失敗を読み取って繰り返します。300行のモジュールなら2分以内で完了します。

依存関係の移行

主要な依存関係のアップグレード(例えば非同期サポートのためにrequestsからhttpxへの移行)は、以前なら午後丸ごと使って検索置換し、微妙な動作の違いをデバッグする作業でした。Claude Codeを使えば:

> このプロジェクトの全HTTPコールを`requests`から`httpx`に移行して。呼び出し元の関数がすでに非同期の場合はasync/awaitを使い、それ以外は同期呼び出しにすること。requirements.txtも更新して。移行後にテストを実行して。

Git連携

Claude Codeはgitの履歴を読み込み、差分を確認し、コミットを作成できます。変更内容を正確に説明するコミットメッセージの生成に役立ちます:

> ステージされた変更を見て、conventional commitフォーマットでコミットメッセージを書いて

クローンしたばかりのコードベースを理解するときにも使えます:

> 直近20件のコミットを見て、チームが何に取り組んできたかをまとめて

本当に役立つ実践的なコツ

スコープを明確に指定する

曖昧なタスクは曖昧な結果しか生みません。「コード品質を改善して」ではなく、「src/api/内で50行を超える関数を見つけて、小さな関数に分割して。既存の動作は維持し、パブリックAPIは変更しないこと」と言いましょう。制約を多く与えるほど、出力は精度が高くなります。

CLAUDE.mdを積極的に活用する

プロジェクトの規約は早めにCLAUDE.mdに追加しましょう。例えば:

  • 使用するテストランナーとその実行方法
  • コード自体からは明らかでないコーディングスタイルのルール
  • 絶対に変更してはいけないファイルやディレクトリ
  • デプロイに関するメモ

すべてのセッションがこれらのルールを自動的に引き継ぎます。毎回コンテキストを説明し直す手間が省けます。

大きなタスクをフェーズに分割する

約20ファイル以上に影響するものは、チャンクに分割しましょう。Claude Codeにはコンテキストウィンドウがあり、非常に大きなタスクは終盤に一貫性を失うことがあります。例えばこのように:

  1. 第1フェーズ:「src/models/内の全関数に型ヒントを追加して」
  2. 第2フェーズ:「次にsrc/services/を対象にして」
  3. 第3フェーズ:「mypyを実行して型エラーを修正して」

承認前に必ずレビューする

Claude Codeがファイルに書き込む際、何が変わったかを正確に表示します。必ず読みましょう。AIツールは自信満々に間違えることがあります——リネームされた変数は25箇所中24箇所は正しくても、25箇所目で間違っているかもしれません。パーミッション確認プロンプトは理由があって存在します。承認前に実際に差分を確認するために使ってください。

CIと組み合わせてさらなる効果を

スクリプト内でClaude Codeを非インタラクティブに呼び出せるため、自動化の可能性が広がります:

# Makefileまたはシェルスクリプト内で使用
claude --dangerously-skip-permissions -p \
  "直近のコミットで変更されたファイルに明らかなバグがないか確認して。発見事項をJSONリストで出力して。" \
  --output-format json

出力をリンター、通知システム、またはpre-commitフックにパイプできます。CIパイプラインの代替にはなりませんが、静的解析では見逃すものをキャッチするAIレビューの層が加わります。

料金と実際に必要なもの

Claude CodeはAnthropic APIを使用するため、トークンごとに課金されます。中規模のリファクタリングタスクの典型的なインタラクティブセッションのコストは、コードベースのサイズと必要な反復回数によって異なりますが、おおよそ$0.50〜$2.00程度です。毎日ヘビーに使うと積み重なるので、Anthropicのダッシュボードを時折確認するといいでしょう。

Claude.ai Maxサブスクリプション(月額$100)を持っている場合、OAuthで認証してプランに含まれる高いレート制限でClaude Codeを使用できます——別途APIの課金は不要です。大規模に利用するチームには、こちらの方がコスト効率が良い場合がほとんどです。

実用的な基準としては、機械的なコーディング作業——検索置換によるリファクタリング、ボイラープレートテストの作成、既存コードのドキュメント化——に1日1時間以上費やしているなら、Claude Codeのコストはすぐに元が取れます。

Share: