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

AnthropicのClaude Codeを使い、SupabaseのPythonライブラリを題材にソフトウェア開発ワークフローを改善する方法を学びます。

更新 2026年7月21日 · 12 分読む

AIで探索

Claude CodeはAnthropicが開発したエージェント型のコーディングツールで、ターミナル上で直接動作し、リファクタリング、ドキュメント化、デバッグを効率的に支援します。コードベース全体を把握することで、ソフトウェア開発ライフサイクル全体にわたるワークフローを簡素化します。2026年1月以降、AnthropicはClaude Code 2.1、Claude Cowork、そしてMaxプランのデフォルトモデルとしてClaude Opus 4.7を提供しています。

このチュートリアルでは、Claude Codeを使ってコードのリファクタリング、ドキュメント化、デバッグを行い、開発ワークフローを改善する方法を解説します。具体的には、次の内容を扱います。

コードの可読性と保守性を高めるため、supabase-pyリポジトリから1ファイルをリファクタリングします。
既存コードベースの理解を深めるため、ドキュメントとインラインコメントを追加します。
Claude Codeのデバッグ機能を使ってエラーを特定・解消します。

より効率的で自動化された開発体験のために、Claude Codeを開発プロセスへ統合する方法を学びます。

Claude Codeが初めての方は、このチュートリアルと並行してClaude Code 101コースの受講をおすすめします。

TL;DR

Claude CodeはAnthropicのターミナルベースのエージェント型コーディングアシスタントで、Maxプランでは現在Claude Opus 4.7が動作
curl -fsSL https://claude.ai/install.sh | bash（macOS/Linux）またはWindowsのPowerShell/CMD相当のコマンドでインストール
自然言語で、コードベース全体にわたりリファクタリング、ドキュメント化、デバッグが可能
主な機能はplan mode、auto mode、hooks、plugins、Routines（スケジュール実行のクラウドエージェント）
/modelでモデルを切り替え、/effortで推論の深さを調整

Claude Codeとは？

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

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

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

オープンソースからエンタープライズ規模のコードベースまで、Claude Codeはコーディングスタイルや要件に適応するインテリジェントな自動化を提供します。最近のアップデートでは、許可リクエストが少ないauto mode、設計優先のplan mode、そしてマシンを起動せずにトリガーで動作するスケジュール実行のクラウドエージェント「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で移行できます。

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

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で次のことを行います。

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

ステップ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はプロジェクト全体のコードドキュメントを生成・更新・標準化できます。未ドキュメント箇所の特定、構造化されたドックストリングやコメントの生成、プロジェクト標準への準拠確認が可能です。

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

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

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

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

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

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

バグ修正

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

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

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

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

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

元コードと修正後コードの比較です。

プロンプト: 「Import gotrue.errorsが解決できない」などの不具合が見られます。client.py内のエラーをすべて修正してください。

Claude Codeのコマンド

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

コマンド	アクション
`/model`	利用可能なモデル間で切り替え（Opus 4.7、Sonnet 4.6、Haiku 4.5）
`/effort`	推論の深さを調整（low、medium、high、xhigh、max）
`/plan`	設計優先のplan modeに入る
`/ultrareview`	変更内容のマルチエージェントコードレビュー
`/clear`	会話履歴をクリアしてコンテキストを解放
`/compact`	会話履歴をクリアし、要約のみをコンテキストに保持
`/cost`	現在のセッションの合計コストと所要時間を表示
`/doctor`	Claude Codeのインストール状態（バージョンや更新状況を含む）をチェック
`/help`	ヘルプと利用可能なコマンドを表示
`/init`	コードベースのドキュメントを含む`CLAUDE.md`を新規作成
`/hooks`	自動化フックの設定と管理
`/review`	プルリクエストをレビュー
`/config`	権限を含むClaude Codeの設定を表示・変更
`/usage`	使用量上限の要因（セッション、キャッシュ、コンテキスト）を表示

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

高度なClaude Code機能

