結論：Claude Code を使った Python 開発は「環境と依存の整理」「既存コードの把握」「型ヒント・テスト前提の実装」「人によるレビュー」をワンセットで回すと、生成コードを鵜呑みにせず安全に速度を出せます。
- 要点1：最初に仮想環境とパッケージ管理（venv / uv）の方針を Claude Code に伝えると、依存まわりの手戻りが減る
- 要点2：型ヒント・docstring・pytest をセットで指示し、生成直後に
ruff/mypy/pytestを走らせて自分の目で確認する - 要点3：生成コードはライブラリのバージョン差や非推奨 API を拾うことがあるため、最終確認は必ず人間が行う
対象読者：Claude Code を Python のスクリプト・ツール・小〜中規模アプリ開発に使い始めたい開発者・エンジニア（環境構築は一通り経験済み）
今日やること：自分のリポジトリで claude を起動し、まず「この依存構成と Python バージョンを把握して」とだけ投げて、現状把握から始める
「Claude Code で Python を書かせると、それっぽいコードはすぐ出てくるんだけど、いざ動かすと依存が足りなかったり、古い書き方だったりするんですよね」
これは、実際に Python プロジェクトへ Claude Code を導入したチームでよく聞く話です。正直に言うと、原因の多くは「ツールが悪い」のではなく「環境・依存・既存コードの前提を最初に渡していない」ことにあります。Claude Code はターミナルやIDE上でコードベースを読み、ファイルを編集し、コマンドを実行できるエージェント型のコーディングツールです（code.claude.com 公式・2026年6月時点）。だからこそ、人間側が「どの環境で、どのバージョンで、何を前提に書くか」を渡せるかどうかで、出力の質が大きく変わります。
この記事では、Python 開発を Claude Code で効率化する実践的な進め方を、①環境・依存の整理 ②既存コードの把握 ③実装の進め方 ④テストと動作確認 ⑤よくある作業の効率化 ⑥落とし穴、の順で、具体的な指示例とコード例つきで解説します。なお本記事のコマンド・機能名は2026年6月時点の公式ドキュメントに基づきますが、Claude Code・各ライブラリともに更新が早いため、最新仕様は必ず公式ドキュメントで確認してください。
1. 環境・依存の整理：最初に「方針」を渡す
Python 開発でいちばん最初に詰まりやすいのが、仮想環境とパッケージ管理です。ここを曖昧にしたまま「実装して」と頼むと、Claude Code はそれっぽい import を書いてくれますが、手元で動かない、という状態になりがちです。
仮想環境とパッケージ管理の方針を決める
まずは仮想環境を用意します。標準ライブラリの venv は追加インストール不要で確実です（Python 公式ドキュメント）。
python3 -m venv .venv
source .venv/bin/activate # Windows は .venv\Scripts\activate
python -m pip install --upgrade pip近年は高速なパッケージ・プロジェクト管理ツール uv を使うチームも増えています（Astral 公式ドキュメント・2026年6月時点）。どちらを使うかは好みとプロジェクト方針によりますが、大事なのは「使うものを最初に Claude Code へ伝える」ことです。
Claude Code への最初の指示例
環境方針を明示したうえで、現状把握を頼みます。
このリポジトリの Python バージョン、依存関係（pyproject.toml / requirements.txt）、
仮想環境の前提を把握して、現状を要約してください。
- 環境は .venv（標準 venv）を使います
- Python は 3.12 を前提とします
不足している情報があれば、最初に質問してから作業を開始してください。
仮定した点は必ず"仮定"と明記してください。「不足があれば質問して」「仮定は明記して」の2行を添えるだけで、依存の取り違えがかなり減ります。Claude Code はコードベース全体を読んで複数ファイルにまたがって作業できるので、先に全体像を要約させると、その後の実装指示が通りやすくなります（code.claude.com 公式）。
2. 既存コードの把握：CLAUDE.md とプラン確認を使う
既存プロジェクトに後から入る場合、いきなり実装させると既存の設計と噛み合わないコードが出てきます。ここで効くのが、プロジェクト方針を渡す仕組みと、実装前にやり方を確認する進め方です。
CLAUDE.md にプロジェクトの前提を書く
CLAUDE.md はプロジェクトルートに置くマークダウンファイルで、Claude Code が各セッションの冒頭で読み込みます。コーディング規約・アーキテクチャの決定・推奨ライブラリ・レビュー観点などを書いておくと、毎回同じ前提で作業させられます（code.claude.com 公式）。Python プロジェクトなら、たとえば次のような内容です。
# CLAUDE.md（例）
## 開発環境
- Python 3.12 / 仮想環境は .venv
- パッケージ管理は uv（uv add で追加）
## コード規約
- 型ヒント必須。公開関数には docstring を書く
- Lint/format は ruff、型チェックは mypy
- テストは pytest。新規関数には必ずテストを追加
## 注意
- 非推奨 API は使わない。バージョン差がある場合は確認を入れる実装の前に「やり方」を確認させる
Claude Code には、すぐコードを書き始めるのではなく、まず方針を提示してもらう進め方が向いています。大きめのタスクほど、いきなり全部書かせるより、最初に段取りを確認したほうが手戻りが減ります。
この機能を追加したいのですが、まずファイルを書き換える前に、
変更するファイル・追加する関数・テスト方針の計画だけ提示してください。
合意できたら実装に進みましょう。計画段階で「そのライブラリは使いたくない」「この層には手を入れないで」と軌道修正できるので、失敗1（後述）の「一度に全部やらせて崩れる」を避けられます。
3. 実装の進め方：型ヒント・docstring・ライブラリ選び
Python は動的型付け言語ですが、Claude Code に書かせるときこそ型ヒントが効きます。型を明示しておくと、生成コードの意図が読み取りやすく、レビューも速くなります。
型ヒントとテストをセットで指示する
関数を実装させるときは、シグネチャ・型・テストを同時に頼みます。Python の型ヒントは typing モジュールと標準構文でサポートされています（Python 公式ドキュメント）。
次の仕様で関数を実装してください。
- 関数名: load_users(path: str) -> list[dict[str, str]]
- CSV を読み込んで辞書のリストで返す
- 型ヒントと docstring を付ける
- 同時に pytest のテストも作成（正常系・空ファイル・存在しないパス）
標準ライブラリで実装できる範囲は外部ライブラリを足さないでください。「標準ライブラリで足りるなら依存を増やすな」と添えるのがポイントです。Claude Code は便利なライブラリを提案してくれますが、放っておくと依存が増えがちなので、追加の可否は人間が判断します。
ライブラリ選びは「理由」を聞く
外部ライブラリを使う場合は、候補と選定理由を出させてから決めます。
この処理に使える Python ライブラリを2〜3個挙げ、
それぞれのメンテナンス状況・依存の重さ・向き不向きを比較してください。
推測の場合は"推測"と明記してください。ここで返ってくる情報は便利ですが、メンテ状況や最新バージョンは変わるため、最終的には PyPI や各ライブラリの公式ドキュメントで自分で裏取りします。
4. テストと動作確認：生成直後に必ず走らせる
Claude Code の強みは、コードを書くだけでなくコマンドを実行してテストまで回せる点です（code.claude.com 公式）。Python なら pytest との相性が良く、「テストを書いて、実行して、落ちたら直して」までを一括で頼めます。
pytest を前提に依頼する
pytest は Python で広く使われるテストフレームワークです（pytest 公式ドキュメント）。次のように依頼すると、実装→テスト→修正のループを Claude Code 側で回してくれます。
auth モジュールにテストを書いて、pytest を実行し、
失敗したテストがあれば原因を特定して修正してください。
修正のたびに、何をなぜ変えたかを1行で説明してください。自分の手元でも必ず確認する
Claude Code が「テストが通った」と言っても、最後は自分でも回します。手元の確認手順の例です。
ruff check . # Lint
mypy src # 型チェック
pytest -q # テストここで落ちる場合、生成コードがローカル環境のバージョンと噛み合っていないことがあります。エラーメッセージをそのまま Claude Code に貼って「この環境で落ちた、原因を追って」と頼むと、コードベースをたどって原因を特定し、修正を実装してくれます（code.claude.com 公式）。デバッグの進め方はClaude Code デバッグ・トラブルシューティングガイドでも詳しく扱っています。
5. よくある作業の効率化：パイプ・スクリプト・繰り返し
日々の Python 作業には、テスト作成・lint 修正・依存更新・リリースノート作成のような「後回しにしがちな反復作業」が多くあります。Claude Code はこうしたタスクの自動化に向いています（code.claude.com 公式）。
定型作業を一言で頼む
- 未テストコードへのテスト追加：「テストのない関数を洗い出して、優先度の高いものから pytest を書いて」
- Lint エラーの一括修正：「ruff のエラーをプロジェクト全体で直して。挙動が変わる修正は事前に教えて」
- 依存の棚卸し：「pyproject.toml の依存で、未使用・重複・古いものを洗い出して。更新は私が判断する」
CLI と組み合わせて流す
Claude Code は Unix 哲学に沿って組み合わせられ、-p オプションで非対話的にも実行できます（code.claude.com 公式）。たとえば変更ファイルだけをレビューさせる使い方です。
git diff main --name-only | claude -p "これらの変更ファイルを、Python の観点でレビューしてください"こうした反復作業や品質チェックの自動化は、Claude Code でのQA・テスト自動化ガイドと合わせて読むと、ワークフロー全体を組み立てやすくなります。
6. 落とし穴：生成コードを鵜呑みにしない
ここまで効率化の話をしてきましたが、いちばん大事なのは「最後の判断は人間が持つ」ことです。正直にお伝えすると、生成コードはまだ完璧ではありません。だからこそ「AI に丸投げ」ではなく「AI と協業」が正しいアプローチです。
【要注意】よくある失敗パターンと回避策
失敗1：一度に全部やらせて構造が崩れる
❌「このアプリ全体をリファクタリングして」
⭕「まず認証モジュールだけ、変更計画を出してから着手して」
なぜ重要か：大きなタスクは分割して段階的に進めると、各ステップで軌道修正でき、最終品質が上がります。
失敗2：ライブラリ・バージョン差を見落とす
❌ 生成された import や API をそのままマージ
⭕「この書き方が、手元の依存バージョンで非推奨になっていないか確認して。確認できない場合は”未確認”と書いて」
なぜ重要か：生成コードは古いAPIや別バージョン向けの書き方を拾うことがあります。バージョン差は実行・テストと公式ドキュメントで確かめます。
失敗3：テスト結果を鵜呑みにする
❌「テストが通った」と言われて即マージ
⭕ 手元でも pytest / mypy / ruff を回し、テスト自体が妥当か（カバー範囲・アサーション）を人間がレビュー
なぜ重要か：テストが通ること自体が、テストが正しいことを意味しません。数字・固有名詞・最新情報は、AI 単体での正確性に限界があります。
セキュリティと機密情報
API キーや個人情報をプロンプトやコードに直接書かないこと、生成された外部通信・ファイル操作のコードは中身を確認することは、Python 開発でも変わりません。Claude Code の権限・実行範囲の設定は更新されることがあるため、最新の挙動は公式ドキュメントで確認し、所属組織の規程・コンプライアンスに従ってください。コメントや docstring の整え方はClaude Code でのコメント・docstring活用ガイドも参考になります。
まとめ：今日から始める3つのアクション
- 環境方針を最初に渡す：
claudeを起動し、「Python バージョン・依存・仮想環境を把握して」と現状把握から始める - CLAUDE.md を1枚用意する：型ヒント・docstring・pytest・lint 方針を書き、毎回同じ前提で書かせる
- 生成直後に自分で回す：
ruff/mypy/pytestを手元で実行し、最終判断は人間が持つ
Claude Code を「速く書く道具」ではなく「現状把握・実装・検証を一緒に回す相棒」として使うと、Python 開発の手戻りは確実に減ります。より体系的なテクニックはClaude Code 実践テクニック完全ガイドにまとめています。
著者プロフィール
佐藤傑（さとう・すぐる）。株式会社Uravation代表取締役。X（@SuguruKun_ai）フォロワー約10万人。100社以上の企業向けAI研修・導入支援を手がける。著書『AIエージェント仕事術』（SBクリエイティブ）。
