Claude Codeチュートリアル：セットアップ、リファクタリング、デバッグを実践で学ぶ

Claude Codeとは？

Claude Codeは、ターミナル上で直接動作し、コードベースを理解して自然言語コマンドで開発タスクを支援するツールです。 最小限のセットアップで開発環境に統合できるため、コーディングと改善に集中できます。

Claude Codeの主な機能は次のとおりです。

• 編集とリファクタリング: AIによる提案でコードベースを修正・最適化・強化します。
• バグ修正: エラー、依存関係の不足、パフォーマンスのボトルネックを特定して解決します。
• コード理解: アーキテクチャ、ロジック、依存関係について質問できます。
• 自動テストとリンティング: 失敗したテストの実行と修正、lintコマンドの実行、コード品質の向上を行います。
• Git連携: Git履歴の検索、マージコンフリクトの解消、コミット作成、プルリクエストの生成を簡単に行えます。

オープンソースでもエンタープライズ規模のコードベースでも、Claude Codeはコーディングスタイルや要件に適応するインテリジェントな自動化で支援します。最近のアップデートでは、オートモード（許可リクエストの中断が少ない）、プランモード（設計優先のワークフロー）、Routines（マシンを起動せずにトリガーで動くスケジュール実行のクラウドエージェント）が追加されています。

このサービスの主な利用者像は次のとおりです。

• ソフトウェア開発者：コード品質と保守性の向上。
• OSS貢献者：不慣れなコードベースの理解と改善。
• DevOpsエンジニア：コードレビューやリンティング作業の自動化。

Claude Codeは現在、MaxおよびTeam PremiumプランでClaude Opus 4.7がデフォルトです。 ProユーザーはSonnet 4.6から開始しますが、負荷の高いタスクではOpusに切り替えられます。セッション中に/modelコマンドでモデルを切り替え、/effortスライダーで推論深度を調整できます。さらに、Claude Agents SDKを使用してスタンドアロンのAIエージェントを構築することも可能です。

Anthropicは、コーディング以外の日常的なファイルやドキュメント作業をエージェント的に支援するCoworkも導入しました。Claude Desktopアプリ上で、有料プラン（Pro、Max、Team、Enterprise）の全ユーザーが利用できます。

それでは、ハンズオンプロジェクトを始めましょう。

ステップ1：Claude Codeのセットアップ

Claude Codeを始めるには、ターミナル、作業対象のコードプロジェクト、そしてClaudeのサブスクリプション（Pro/Max/Teams/Enterprise）または課金が有効なClaude Consoleアカウントが必要です。

OSやターミナルに応じて、以下のいずれかのコマンドを実行するだけでClaude Codeをインストールできます。

macOS / Linux / WSL: 

curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell: 

irm https://claude.ai/install.ps1 | iex

Windows CMD:  

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

注：npm install -g @anthropic-ai/claude-codeによるインストールも引き続き可能ですが、非推奨となっているため、上記のネイティブなインストール手順を推奨します。以前npmでインストールしていた場合は、claude installで移行できます。

インストール後、プロジェクトディレクトリへ移動し、次を実行してClaudeを起動します。

cd your-project-directory
claude

認証では、有料サブスクリプションに基づく利用か、API従量課金に基づく利用かを選択します。

次に、ログインリンクが表示され、検証コードが発行されます。これをClaude Codeを実行中のターミナルに入力してください。完了すると、 使用状況の追跡とコスト管理のための専用ワークスペース「Claude Code」が自動的に作成されます。

これでClaude Codeを使う準備が整いました。

ステップ2：開発環境のセットアップ

このデモでは、Supabaseと対話するためのオープンソースPythonクライアントであるsupabase-pyを使用します。SupabaseはPostgreSQL上に構築されたBaaS（Backend as a Service）で、認証、リアルタイム購読、ストレージ、自動生成APIなどのツール群を提供します。

まず、リポジトリをクローンし、開発環境を整えましょう。

1. ターミナルを開き、Supabase-pyリポジトリをクローンしたいディレクトリ（例：cd Desktop）へ移動し、次のコマンドを実行します。

git clone https://github.com/supabase/supabase-py.git
cd  supabase-py

2. 次に、仮想環境を作成し、必要な依存関係をインストールします。以下のコマンドをターミナルで1行ずつ実行してください。

python3 -m venv env
source env/bin/activate  # On Windows, use ./env/Scripts/activate
pip install -e .

これでSupabaseライブラリを実行するために必要な依存関係を備えたPython環境が整い、リポジトリの準備も完了しました。

ステップ3：貢献領域の特定

