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

Claude Codeとは？

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

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

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

オープンソースでもエンタープライズ規模のコードベースでも、Claude Codeはコーディングスタイルや要件に適応するインテリジェントな自動化を提供します。 最近のアップデートでは、承認の中断を減らすautoモード、設計を優先するplanモード、そしてマシンが起動していなくてもトリガーで動作するクラウドエージェント「Routines」が追加されました。

このサービスが特に役立つユーザー像は次のとおりです。

• ソフトウェア開発者：コード品質と保守性の向上。
• オープンソース貢献者：不慣れなコードベースの理解と改善。
• 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）の全加入者が利用できます。

また、xAIのターミナルエージェントとの比較検討には、Grok Build vs. Claude Codeの比較記事で同一タスクに対するテスト結果をご覧ください。

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

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

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

オペレーティングシステムとターミナルに応じて、以下のいずれかのコマンドをターミナルで実行し、簡単にインストールできます。

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（PostgreSQL上に構築されたバックエンド・アズ・ア・サービス）を使用します。Supabaseは認証、リアルタイム購読、ストレージ、自動生成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で次の対応を行います。

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

ステップ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に次の改善を施しました。

• インポートの整理:  Claude Code は関連するインポートを論理的なセクション（認証エラー、API型、関数エラー）にグループ化し、明確化のために名称を調整し、冗長なエイリアスを削除して一貫性を持たせました。
• 可読性の向上: セクションコメントを追加してインポートを分類し、よりクリーンにするため__all__リストの重複を取り除きました。
• クライアントオプションの簡素化: 類似のインポートを単一の文にまとめ、行数を削減しました。

オリジナルとリファクタ後のコードを並べて比較します。

コードのドキュメント化

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

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

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

リファクタ済みコードとドキュメント追加後のコードの比較です。

プロンプト：client.pyの理解を深めるため、コメントを追加してドキュメント化してください。

ドキュメントを追加したら、次のようにプロンプトしてプロジェクト標準への準拠を確認できます。

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

バグ修正

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

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

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

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

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

オリジナルと修正後のコードを並べて比較します。

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

Claude Codeのコマンド

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

さらに詳しくは、Claude Codeのスラッシュコマンドガイドをご覧ください。

高度なClaude Code機能

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

Claude Code hooks

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

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

• イベント: いつフックを起動するか？

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

• コマンド: 起動時に何を実行するか？

たとえば、ClaudeがPythonファイルを書き込んだ直後にblackを自動実行して整形するように設定できます。Hooksは発生事象に関するJSONコンテキストを受け取り、ファイル種別やパスに基づいた判断が可能です。Claudeのトランスクリプトへ出力したり、エラーメッセージを直接送信して操作をブロックしたりできます。

Hooksの一般的なユースケースは次のとおりです。

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

• テスト: 変更後にテストスイートを実行して早期にバグを検出

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

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

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

• 通知: 重要ファイルの変更時にSlackでチームへ通知

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

HooksはClaude Code内の/hooksコマンドで設定するか、~/.claude/settings.jsonを直接編集して構成します。

Claude Codeプラグイン

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

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

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

Claude Codeプラグインが得意なタスクは次のとおりです。

• CI/CD統合: ファイル変更時にビルド、テスト、デプロイを起動

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

• チーム連絡: 変更時にSlackやTeamsへ更新を投稿

• コードレビュー: プルリクエストの自動作成とGitHub/GitLabでのレビュー管理

• 外部解析: SonarQube、CodeClimate、Snykを呼び出してエンタープライズ向けコードスキャン

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

• IDE拡張: カスタムコマンドやナビゲーションヘルパーの追加

プラグインはレジストリからインストールするか、組織内で自作して導入できます。反応するイベントを設定し、Hooksと組み合わせることで、既存インフラに適応する拡張性の高いプラットフォームを構築できます。

その他の高度な機能

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

• Planモード: コードを書き始める前に詳細な実装計画を作成する、設計優先のワークフロー。非 trivial なタスクには特に有用です。
• Autoモード: 許可判定を行う分類器により中断を減らします。ファイル書き込みごとの承認を避けたい長時間タスクに便利です。
• Routines: cron、GitHubイベント（PR作成など）、Webhookで起動するスケジュール実行のクラウドエージェント。ローカルマシンは不要です。
• IDE連携: VS Code、Cursor、JetBrains向けの公式拡張（インラインdiff、チェックポイント、マルチセッション対応）。
• リモート操作とChannels: スマホや他デバイスからClaude Codeセッションを操作できます。

まとめ

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

Claude Codeはplanモード、autoモード、Routinesなど進化を続けています。ご自身のプロジェクトでも試し、ワークフローへの適合度を探ってみてください。

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