結論
Claude CodeをPython開発に使うときは、いきなり実装を依頼するより、最初にリポジトリの構成・既存テスト・実行コマンドを確認し、変更範囲を絞ると進めやすくなります。Anthropicの公式ガイドもコードベースを調べ、プロジェクトの既存パターンに合わせてテストを書き、実行して確認する流れを紹介しています。
ここでは、すでにPythonプロジェクトを開ける状態を前提に、調査から差分確認までの手順を整理します。Claude CodeがPythonの動作を保証するわけではないため、最後は実際のテスト結果と変更内容を自分で確認してください。
Pythonの設定と既存テストの確認
Claude CodeのQuickstartは、端末でプロジェクトを開き、コードベースを調べて最初の変更を行う手順です。言語別の専用モードを前提にせず、公式のCommon workflowsはテスト追加時に既存のテストファイルを調べ、フレームワークやアサーションの書き方を合わせる方法を案内しています。
Pythonではまずリポジトリにある設定を読みます。たとえば pyproject.toml、pytest.ini、tox.ini、requirementsファイル、uv.lock、poetry.lock などです。すべてのプロジェクトに全ファイルがあるとは限りません。ここで確認したいのは、使っているPythonのバージョン、依存関係の管理方法、テストの配置、既存の実行コマンドです。
Claude Codeをプロジェクトのルートで起動し、最初は調査だけを頼みます。たとえば次のように伝えます。
このPythonリポジトリを読み取り専用で調べてください。Pythonのバージョン、依存関係の管理方法、テストフレームワーク、既存のテスト実行コマンドを、確認したファイル名と一緒に示してください。ファイル変更、パッケージ追加、コマンド実行はまだしないでください。見つからない項目は推測せず、不明と書いてください。
この段階で、Claude Codeの説明と実際の設定ファイルが合っているかを見ます。構成の説明だけでテストの実行方法が分からない場合は、READMEやCI設定など、根拠になりそうなファイルを追加で確認してください。
変更前に対象・受け入れ条件・テストを決める
「この関数を直して」だけではどの入力や既存動作を守るのかが曖昧です。依頼を出す前に、変更する対象、変えてよい動作、維持する動作、確認方法を短く書きます。
たとえば、次の項目を明示します。
- 対象：変更したいモジュールや関数名。
- 目的：修正する不具合、追加する処理、利用者が見る結果。
- 制約：公開API、既存データ形式、他のモジュールとの互換性で変えないもの。
- テスト：既存テストのどれを実行し、どの結果を確認するか。
- 変更範囲：依存関係の追加、ロックファイル更新、外部通信を許すか。
具体的な再現例や期待結果が分かるなら、入力と出力をそのまま示してください。情報がない場合は、Claude Codeに不足点と前提候補を先に列挙させ、実装の前に確認します。テストが存在しない場合も、存在しないテスト設定を前提にせず、既存設定から追加先と実行方法を決めます。
変更が広い場合は、公式のpermission modes資料が説明するPlan Modeを使い、編集前に対象ファイル・変更案・テスト案を確認できます。Plan Modeの編集制限には権限設定による例外もあるため、利用中の設定を確認してください。切り替え方と例外は公式のpermission modes資料を参照できます。
1つの小さな変更から実装を頼む
依頼は一度に全面的なリファクタリングまで含めず、検証できる単位に分けます。たとえば「対象関数の境界条件を修正し、同じ動作を守るテストを追加する。関係のない整形や別モジュールの整理はしない」と伝えます。
テストについては公式ワークフローのように、まず未テストの箇所を特定し、既存テストのパターンに沿ってテストを追加し、通常ケースと境界条件を確認する順が使えます。Pythonであれば、プロジェクトがpytestを使っているのか、標準のunittestを使っているのかを、設定と既存ファイルから確認してから依頼します。フレームワークを推測で決めないでください。
作業中にClaude Codeが新しい依存関係の追加、外部サービスへの接続、データ変換などを提案したら、目的と影響を分けて確認します。とくにロックファイルの更新やインストールは、依頼に含めていなければ実行前に差し戻してください。Claude Codeが操作できる範囲は、利用中のpermission modeや確認設定にも左右されます。
テストの実行と差分確認
実装後はまず変更箇所に近いテストをプロジェクトの既存コマンドで実行します。pytestやunittestなどの名称だけを見て、新しい実行方法を決めないでください。CIやREADMEに記載されたコマンドがある場合は、それを先に確認します。次に、影響範囲に応じて関連テストや全体のテストを実行します。
テストが失敗したら、失敗したコマンド、対象テスト、エラー出力を見て、コードの失敗と環境・依存関係の失敗を分けます。Claude Codeには「失敗を直して」とだけ頼まず、失敗したテストが確認する仕様、変更との関係、次に必要な検査を説明させます。実行結果を読まず、実装案だけで成功と判断しないようにします。
最後にGitの差分を確認します。変更したファイルが依頼した範囲に収まっているか、テストが意図した動作を検証しているか、設定・ロックファイル・生成物が不要に変わっていないかを読みます。Claude Codeが「テスト成功」と報告した場合も、表示されたコマンドと終了結果を確認し、別の環境で実行した説明と混同しないでください。
Claude CodeをGitHub上の作業に接続する場合は、Claude Code GitHub連携の記事で認証と安全な試験を確認できます。前の会話を再開して作業する場合はcontinue・resumeの使い分けを参照してください。作業の基本的な導入方法はClaude Codeのインストール記事にまとめています。
Pythonプロジェクトで使う依頼文のひな形
次のひな形は対象と受け入れ条件を明確にするための例です。角括弧の箇所はリポジトリの実情に置き換えてください。
対象は [モジュール・関数] です。現在の動作と関連テストを先に読み、確認したファイル名を示してください。期待する動作は [入力条件と期待結果] です。既存の公開APIとデータ形式を維持し、変更は必要なファイルに限ってください。依存関係の追加と外部通信は行わないでください。まず変更案とテスト案を説明し、承認後に実装してください。実装後は既存の方法で関連テストを実行し、コマンドと結果を報告してください。
この指示は実際のリポジトリにないテスト設定を作らせないための出発点です。プロジェクトの制約に合わせて、許可する操作や確認項目を調整してください。依頼文だけで権限や安全性が変わるわけではありません。画面に出るpermission modeと操作の承認表示を確認します。
よくある質問
公式ガイドにPython向けの特別なテスト手順はありますか？
ここで参照したQuickstartとCommon workflowsは、端末から既存プロジェクトを調べ、既存のテストパターンに合わせて作業する一般的な流れを説明しています。Python固有のテスト方式は指定されていないため、実際のリポジトリの設定とテストファイルを確認して進めます。
pytestがなければ、Claude Codeに新しく入れてもらえばよいですか？
まず既存のテスト方式と依存関係管理を確認します。新しいフレームワークやパッケージの追加は、目的と影響を確認し、必要な場合に限って決めてください。
Claude Codeがテスト成功と言えば、変更を完了扱いにできますか？
報告だけでは判断できません。実行したコマンド、対象テスト、実際の終了結果を確認し、変更差分とテスト内容が受け入れ条件を満たすかを見ます。
チームでPython開発へ導入する前に相談できますか？
利用するリポジトリ、作業範囲、承認方法、テスト運用を整理してから判断します。外注費とAI活用の対象を含む業務全体を検討する場合は、Miraigentの無料診断で診断対象と条件をご確認ください。個別のClaude Code導入支援を約束するページではありません。