貢献の良い出発点は、GitHubのIssuesタブを確認することです。Supabaseのリポジトリでは、client.pyに、可読性・構造・コメント不足に関する課題を見つけました。

ここでは、Claude Codeで次のことを行います。

• 可読性・保守性・構造を高めるためにコードをリファクタリング。
• 各コンポーネントの目的が明確になるよう、意味のあるドックストリングとインラインコメントを追加。
• Issueや潜在的な不具合を分析して、バグを特定・修正。

ステップ4：Claude Codeで試してみる

すでにsupabase-pyフォルダ内にいるので、client.pyがあるsupabaseディレクトリに移動し、Claude Codeを実行します。

cd supabase
claude

Claude Codeは、Supabase-pyフォルダ配下のすべてのファイルとフォルダにアクセスできるようになりました。では、実験してみましょう。

コードのリファクタリング

Supabase Python SDKの改善の一環として、client.pyをリファクタリングし、可読性・保守性・整理度を高めます。コマンドラインに次のプロンプトを入力してください。

プロンプト：Supabaseフォルダ内のclient.pyのコードをリファクタリングしてください。

Claudeは実行前に確認を求めます。変更を承認するにはEnterを押してください。完了すると、Claude Codeがファイルを更新し、ターミナルに変更点を表示して、要約を提示します。

Claude Codeを使って、client.pyに次の改善を施しました。

• インポートの整理：関連するインポートを（認証エラー、API型、関数エラーなど）論理的なセクションにグルーピングし、可読性向上のために名前を調整し、一貫性のため冗長なエイリアスを削除しました。
• 可読性の向上：インポートを分類するセクションコメントを追加し、__all__リストの重複を除去して構成をすっきりさせました。
• クライアントオプションの簡素化：類似のインポートを1つのステートメントにまとめ、行数を削減しました。

以下は、オリジナルとリファクタリング後のコードの比較です。

コードのドキュメント化

リファクタリングに加え、Claude Codeはプロジェクト全体のコードドキュメントを生成・更新・標準化できます。未ドキュメントの箇所を特定し、構造化されたドックストリングやコメントを生成し、プロジェクトのドキュメント標準への準拠も確認できます。

client.pyのドキュメントをClaude Codeで改善した結果、次のようになりました。

• ファイルの目的を説明するモジュールレベルの明確なドックストリング。
• インポートを分類する詳細なセクションコメント（エラー種別、クライアント実装、ストレージサービス）。
• エラー種別、クライアント関数、重要なコンポーネントを説明するインラインコメント。

以下は、リファクタリング後とドキュメント追加後のコードの比較です。

プロンプト：client.pyにコメントを追加して理解しやすくなるようドキュメント化してください。

ドキュメントの追加後、次のように促すことで、プロジェクト標準に準拠しているかを確認できます。

プロンプト：ドキュメントがプロジェクト標準に従っているか確認してください。

バグ修正

デバッグは時間がかかりがちですが、Claude Codeはエラーメッセージを分析し、原因を特定して修正案を提示することでサイクルを短縮します。インポート不足、実行時エラー、ロジックの問題など、探索範囲を絞り、的確な修正を提案します。

Claude Codeでデバッグする手順は次のとおりです。

1. 問題の特定：エラーメッセージをClaudeに共有します。
2. 修正案の取得：可能な解決策をClaudeに尋ねます。
3. 修正の適用と検証：Claudeの提案を実装し、問題が解決したか確認します。

client.py内のインポート関連の問題解決に向け、Claude Codeは次の対応を行いました。

• type ignoreコメント： 未解決のインポートに対するIDEや型チェックの警告を抑制するため、# type: ignoreコメントを追加。
• エラー分類の一貫性： 認証・データベース・ストレージ・関数のエラーに関するインポートを明確にグルーピング。
• 可読性の維持： インポートを削除するのではなく、無視した理由を示すコメントを追加。

以下は、元のコードと修正後コードの比較です。

プロンプト： 「Import gotrue.errorsを解決できません」などのバグが見られます。client.pyのすべてのエラー修正を手伝ってください。

Claude Codeのコマンド

Claudeで試せるコマンドをいくつか紹介します。

併せて、Anthropicの公式チュートリアルや、当社のClaude Codeベストプラクティスガイドもご確認ください。

Claude Codeの高度な機能

リファクタリングとデバッグの基本に慣れたら、Claude Codeの振る舞いをカスタマイズして機能を拡張できます。HooksとPlugins を使うと、定型作業を自動化し、外部システムと統合できます。

Claude Code hooks

