Python(FastAPI)とReactを同一リポジトリで管理するモノレポ構成において、Claude Codeを導入して自動リファクタリングやテスト自動化を試みていたところ、環境変数の読み込みや仮想環境のパスでハマったので備忘録として残します。
この記事でわかること
- Claude Codeのツール実行時にパスが通らない原因
- モノレポ構成におけるPython venvの適切なアクティベート方法
- .envファイルを確実にClaude Codeへ認識させる起動スクリプトの書き方
[現象] ツール実行時にエラーが発生
Claude Code上で /run pytest を実行した際や、自動エージェントがテストを回そうとした時に、以下のようなエラーに遭遇しました。
Tool execution failed: bash: pytest: command not found
# あるいは環境変数の未定義エラー
RuntimeError: Environment variable 'DATABASE_URL' is not set during Claude Code's automated tool usage.[環境] モノレポ構成の構成
今回ハマった環境は以下の通りです。
| プロジェクト | Python (FastAPI) + React |
| 構成 | モノレポ (同一Gitリポジトリ内にbackend/ frontend/) |
| パッケージ管理 | Python venv + npm |
| ツール | Claude Code (claude-code) |
[原因] サブプロセスへの環境継承不足
原因を調査したところ、Claude Codeのツール実行用サブプロセスは、ユーザーが普段使っている対話型シェル（.zshrcや.bashrc）のエイリアスや、IDEが自動ロードする仮想環境（venv）を完全に引き継がないことが分かりました。
特にdirenvやVS Codeの自動アクティベート機能に依存している場合、Claude Code内部でbashが立ち上がった瞬間にパスが通っておらず、pytestなどのコマンドが見つからない状態になります。また、.envファイルの内容も明示的にロードしない限り、サブプロセスからは参照できません。
[解決策] 明示的な環境注入スクリプト
この問題を解決するには、Claude Codeを起動する際に仮想環境と環境変数を明示的に注入する必要があります。
Before: 失敗する起動方法
# 単に起動するだけだと、サブプロセスでパスが切れる
claudeAfter: 成功する起動方法（ラッパースクリプト例）
プロジェクトルートに claude-dev.sh などの名前で以下のコマンドを用意し、実行権限を与えて使用します。
# 仮想環境をアクティベートし、.envを読み込んでからClaudeを起動
source .venv/bin/activate && export $(grep -v '^#' .env | xargs) && claudeまた、Claude Codeとの対話中に特定のパスを指定するよう指示することも有効です。例えば、テスト実行を依頼する際に「./node_modules/.bin/vitest を使って」や「backend/.venv/bin/pytest を使って」と明示的にパスを伝えます。
[まとめ] Claude Codeを使いこなすために
Claude Codeは非常に強力ですが、実行環境（ランタイム）の制御については、まだユーザー側での明示的な設定が必要なケースが多いです。特にPython venvやモノレポ構成では、以下の3点を意識しましょう。
- 起動前に venv を activate する。
- .env の変数を export して環境に流し込む。
- Claudeへのプロンプトで実行ファイルの相対パスを明示する。
これだけで、環境変数エラーで止まることなく、スムーズな自動コーディング体験が得られるようになります！
