はじめに

アドベントカレンダー「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 になる――

そんな開発スタイルも、案外すぐ当たり前になるのかもしれないな、と思いました。