Claude Code hooksは、Claude Codeのセッション中に特定のイベントが発生した際にシェルコマンドを実行する自動トリガーです。コード整形、テスト実行、セキュリティチェックなど、Claudeがスキップしがちな定型作業を自動化します。

Hooksはイベントとアクションの仕組みで、次の3点を定義します。

• イベント：いつフックが発火するか？

• マッチャー：どの操作に適用するか？

• コマンド：フック発火時に何を実行するか？

例えば、ClaudeがPythonファイルを書き込んだ後にフックを発火させ、コード整形ツールblackを自動実行できます。Hooksは発生内容のJSONコンテキストを受け取り、ファイル種別やパスに基づく判断を可能にします。Claudeのトランスクリプトへ出力したり、エラーメッセージを直接送信して処理をブロックすることもできます。

Hooksの一般的なユースケース：

• コード整形：書き込み後に自動でリンターやフォーマッターを実行

• テスト：変更後にテストスイートを実行し、早期に不具合を検出

• セキュリティ：本番設定やAPIキーなど機密ファイルの変更をブロック

• ドキュメント：ソース変更時にAPIドキュメントを自動生成

• Git自動化：スマートなコミット作成やブランチ保護ポリシーの検証

• 通知：重要ファイルの変更をSlackでチームに通知

• コンプライアンス：変更許可前にライセンスヘッダーやコーディング規約を強制

フックは、Claude Code内で/hooksコマンドを使って設定するか、~/.claude/settings.jsonを直接編集して設定します。

Claude Code plugins

プラグインは、Claude Codeを外部ツール、サービス、APIに接続する拡張機能です。Hooksがローカルのシェルコマンドを自動化するのに対し、プラグインはCI/CD、プロジェクト管理、チームコミュニケーションなど広範な開発エコシステムと統合します。

プラグインは、サブエージェント（特定タスクに特化したClaudeアシスタント）、MCPサーバー（標準化されたツール統合）、Hooksなど複数コンポーネントを1つにまとめ、連携してオーケストレーションできます。

例えば、コード変更を分析してJiraに課題を自動起票したり、社内のテスト基盤に接続したりできます。プラグインはHooksと同じイベントに反応しますが、データを外部サービスへ送信し、応答を処理してClaudeのワークフローに反映します。

Claude Codeプラグインが得意なタスク：

• CI/CD統合：ファイル変更時にビルド、テスト、デプロイをトリガー

• プロジェクト管理：Jira、GitHub、Linearで課題を自動作成・更新

• チームコミュニケーション：変更時にSlackやTeamsへ更新を投稿

• コードレビュー：プルリクエストを自動作成し、GitHub/GitLabでレビューを管理

• 外部解析：SonarQube、CodeClimate、Snykなどでエンタープライズ向けコードスキャン

• カスタムツール：社内システムや独自ワークフローと統合

• IDE拡張：カスタムコマンドやナビゲーション補助を追加

プラグインはレジストリから導入するか、組織内で独自開発し、反応させるイベントを設定します。Hooksとプラグインを組み合わせることで、既存インフラに適応する拡張可能なプラットフォームが構築できます。

その他の高度な機能

2026年には、Claude Codeの利用範囲を広げるいくつかの主要機能が追加されています。

• プランモード：コードを書く前に詳細な実装計画を作る設計優先のワークフロー。非自明なタスクで活用しています。
• オートモード：許可の中断を減らすパーミッションクラスifier。ファイル書き込みの都度承認したくない長時間タスクに有用。
• Routines：cron、GitHubイベント（PR作成など）、Webhookで起動するスケジュール実行のクラウドエージェント。ローカルマシンは不要。
• IDE統合：VS Code、Cursor、JetBrains向け公式拡張。インラインdiff、チェックポイント、マルチセッション対応。
• リモート操作とChannels：携帯や他デバイスからClaude Codeセッションを操作。

まとめ

このチュートリアルでは、SupabaseのPython SDK内のファイルを題材に、Claude Codeでリファクタリング、ドキュメント化、デバッグを行いました。可読性を高め、構造化されたドキュメントを追加し、インポート問題を解決しました。

Claude Codeはプランモード、オートモード、Routinesなど継続的に進化しています。自身のプロジェクトで試し、ワークフローへの適合性を検証してみてください。

次のステップとして、Claudeのコンテキストウィンドウを最大限に活用する方法を解説したClaude Codeベストプラクティスのチュートリアルをご一読ください。ゼロからプロジェクトを構築したい場合は、Spec-Driven Development with Claude Codeのチュートリアルをおすすめします。