リファクタリングやデバッグの基本に慣れたら、HooksやPluginsで挙動をカスタマイズしてClaude Codeの能力を拡張できます。これらにより、反復作業の自動化や外部システムとの連携が可能になります。

Claude Code hooks

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

Hooksはイベント—アクション方式で、次の3点を定義します。

イベント: いつフックが起動するか
マッチャー: どのアクションに適用するか
コマンド: 起動時に何を実行するか

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

一般的なユースケース：

コード整形: 書き込み後にリンタやフォーマッタを自動実行
テスト: 変更後にテストスイートを実行し、早期に不具合を検出
セキュリティ: 本番設定やAPIキーなど機密ファイルの変更をブロック
ドキュメント: ソース変更時にAPIドキュメントを自動生成
Git自動化: スマートコミット作成やブランチ保護ポリシーの検証
通知: 重要ファイル変更時にSlackでチームへ通知
コンプライアンス: 変更前にライセンスヘッダやコーディング規約を強制

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

Claude Code plugins

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

Pluginsは、サブエージェント（特定タスク用の専門Claudeアシスタント）、MCPサーバー（標準化されたツール連携）、Hooksなど複数コンポーネントを1つのパッケージに束ね、連携してオーケストレーションします。

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

Claude CodeのPluginsが得意なタスク：

CI/CD統合: ファイル変更時にビルド・テスト・デプロイをトリガー
プロジェクト管理: Jira、GitHub、Linearの課題を自動作成・更新
チーム連携: 変更時にSlackやTeamsへ更新を投稿
コードレビュー: PRを自動作成し、GitHub/GitLabでレビューを管理
外部解析: SonarQube、CodeClimate、Snykによるエンタープライズ向けコードスキャン
カスタムツール: 企業独自のシステムやワークフローと連携
IDE拡張: カスタムコマンドやナビゲーション支援を追加

レジストリからPluginsをインストールするか、社内向けに構築して、反応させるイベントを設定します。HooksとPluginsを組み合わせることで、既存インフラに適応する拡張可能なプラットフォームが構築できます。

その他の高度機能

Claude Codeは2026年に、利用範囲を広げる主要機能をいくつか追加しました。

Plan mode: コードを書く前に詳細な実装計画を作成する設計優先のワークフロー。非自明なタスクで特に有用です。
Auto mode: 許可の中断を減らすための権限分類器。すべての書き込みを承認したくない長時間タスクに便利です。
Routines: cron、GitHubイベント（例：PR作成）、Webhookで起動するスケジュール実行のクラウドエージェント。ローカルマシンは不要。
IDE統合: VS Code、Cursor、JetBrains向けの公式拡張を提供。インライン差分、チェックポイント、マルチセッション対応。
Remote controlとChannels: スマホなど他デバイスからClaude Codeセッションを操作。

まとめ

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

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

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

Claude Codeを使うには有料サブスクリプションが必要ですか？

Claude CodeはPython以外の言語でも使えますか？

Claude Codeのhooksとpluginsの違いは何ですか？

Hooksは、特定イベント時にローカルのシェルコマンドを実行するシンプルな自動化（例：ファイル書き込み後にコード整形）です。Pluginsは、Jira、Slack、GitHub、社内ツールなど外部システムとClaude Codeを統合する強力な拡張機能です。PluginsはHooks、サブエージェント、MCPサーバーを束ね、複雑な多段ワークフローに適しています。ローカル自動化にはHooks、エコシステム全体の統合にはPluginsを使います。

Claude Codeはコードベース全体にアクセスできますか？

Claude Codeはチームで使えますか？個人向けのみですか？

Claude Codeはチームでも有効です。プロジェクトの.claude/settings.jsonにMCPサーバーやHooksなどの構成を保存して、バージョン管理にコミットすれば、チーム全体で共有できます。Pluginsの動作もチームで一貫します。ただし、各メンバーは個別のClaudeサブスクリプションまたはAPI課金が必要です。エンタープライズ環境向けには、集中管理と共有ワークスペースを備えたTeamsおよびEnterpriseプランがあります。