Claude CodeでDjangoアプリをMVT構成で開発する手順

Claude CodeでDjangoアプリを作る前に

Claude CodeはPythonのWebフレームワークであるDjangoにも標準で対応します。django-admin や manage.py はただのコマンドラインツールなので、Claude Codeにファイル作成とコマンド実行を任せながら開発を進められます。

この記事ではDjango公式チュートリアルが扱う投票アプリ(polls)を題材に、Model-View-Template(MVT)の3層を順番に実装します。DjangoそのものではなくClaude Codeとの組み合わせ方に焦点を置くため、Django自体の詳しい仕様は公式チュートリアルを参照してください。

MVTはDjango独自の呼び方で、他のフレームワークでよく使われるMVC(Model-View-Controller)とほぼ同じ役割分担です。DjangoのView(views.py)がMVCのControllerに近く、DjangoのTemplateがMVCのViewに近い、と対応づけると理解しやすくなります。データを扱うModel、リクエストを処理するView、画面を組み立てるTemplateという3つの責務を分けて実装していきます。

前提条件は次の3つです。

• Claude Codeがインストール済みで claude --version が通る
• Python 3.12以降がインストール済みで、python -m django --version でDjangoのバージョンを確認できる
• ターミナルの基本操作(cd、ファイル編集の承認プロンプトへの応答)に慣れている

進め方はDjango公式チュートリアルの構成に沿って3段階です。プロジェクト作成、Modelの定義、View・Templateの実装の順に、Claude Codeへの指示例を挟みながら進めます。

Djangoには「プロジェクト」と「アプリ」という2つの単位があります。プロジェクトはデータベース設定やURL構成をまとめる器で、アプリはその中で動く個々の機能(投票機能、ブログ機能など)です。1つのプロジェクトに複数のアプリを持たせられ、逆に同じアプリを別のプロジェクトへ持ち込むこともできます。この記事では mysite プロジェクトの中に polls アプリを1つ作る、公式チュートリアルと同じ構成で進めます。

プロジェクトを作成し開発サーバーを起動する

まず空のディレクトリでClaude Codeを起動し、プロジェクトの雛形を作らせます。

mkdir djangotutorial && cd djangotutorial
claude

セッション内では自然言語で指示します。

django-adminでmysiteという名前のDjangoプロジェクトをこのディレクトリに作成してください

Claude Codeは django-admin startproject mysite . 相当のコマンドを実行し、manage.py と mysite/settings.py などを生成します。Pro・Max・Teamプランのインタラクティブセッションでは既定でAuto modeが有効なため、分類器が安全と判断したコマンドはプロンプトなしで実行されます。初回インストール直後のセッションや他プランではManual modeが既定になる場合があり、その際はコマンドごとに承認を求められます。

続けて開発サーバーの起動を頼みます。

python manage.py runserverで開発サーバーを起動して、動作確認してください

http://127.0.0.1:8000/ にアクセスして「Congratulations!」ページが表示されれば成功です。開発サーバーはコード変更を自動検知して再起動しますが、Claude Codeのセッションとは別プロセスなので、動作確認が終わったら別ターミナルでCtrl+Cを押して停止します。

最後にpollsアプリを作成します。

manage.py startappでpollsという名前のアプリを追加し、polls/views.pyに"Hello, world. You're at the polls index."を返すindexビューを書いてください。polls/urls.pyでindexにルーティングし、mysite/urls.pyにincludeで組み込んでください

http://localhost:8000/polls/ にアクセスして文言が表示されれば、Viewの最小構成が完成した状態です。

Modelを定義してマイグレーションを反映する

次にDjangoのORMでデータモデルを定義します。今回のpollsアプリでは、質問を表す Question と選択肢を表す Choice の2つのモデルを使います。

polls/models.pyに、Question(question_text: CharField, pub_date: DateTimeField)と、Choice(question: ForeignKey to Question, choice_text: CharField, votes: IntegerField default 0)を定義してください。両方のモデルに__str__メソッドも追加してください

モデルを追加しただけではデータベースに反映されません。INSTALLED_APPS にアプリを登録したうえで、マイグレーションを作成・適用する2段階の操作が必要です。

python manage.py makemigrations polls
python manage.py migrate

これらのコマンドをClaude Codeに実行させると、makemigrations と migrate のような複合的な操作はBash権限ルールの対象になります。データベースへの書き込みを伴うコマンドは、Auto modeでも慎重に扱いたい場面があります。settings.json の permissions に Bash(python manage.py migrate) のような許可ルールを明示しておくと、承認の挙動を自分でコントロールできます。

管理サイトから直接データを編集できるようにするには、スーパーユーザー作成と admin.py へのモデル登録が必要です。

python manage.py createsuperuserでadminユーザーを作成し、polls/admin.pyでQuestionモデルを管理画面に登録してください

http://127.0.0.1:8000/admin/ にログインすると、Questionの追加・編集・削除ができる管理画面が自動生成されます。Djangoの管理画面はモデル定義から自動生成される機能で、フォームや一覧表示のコードを自分で書く必要はありません。

ViewとTemplateでMVTを完成させる

