「Pythonプロジェクトで Claude Code を使いたいんですけど、仮想環境とかどうするんですか」 — 研修先で頻発する質問です。Pythonは仮想環境やパッケージマネージャの選択肢が多く、Claude Codeとの組み合わせで戸惑う人が多い。

この記事は、Pythonプロジェクトで Claude Code を運用する時の現実を、私の半年の運用から整理したものです。

まず仮想環境の話から

Pythonでは仮想環境(virtual environment)が常識です。Claude Code を使う前に、自分のプロジェクトでどの仮想環境が動いているかを確認するのが先。

主流の選択肢を表で並べます。

ツール

特徴

Claude Codeとの相性

venv(標準)

軽量・標準・どこでも動く

良。最も素直

poetry

依存解決と仮想環境を一体管理

良。poetry run の前提で書く

uv

高速、Rust製の新興

良。最近Claude Codeでも安定

pyenv

バージョン管理

良(virtualenv 併用が前提)

どれでも動きますが、Claude Codeに「テストを実行して」と頼む時の挙動は、仮想環境の起動状況で変わります。

Claude Codeに仮想環境を意識させる

Claude Code は起動時のシェル環境を引き継ぎます。だから、仮想環境がアクティブな状態で claude を起動すれば、その仮想環境内でコマンドを実行してくれます。

# venvを有効化してからClaude Codeを起動
source .venv/bin/activate
claude

これで、Claude Codeが pytest や python を呼ぶ時に、仮想環境のものが使われます。

poetryの場合は次のような流れが楽です。Poetry 2.0以降は poetry shell が削除されたので、eval $(poetry env activate) か poetry run が現行の正解です。

# Poetry 2.0以降で仮想環境をアクティブ化してclaudeを起動
eval $(poetry env activate)
claude

# またはClaude Code起動を1コマンドで包む
poetry run claude

CLAUDE.mdに「このプロジェクトはpoetryを使っている」と書いておくと、Claudeが poetry run を前置する判断をしてくれます。

CLAUDE.mdの書き方テンプレート

claudecodelab.jp

テスト実行の自動化

Pythonプロジェクトで Claude Code が一番効くのは、テスト実行と修正のループです。

「このテストを走らせて、失敗したら直して」と頼むと、pytest を実行→失敗箇所を読み→修正→再実行、というサイクルをClaudeが回します。

# Claude Codeに頼む例
$ claude
> tests/test_user_service.py のテストを通るようにしてください。
> 失敗したら原因を読んで修正してから再実行を3回まで試してください。

私の運用では、テスト主導で進める案件はこのパターンが頭ひとつ抜けて楽です。

Claude Codeを安全に運用する3層チェック体制の作り方

claudecodelab.jp

型ヒント(mypy)とのスムーズな連携

Pythonの型ヒント(typing hints)を Claude Code は適切に扱えます。

mypy のエラー出力を貼って「これを直して」と頼むと、型修正と関連ロジックの調整をまとめて提案してくれる。型をしっかり書いているプロジェクトほど、Claude Code との相性が良くなります。

CLAUDE.mdに「このプロジェクトは型ヒント必須」と書いておけば、新規追加コードにも自動で型を付けてくれる。これは地味だけど効きます。

データサイエンス系の使いどころ

Pythonの中でも、データサイエンス系(pandas, numpy, jupyter)の作業はClaude Codeの効きが特に良いです。

具体例として、私が研修先でやって効いた例を挙げます。

  • CSVデータの集計コードのドラフト(pd.groupby + 集計関数の組み合わせ)
  • データクリーニング(欠損値処理・型変換・異常値検出)のスクリプト
  • Jupyter notebookで実行する分析コードの設計と検証
  • 散布図・棒グラフなどの可視化コード(matplotlib / plotly)

「PythonでデータサイエンスをやりたいけどPandasが苦手」という研修先の方には、Claude Codeに任せれば、最初のたたき台が3分で出ます。

仮想環境がないプロジェクトは要注意

正直に書きます。仮想環境を切らずにシステムPythonで作業しているプロジェクトでは、Claude Codeに pip install を頼むのは避けたほうが安全です。

システムPythonを汚す pip install は、別のアプリの依存と衝突する原因になります。Claude Codeに頼む前に、venv を切る習慣を身につけるほうが先です。

権限管理の話は別記事に。

Claude Codeのpermissionの設定

claudecodelab.jp

permissionsで pip install を「確認(ask)」にしておくと、うっかり走らせる事故が減ります。

私の落としどころ

参考までに、いまの私のPython運用構成を共有します。

新規プロジェクトは uv で初期化。仮想環境とパッケージ管理を一体で済ます。CLAUDE.mdには「uvを使っている」「型ヒント必須」「テストはpytest」と明示。

source .venv/bin/activate してから claude を起動するシェルエイリアスを作っておけば、毎回の起動が1コマンド。これでテストループや依存管理が安定します。

まとめ

  • PythonプロジェクトでのClaude Code利用は仮想環境の状態が肝
  • venv/poetry/uv どれでも動くが、CLAUDE.md で何を使っているか明示すると挙動が安定
  • 仮想環境を有効化してから claude を起動すると、コマンド実行で混乱が起きない
  • テスト実行→失敗→修正のループは Python で Claude Code が一番効く使い方
  • 型ヒント(mypy)が整っているプロジェクトほど相性が良い
  • データサイエンス系(pandas, jupyter)は特に効きが大きい
  • システムPythonで pip install を走らせる事故を避けるため、必ず仮想環境を切る