AIエージェントにDjango開発環境を最新化してもらった

こんにちは、ENECHANGEでエンジニアをしている児玉です。

今回は、Cursorを使ってDjango開発環境をモダナイズした体験談をお話しします。具体的には、古くなった設定ファイル群を整理し、最新のPythonツールチェーンに移行する作業を実施しました。

背景と課題

長期運用されているDjangoプロジェクトでは、以下のような課題を抱えていました：

開発効率の課題

依存関係のインストール時間: 40以上の依存関係により、環境構築に時間がかかる
ツールの実行速度: black + isort + flake8を個別に実行することで、チェック時間が累積
CI/CDの待ち時間: ビルド時間が長く、フィードバックループが遅い

管理面の課題

設定ファイルの分散: setup.cfgとpyproject.tomlに設定が分かれており、管理が煩雑
ツールの分散: フォーマッター、import整理、リンターがそれぞれ別ツールになっており、設定や実行が個別に必要

これらの課題を解決するため、最新のツールチェーンへの移行を検討しました。

Before / After 比較

項目	変更前	変更後
依存関係管理	Poetry	uv
設定ファイル管理	2ファイル	1ファイル
コードフォーマッター	black + isort	ruff
リンター	flake8	ruff
設定ファイル	setup.cfg + pyproject.toml	pyproject.toml のみ

事前準備

移行作業を始める前の環境：

依存関係管理にPoetry使用
40以上の依存関係を持つプロジェクト
Cursorの最新版で作業

既存のプロジェクトでは以下のツールを使用していました：

Poetry: 依存関係管理とパッケージング
black: コードフォーマッター
isort: import文の整理
flake8: リンター
mypy: 型チェック
setup.cfg: 各ツールの設定集約

手順

移行は以下の3段階に分けて実施しました：

段階1: setup.cfg → pyproject.toml への移行
段階2: Poetry → uv への移行
段階3: ruff導入とblack/isort/flake8の削除

段階1: setup.cfg → pyproject.toml への移行

最初の段階では、既存のツール構成を維持したまま、設定ファイルの統合のみを行いました。

Cursorへのプロンプト:

プロジェクトルート上のsetup.cfgをpyproject.tomlへ移行する作業を実施します。

作業ブランチ名: feature/migrate-setup-cfg-to-pyproject-toml

作業ブランチを作成、リポジトリ内容を把握、それぞれのファイルのバックアップを作成して作業を開始してください。

移行対象のツール:
- pytest ([tool:pytest] → [tool.pytest.ini_options])
- isort ([isort] → [tool.isort]) ※既に存在する場合は設定の確認のみ
- mypy  ([mypy] → [tool.mypy])
- flake8 ([flake8] → [tool.flake8]) ※Flake8-pyproject を dev dependencies に追加
- black （新規追加） → [tool.black]

また、以下の確認を実施してください：
1. 移行前の状態記録（各ツールの設定確認コマンドの出力を保存）
2. setup.cfg の削除前後で設定・挙動が変わらないかの検証
3. 検証専用の一時ファイル `tmp_config_check.py` で動作確認
4. black の設定も明示的に追加（line-length = 88, target-version = ['py313']）

実行結果:

Cursorは段階的なアプローチで作業を進めました：

作業ブランチの作成とバックアップ
現在のファイル構造の確認
移行前の状態記録
各ツールの設定移行
移行後の検証
setup.cfgの削除

移行後、同じ検証を実行して動作が一致することを確認しました。

段階2: Poetry → uv への移行

次に、依存関係管理ツールの移行を実施しました。Docker環境やCI/CDも含めた完全移行を行いました。

Cursorへのプロンプト（要点）:

Poetry → uv 完全移行タスクとして依頼
Docker環境での動作を前提とした移行
CI/CD環境も含めた全面的な変更
build-systemの削除（Webアプリでは不要）
docker compose upでの動作確認まで含む移行計画

実行結果:

Cursorは以下の手順で移行を実施：

pyproject.tomlの[tool.poetry]セクションをuv標準形式に変更
poetry.lockからuv.lockへの移行
Dockerfileの修正（Poetry関連をuv対応に変更）
CI/CD設定の更新
Docker環境での動作確認

段階3: ruff導入とblack/isort/flake8の削除

最後に、既存のblack + isort + flake8の組み合わせをruff一つに統合しました。

Cursorへのプロンプト（要点）:

プロジェクトにRuffを導入し、black, isort, flake8を置き換える作業
現状の動作確認と記録（各ツールの検出する問題数の記録）
既存設定の正確なRuffへの移行
3段階での動作確認（共存→比較→Ruffのみ）
重要な制約: コード修正は行わず、設定移行のみを実施

実行結果:

Cursorは慎重なアプローチを取りました：

現状記録: 既存ツールでの問題検出数を記録
Ruffインストール: uv add --dev ruffでのインストール
設定移行: 既存の設定を[tool.ruff]セクションに移行
3段階検証:
- 段階A: Ruffと既存ツールの共存確認
- 段階B: 出力の比較
- 段階C: Ruffのみでの動作確認
クリーンアップ: 既存ツールの削除

トラブルシューティング

段階1での問題

Problem: flake8がpyproject.tomlを読まない
Solution: flake8-pyprojectのインストール確認

段階2での問題

Problem: uvでの仮想環境が既存のPoetry環境と競合
Solution: Poetry環境を完全クリーンアップしてから、uvで新しい環境を作成

Problem: DockerfileでのPoetry依存部分の変更が必要
Solution: DockerfileのPoetryインストール部分をuv対応に変更

段階3での問題

Problem: ruffのisort設定が既存のisortと微妙に異なる動作
Solution: 3段階検証の段階Bで出力比較を行い、設定を調整

Problem: CIでuvコマンドが見つからない
Solution: GitHub ActionsでのPythonセットアップをuv対応版に変更

得られた効果

数値で見る改善効果（40以上の依存関係を持つプロジェクトでの実測）：

指標	変更前	変更後	改善率
Docker全体ビルド時間	69.9秒	54.3秒	22.4%短縮
Docker依存関係インストール	36.5秒	26.5秒	27.5%短縮
ローカル依存関係インストール	15.1秒	2.6秒	82.8%短縮
コードフォーマット＋リント実行	7.7秒	0.4秒	94.8%短縮
設定ファイル管理	2ファイル	1ファイル	統合