MVTの最後のピースはTemplateです。detail・results・voteの3つのビューを追加し、indexビューをテンプレート経由の描画に切り替えます。

polls/views.pyにdetail(question_idを受け取りQuestionを表示)、results、voteの3つのビューを追加してください。detailはget_object_or_404で存在しない場合404を返すようにし、polls/urls.pyにapp_name="polls"の名前空間付きでルーティングしてください

テンプレートはアプリごとのディレクトリに配置します。Djangoは polls/templates/polls/ のように、アプリ名のディレクトリを二重に切る命名規則を使います。これは複数アプリで同名テンプレートが衝突するのを避けるためです。

polls/templates/polls/index.htmlを作成し、latest_question_listをループしてquestion_textをリンク付きで表示してください。リンク先は{% url 'polls:detail' question.id %}を使い、ハードコードしないでください

index側のビューは render() ショートカットを使うと簡潔に書けます。

from django.shortcuts import render
from .models import Question
 
def index(request):
    latest_question_list = Question.objects.order_by("-pub_date")[:5]
    context = {"latest_question_list": latest_question_list}
    return render(request, "polls/index.html", context)

{% url 'polls:detail' question.id %} のようにURL名を使ってリンクを組み立てると、後から polls/urls.py のパスを変更してもテンプレート側の修正が不要になります。この仕組みはDjango公式チュートリアルの言葉を借りれば、URLをテンプレートにハードコードする密結合を避けるための設計です。

ここまででModel(models.py)・View(views.py)・Template(templates/polls/*.html)の3層が揃い、MVT構成の最小実装が完成します。

Claude CodeでDjango開発を効率化する設定

Djangoプロジェクト固有のルールは、毎回チャットで説明する代わりに CLAUDE.md に書いておくと、セッションをまたいでも再指示が要らなくなります。CLAUDE.mdとSkillsの役割分担にあるとおり、CLAUDE.mdは「常に守ってほしい前提」を書く場所で、多段の手順はSkillsに切り出すのが向いています。

# CLAUDE.md
- 仮想環境は `source .venv/bin/activate` で有効化してから manage.py を実行する
- モデルを変更したら必ず makemigrations → migrate の順で実行する
- テストは `python manage.py test` で実行する
- マイグレーションファイルは生成されたらそのままコミットする(手動編集しない)

モデルのフィールド変更やマイグレーションの取り消しなど、データベースに影響する変更を加える前にレビューしたい場合はPlan modeが使えます。claude --permission-mode plan で起動するか、セッション中に Shift+Tab でPlan modeへ切り替えます。Claude Codeはファイルを読んで計画を提示するだけで、承認するまで実際の変更は行いません。

作業を任せる範囲の目安を早見表にまとめます。

開発サーバーの先へ進むときは、Heroku MCPサーバーでClaude Codeからアプリをデプロイ・スケーリングするが参考になります。コンテナ化して動かす場合はDocker/Podman/Kubernetes MCPの選び方も参照してください。

よくあるつまずき

仮想環境を有効化しないままコマンドを実行してしまう。Claude Codeは新しいシェルセッションでコマンドを実行します。.venv を有効化する記述がCLAUDE.mdに無いと、システムのPythonで実行されて ModuleNotFoundError: No module named 'django' になることがあります。CLAUDE.mdに活性化コマンドを明記しておくと再現しません。

INSTALLED_APPSへの追加を忘れたままmakemigrationsを実行する。polls.apps.PollsConfig を mysite/settings.py の INSTALLED_APPS に追加する前に makemigrations polls を実行すると、アプリが認識されずマイグレーションが作られません。モデルを書いた直後は、設定への追加まで含めて指示すると手戻りが減ります。

テンプレートのディレクトリ構造を間違える。polls/templates/index.html のようにアプリ名のサブディレクトリを省略すると、他のアプリに同名テンプレートがある場合にどちらが読み込まれるか制御できなくなります。polls/templates/polls/index.html の二重ディレクトリ構造を崩さないよう、テンプレート作成時は毎回パスを指定して依頼するのが確実です。

開発サーバーがバックグラウンドで残り続ける。runserver を止めずに次のセッションを始めると、ポート8000が使用中のまま新しいサーバーが起動できません。作業を終えるときは開発サーバーのターミナルでCtrl+Cを押す習慣をつけておきます。

__str__ メソッドを書かずに管理画面やシェルで確認する。モデルに __str__ を追加しないと、シェルや管理画面での一覧表示が Question object (1) のような判別しにくい表記になります。Claude Codeにモデルを書かせるときは、フィールド定義と合わせて __str__ の実装まで依頼に含めておくと、その後の動作確認がしやすくなります。

まとめ

Claude CodeでDjangoアプリを作る流れは、Django公式チュートリアルのステップをそのまま自然言語の指示に置き換える形で進められます。プロジェクト作成とView、Modelとマイグレーション、Templateという3段階に分けて依頼すると、各ステップでの動作確認がしやすくなります。

仮想環境の有効化やマイグレーションの手順といったプロジェクト固有のルールはCLAUDE.mdに書いておき、データベースに影響する操作だけはPlan modeや個別の許可ルールで一段階確認を挟む、という役割分担が実用的な運用です。