はじめに
アドベントカレンダー「AI エージェント機能で進化した JetBrains の開発体験をシェアしよう by JetBrains Advent Calendar 2025」の投稿です。
以前から仕事でもプライベートでもJetBrains製IDEが好きで普段から使っており、今回参加させてもらうことにしました。よろしくお願いします。
さて、今回はPythonのモダンフレームワークFastAPIでAPIを作るまでを、JetBrains製のAIエージェントJunieを使って行ってみたいと思います。
あるのは空のディレクトリとguidelines.mdだけ
今回はまっさらな状態から作成していくことにします。てきとうなディレクトリを用意して、そこにguidelines.mdを配置します。
デフォルトでは、Junie は設定されたプロジェクトのルートフォルダーにある .junie/guidelines.md でエージェントガイドラインを検索します
まずは空のディレクトリ配下を指定し、プロジェクトを開きます。上記のような確認がでますが、空なので信頼して問題ありません。
なにもないディレクトリなのでmain.pyをPyCharmが生成してくれますが、それは一旦使いません。
まずは、.junie/ディレクトリと空のguidelines.mdを作成します。
実はJunieは、このguidelines.mdすら自分で生成できますが、今回は人間が作成することにします。
早速、ディレクトリを作って空のファイルを…と、それもいりません。Junieを起動し、チャット欄の「＋」マークをクリックして、Create project guidelinesを押すだけ。
# Project Guidelines
This is a placeholder of the project guidelines for Junie.
Replace this text with any project-level instructions for Junie, e.g.:
* What is the project structure
* Whether Junie should run tests to check the correctness of the proposed solution
* How does Junie run tests (once it requires any non-standard approach)
* Whether Junie should build the project before submitting the result
* Any code-style related instructions
As an option you can ask Junie to create these guidelines for you.
なんかできました。すごい。
guidelines.mdに書くこと
guidelines.mdにはどんなものを書くといいでしょう。自動生成されたguidelines.mdでは
- プロジェクトの構造
- 提案されたソリューションの正当性を確認するためにJunieがテストを実行する必要があるかどうか
- テストの実行方法（非標準的なアプローチが必要な場合）
- 結果を送信する前にJunieがプロジェクトをビルドする必要があるかどうか
- コードスタイルに関する指示
とのこと。プロジェクト全体のディレクトリ構成、環境、ルールなんかを明確にする感じっぽいですね。
以下のようにしてみました。
# Project Guidelines
これはこのプロジェクトのガイドラインです。
## 必ず行ってほしいこと
- ドキュメントの作成、コード内のコメント、Junieとの受け答えはすべて日本語で行います。
## 環境
- 言語：python3.13
- パッケージ管理：uv
- フレームワーク：FastAPI
上記を、ローカル環境上のDockerコンテナ内で作成します。
## 仕様
`.junie/spec.md`に記載してある仕様を満たします。
## コーディングルール
- PEP8に準拠させます。
- 1行を最大で100文字に設定します。
- 循環複雑度は10までとします。
### 変数について
- 複数形と単数形を適切に使用します。
- インデックス以外に1文字の変数を使用しません。
- 定数は大文字のスネークケースを使用します。
- 変数名はスネークケースを使用します。
- dictのキー名はスネークケースを使用します。
- 短縮、省略した名前を使用しません（例：obj, idxなど）
- 汎用的な名前は使用しません（例：result, data, tempなど）
### 関数について
- 安易にgetやfindといった名前を使用せず、明確で適切な名前を使用します。（例：DBからデータを取得するならfetch〜、文字列を抽出するならextract〜など）
- スネークケースで命名します。
- その関数の処理を１行でdocstringにまとめます。input / outputパラメータの情報は必要ありません。
- 関数をまとめる単位は、大まかな機能単位です。細かくなりすぎても、大きくなりすぎてもいけません。
- １関数は多くても60行以内にまとめます。
### クラス名について
- アッパーキャメルで生成します。
- クラスについてのdocstringは必要ありません。
- クラス名は`Service`を末尾に付与します。（例：HelloWorldService）
### スキーマについて
- スキーマのクラス名の末尾に、リクエストの場合は`Request`、レスポンスの場合は`Response`を付与します。（例：HelloWorldRequest, HelloWorldResponse）
## ディレクトリ構成
### アプリケーションのroot
- `./api/` にmain.pyを配置します。FastAPIで使うすべてのコードはこの下に集約します。
### ルーター
- `./api/routers/` にファイルを作成します。
### ビジネスロジック
- `./api/services` にファイルを作成します。
### スキーマ
- `./api/schemas/` に、`requests` と `responses` を作成し、それぞれにpydanticリクエストスキーマとレスポンスのスキーマを作成します。
### テスト
- `.api/tests/` にpytestコードを作成します。
## FastAPIについて
### ルーター
- スキーマとビジネスロジックは`Depends`で依存性の注入を行います。
- ルーターにビジネスロジックは記述せず、ルーティング、バリデーションだけに集中します。
## README.md
`README.md`を作成し、以下の情報を記述します。
- 初回環境作成方法
- 起動方法
- API仕様書確認方法
## HTTPクライアント
このアプリをコールできるHTTPクライアントを作成します。
そうなんです。別に日本語でいいんです。英語でかけるならそれがベストかもしれませんが、こだわる必要はありません。
すこし細かく感じる方もいるかもしれません。
ただ、現在のAIが生成するコードはまだ完全に信頼できる段階ではないという認識です。正直、「動きはするけど…」というコードも多いです。
今回のような検証レベルなら問題ないとは思いますが、このままプロジェクトのベースにしよう！と始めるなら、ある程度までガイドラインを設定してあげたほうがJunieも私たちもストレスが減ると思います。
今回はDBを使わないので記述していませんが、本当ならModelについて Repositoryについて マイグレーションについて なんかの記載も必要でしょう。あとから追加していくのでもOKです。
仕様（要件）を書く
さて、ガイドラインは大枠できました。次に、作ってもらうAPIの仕様を書きます。
guidelines.mdで記述したように、.junie/ ディレクトリ配下に spec.md を作成し、そこに仕様を書いていきます。
# Spec
# ハートビートAPI
## API概要
死活監視を行う。
## HTTPメソッドとエンドポイント
- GET `/heartbeat`
## リクエスト
なし
## レスポンス
### ステータスコード
200
### レスポンスボディ
{"status":"ok"}
### エラーレスポンス
- 500 Internal Server Error
# 生まれてから今日までの日数返却API
## API概要
生年月日を受け取り、誕生から今日までの日数を返却する。
## HTTPメソッドとエンドポイント
- PUT `/live_days`
## リクエスト
{"birthday":"YYYY-MM-DD"}
## レスポンス
### ステータスコード
200
### レスポンスボディ
{"days":365}
### エラーレスポンス
- 400 Bad Request (受け取った生年月日が型が違う、日付として扱えない場合)
- 500 Internal Server Error
と、ここまで書いて思ったのはspec.mdをこんなふうに自然言語で書くのもいいんですが、リクエスト/レスポンスパラメータが増えてきたりすると逆に面倒かなということです。
となると、OpenAPI仕様、いわゆるSwaggerで記述してそれを仕様とするのもありかな、と思います。
ただ、FastAPIは、実装に即したAPI仕様書をOpenAPI仕様で出力ができる点もセールスポイントの１つではあるので、spec.mdは、自然言語で、実装に即したAPI仕様書としてFastAPIが出力するSwaggerを使うという方向性でもいいのかもしれません。
実際に作成してもらう
準備は整いました。早速Junieに作ってもらいましょう。
一気に全部作って、といっても実行計画を適切にたてて実行してくれますが、今回は少しずつやってもらうことにします。
guidelines.mdを確認し、まずは環境のセットアップをしてください。
確認をされました。ディレクトリを作るよ！ってことですね。毎回確認しなくていいよ、という設定もできます。
何回か確認されて処理が終了。「まずは環境設定だけ」と指示したんですが、Junieは「環境構築＝動くところまで」と解釈したようで、API実装まで一気に進めてくれました。もうAPI2本できています。すごいな。
この間、Junieは計画を立て、そのとおりに実行しました。今回のような検証ではなく、実際の開発の際には、
guidelines.mdを確認し、実行計画を立て、plan.mdを生成してください
という指示をして、実行計画をまずレビューする方法も良いと思います。
デバッグをする
さて、README.mdに実行方法が記載されているので、そのとおりに実行してみます。
docker compose build
コンテナのビルドは問題なく終了。
docker compose up
ここで、エラーです。
$ docker compose up
[+] Running 2/2
✔ Network junie_make_default Created 0.0s
✔ Container junie_make-api-1 Created 0.0s
Attaching to api-1
api-1 | exec /app/.venv/bin/uvicorn: no such file or directory
api-1 exited with code 255
これをそのままJunieに投げてみます。
どうやら修正完了したようです。再度実行してみます。
無事起動しました。
細かい修正を指摘し、必要に応じてguidelines.mdを修正する
さて、最初「環境設定だけ」と指示したのが悪かった＆guidelines.mdの書き方が悪かったんだと思いますが、想定とは違う部分がいくつかあります。それを修正していきます。
HTTPクライアントがない
PyCharmには便利なHTTPクライアントがあるので、それを追加してもらいます。
guidelines.mdに記載した、HTTPクライアントがありません。PyCharmで提供しているHTTPクライアントを生成し、2本のAPIへアクセスできるようにしてください。
### ハートビートAPI
GET http://localhost:8000/heartbeat
Accept: application/json
###
### 生まれてから今日までの日数返却API
PUT http://localhost:8000/live_days
Content-Type: application/json
{
"birthday": "2000-01-01"
}
無事生成されました。
サービスとテストが、2本分のAPIが１つのファイルに入っている
サービスとテストはAPIごとにファイルを分けたいです。それをお願いしてみます。
サービスとテストについてです。2本のAPIが1つのファイルに混在しています。API毎にファイルを分けてください。
また、このことをguidelines.mdに追記し、以降この基準に従うようにしてください。
しばらくするとこのように２つのファイルに分けられて
guidelines.mdにも
### ビジネスロジック
- `./api/services` にファイルを作成します。
- 原則としてAPI（機能）ごとにファイルを作成します。
### スキーマ
- `./api/schemas/` に、`requests` と `responses` を作成し、それぞれにpydanticリクエストスキーマとレスポンスのスキーマを作成します。
### テスト
- `./api/tests/` にpytestコードを作成します。
- 原則としてAPI（機能）ごとにファイルを作成します。
原則としてAPI（機能）ごとにファイルを作成します。 という追記がされました。
IDEの設定がおわっていないので、コードを開くと「未解決」と表示されてしまう
pythonインタプリタの設定がされていないので、パッケージの依存解決ができずにPyCharmが警告を出しています。せっかくの高機能が活かしきれていないので、その設定方法もREADMEに追記してもらいましょう。
PyCharmでインタプリタの設定がされていないので、コードを開くと警告がでています。
README.mdに今回の環境のインタプリタ設定方法を記述してください。
ほどなく追記されました。
## PyCharmのインタープリタ設定方法
PyCharmでコード補完や型チェックを有効にするために、Docker Composeを使用したインタープリタの設定を推奨します。
1. PyCharmの **Settings** (または **Settings...**) を開きます。
2. **Project: junie-make** > **Python Interpreter** を選択します。
3. 右上の **Add Interpreter** ボタン（歯車アイコンの隣、またはドロップダウン内）をクリックし、**On Docker Compose...** を選択します。
4. **Configuration files** に `docker-compose.yml` が選択されていることを確認します。
5. **Service** で `api` を選択します。
6. **Next** > **Create** をクリックして完了します。
static method警告が出ている
コードを見てみると、
のように警告が出ています。直してもらいましょう。
PyCharmで、関数をstaticにできるという警告が出ています。`@staticmethod`アノテーションを用いて、staticにできる関数はstaticにしてください。また、この件についてguidelines.mdに追記してください。
無事に修正され、guidelines.mdにも追記されました。
### 関数について
- 安易にgetやfindといった名前を使用せず、明確で適切な名前を使用します。（例：DBからデータを取得するならfetch〜、文字列を抽出するならextract〜など）
- スネークケースで命名します。
- その関数の処理を１行でdocstringにまとめます。input / outputパラメータの情報は必要ありません。
- 関数をまとめる単位は、大まかな機能単位です。細かくなりすぎても、大きくなりすぎてもいけません。
- １関数は多くても60行以内にまとめます。
- `self`を使用しない場合は、`@staticmethod`アノテーションを付与します。
終わりに
今回のように、自然言語でガイドラインや仕様をきちんと示すことで、
コードを1行も書かずに、まっさらな環境から FastAPI の API を実装することができました。
正直なところ、DB が絡んだり、DDD のようなアーキテクチャを意識し始めたりすると、
AI エージェント任せではうまくいかない場面も、これからもっと増えてくると思います。
それでも今回試してみて感じたのは、
開発者が「何をどう作りたいのか」を適切に言語化できれば、
AI エージェントは十分に“開発の相棒”になり得るということでした。
一昔前は、その言語やフレームワークのお作法やイディオムをどれだけ知っているかが、技術力の指標のひとつだったように思います。
もちろんそれは今でも大切ですが、これからはそこに加えて「設計や意図を言葉で伝える力」もますます重要になっていくのかもしれません。
JetBrainsのIDEとともに少し未来の話をすると…
次に新しいプロジェクトを立ち上げるとき、まず最初に書くファイルは main.py ではなく、guidelines.md になる――
そんな開発スタイルも、案外すぐ当たり前になるのかもしれないな、と思いました。