はじめに

AI開発が急速に進む昨今、皆さんのチームでも何らかのツールの導入を検討されていることでしょう。

新規プロジェクトとは異なり、既存プロジェクトでは「AさんはCopilot、BさんはChatGPT…」といった具合に、ツールがバラバラで統制が取れないケースも多いのではないでしょうか？

実際、私が参加しているプロジェクトでも、各自が異なるツールを使う状態が続いていました。

この記事は、そうした状況をトップダウンで一斉に変えるのではありません。
ボトムアップで、JetBrainsのAIエージェント「Junie」のチーム導入を試みた体験記です。

AI導入には興味があるものの、

既存のワークフローが混乱するのではないか
AIが生成するコードの品質は大丈夫か

といった懸念を持つ開発者やテックリードの方々に向けて、私たちのチームが実践した 「4つのスモールステップ」戦略 をご紹介します！

この記事で得られる知見

失敗しない導入法: 無料枠から有料プランへ、チームを納得させながら移行する4ステップ
Junie教育法: .junie/guidelines.md で、AIに「チームの作法」を教え込む技術
理想の分業: AIがコードを書き、自律的にテスト検証まで行う「エージェント型開発」の実態

前提知識： JunieとAI Assistantの違い

私たちのチームは、日頃からIntelliJ IDEAを利用して開発を行っています。
JetBrains AIの機能群には、大きく2つの側面があります。

AI Assistant（補佐役）
従来のチャット型AI。コード生成や要約など、ワークフローに組み込む役割
Junie（協働エージェント）
自律型のAIエージェント。タスク計画、複数ファイル編集に加え、テスト実行と検証までを自律的に実施

この2つは境界が曖昧ですが、私はこの補佐から協働へのグラデーションこそがスモールステップ戦略の核だと考えました。まずは、AIエージェントに抵抗がある開発者に、補佐役として慣れてもらうことから始めたのです。

JetBrains AIをさらに詳しく知りたい方は、公式ページもご参照ください。

導入の壁：既存プロジェクト特有の心理的・技術的ハードル

既存プロジェクトへのAI導入には、特有の障壁が存在します。

心理的障壁
まだまだAIツール（特にJunieのように自律機能を持つもの）に対して懐疑的な開発者がいます。Stack Overflowの調査(2025)によれば、「AIの提案は“ほぼ正しい”が、結局デバッグに時間がかかり、逆に生産性が落ちる」というフラストレーションが最大の不満点として挙げられています。また、責任の重いタスク（例：プロジェクト計画やデプロイ）をAIに任せることには強い抵抗感があるという開発者の声も挙げられています
技術的障壁
既存プロジェクトには、独自のコーディング規約、アーキテクチャ、そして暗黙のルールが往々にして存在します。AIがこれらを無視したコードを生成すれば、即座に使えないと判断されてしかねません

最大の障壁：セキュリティとプライバシーの確保

チームでの導入検討時、最初に直面した最大の障壁がセキュリティとプライバシーの問題でした。

プロジェクトのコード（＝企業の知的財産）をAIに送信する以上、コードがAIの学習に利用されないという確証が必須だったのです。

この点において、JetBrainsのポリシーは非常に明確です！

学習利用はデフォルトOFF
商用ライセンスでは、ユーザーが明示的に許可（オプトイン）しない限り、データは保持・学習されない
企業ライセンスは管理者制御
組織でのデータ共有は管理者が一元管理するため、個々の開発者が誤って設定を変えることはできない
ローカルファイルも制御可能
.aiignore ファイルを使い、機密情報を含む特定のファイルやフォルダをAIの処理対象から明確に除外可能

参考：Product Data Collection and Usage Notice

この強力なプライバシーポリシーこそ、導入戦略の要です。

セキュリティ部門や、AIに懐疑的なチームメンバーを説得する上で、 最も強力な「お墨付き」 として機能しました！

💡 補足：組織でAI利用が制限されている場合
実際、私たちの会社でも当初は管理者がAI利用をオフにしていたため、使えない状態でした。
もし皆さんの組織でも利用が制限されている場合は、まず管理者の説得が必要です。
その際、本記事で紹介したセキュリティポリシーや導入のメリットが、説得の材料として役立てば幸いです！

導入戦略：チームにJunieを浸透させる「4つのスモールステップ」

セキュリティの安心を大前提に、私たちのチームは以下の4つのフェーズでJunieの導入を進めました！

【表1：既存プロジェクトへのJunie導入4ステップ・ロードマップ】

フェーズ	目的	主な機能	対象プラン	チームの反応
Phase 1	AIを安全に試す	無制限コード補完 + 少量のクラウド機能（コミットメッセージ、ドキュメント生成）	AI Free	コストゼロで日々の作業が楽に。AIへの心理的ハードルが下がり、同時に無料枠の限界を体感。
Phase 2	AIの真価を知る	AIチャット、テスト自動生成、リファクタリング支援	AI Pro Trial (30日間)	AIが便利なアシスタントから相談相手に。チーム内でAI Proプランを契約するか評価。
Phase 3	AIを教育する	`.junie/guidelines.md` によるプロジェクト規約の指定	AI Pro Trial (30日間)	AIがプロジェクトの文脈を理解するように。手直しの量が減る。
Phase 4	AIと一緒に仕事をする	Junieエージェントによる自律的な複数ファイルリファクタリング、テスト実行と検証	AI Pro	開発者は「指示者」に。AIが「実行者」となり、生産性が飛躍的に向上。

Phase 1 【AI Free】：心理的ハードルを下げる

スモールステップの第一歩は、コストもセキュリティリスクもゼロで始めることです。

そこで、ローカルLLMを利用するという選択肢もありました。
しかしながら、実際に試したところ高いマシンスペックが要求され、開発に支障が出たため、今回はクラウド機能を選択しました。

戦略： AI Freeプランの真価（無制限補完＋無料クレジット）

JetBrainsは、IDEライセンスを持つすべてのユーザーにAI Freeプランを提供しています。
このプランが導入の第一歩として優れている点には、以下の2つがあります。

無制限のローカルコード補完
JetBrains独自のモデルによるコード補完が、クレジット消費なしで無制限に使える
無料AIクレジット付与
高性能なクラウドモデル（OpenAIやAnthropicなど）を利用するための3 AI Creditsが毎月付与

この無制限のローカル補完と無料クラウドクレジットの組み合わせが、マシンスペックを問わず、チーム全員がAI導入の第一歩を踏み出すための、入口となりました。

実践：無料クレジットで「地味に面倒な作業」を自動化

私たちは、この貴重な無料枠（3クレジット）を使って コミットメッセージの自動生成を試しました。
チームの振り返りで、「地味に面倒だよね」と話題に上がっていた作業です。

開発者は当然コードの内容を把握していますが、チームからは以下のような「地味な悩み」が上がっていたのです。

連休を挟むと、何を変更したか思い出すのが面倒
英語で的確なコミットメッセージを書くのが地味に大変
変更点が多くて、メッセージが端的にならない

共感してくださる方もいるのではないでしょうか。

【無料で試せるアイディア】コミットメッセージの自動生成

自動生成の方法はとても簡単です。

Commitツールウィンドウで、Generate Commit Message with AI Assistant ボタンをクリックするだけです。

AI Assistantが差分（diff）を分析し、的確なメッセージを数秒で生成してくれます。（以下はFizzBuzzの例）

実は、「Prefix ＋日本語＋チケット番号」といったチーム独自のコミット規約も、IntelliJのAI Assistantを使えば完全に自動化できます。

毎回フォーマットを整える手間をなくしたい方は、ぜひ以下の記事を参考に設定してみてください。

評価：チームの反応と所感

コスト効率は抜群:
1ヶ月試しても消費はわずか1クレジット程度で、無料枠で十分実用的でした。
品質には限界あり:
プロンプト未調整では「差分の列挙」止まり。最終的な手直しは必須です。
それでも高評価:
完璧ではなくとも、「0から書く心理的負担」が減ったことでチームの反応は上々でした。

以下が、振り返りで上がったコメントです。

「コミットメッセージの “叩き台” を作ってくれるだけでも、心理的負担が減った」
「AIの提案を見て、コミットの粒度を分けるヒントになった」※1

※1補足：GUI上でコミットするファイルを選択できるため、AIのコミットメッセージが長かったり複数の機能が入っている場合に、コミットを分ける判断材料になった、ということです。

Phase 1の成果と課題

このステップで、懐疑的だったメンバーも「便利なアシスタントだ」と認識し始めました。

✅ 成果: 懐疑派も「便利なアシスタントだ」と認識。AIへの抵抗感が消滅
⚠️ 課題: 高度な機能を使うと、無料の3クレジットでは即座に枯渇
➡ Next: 「もっと使いたい」という現場のニーズをテコに、有料トライアルへ移行

Phase 2 【AI Pro Trial】：相談相手を見つける

Phase 1が想定以上に好評で、チーム内から「30日間のAI Pro無料トライアルがあるから、試してみようよ！」という声が上がりました。そこで、チーム全体でProトライアルへ移行。

目的は、無料枠では試せなかった「クレジット消費の多い高度な機能」を使い、AIが月額料金を支払う価値のある「相談相手」として実務に耐えうるかを評価することに設定しました。

実践：単体テストの雛形生成

記述量が多く、定型的になりがちな正常系テストの作成をAIに任せることにしました。

テスト対象のクラスやメソッドで Alt+Enter（macOSでは ⌥⏎）を押す
AI Actions | Generate Unit Tests を選択
AIが文脈を分析し、テストの雛形を生成（既存ファイルへの追加、または新規作成)

先ほどのFizzBuzzを対象に生成した単体テストが以下の通りです。

ただ、このままだとテスト内部に本番とほぼ同様のロジック（i % 3 == 0など）が組み込まれており、テストとして不十分です。

そこで、Specifyボタンから「3の倍数のケース、5の倍数のケース、15の倍数のケースを具体的にテストして」と追加で指示（※英語のみ）を出すことで、より実用的なテストコードに調整できます。

調整後の結果は省略しますが、概ね指示通りに生成されました。

サンプル用にサクッとイメージを掴んでもらうために生成した単体テストなので、改善の余地は十分にある点はご容赦ください。

評価：生産性向上と新たな課題

AIが生成した雛形をレビューし、エッジケースを追加する作業に集中できるようになったことで、　「テストを書き始める速度が圧倒的に上がった」　という声が上がりました。これは無料枠では試せなかった、明らかな生産性向上です。

しかし同時に、　「今のままではプロジェクトのコーディングルールに沿っておらず、手直しが多い。それなら初めから自分で書いた方が良い」　という、もっともな意見も出てきました。

Phase 2の成果と課題

⚖️ 評価: チーム内の反応は「賛否両論」。課金の価値について意見が割れる
⚠️ 課題: プロジェクトの文脈（規約）を理解しないなら、無料の外部AIで十分ではないか？という指摘
➡ Next: AIに「チームのコンテキスト」を教育するため、ガイドライン作成へ

Phase 3 【AI Pro Trial】： AIを教育し、チームの一員にする

Phase 2の総括で出た「AIがチームのコンテキスト（規約）を理解してくれないなら、無料のChatGPTやGeminiで十分ではないか？」という意見は、Junie導入における核心的な問いでした。

確かに、一般的な質問やアルゴリズムのコード片を生成するだけなら、外部のAIツールでも十分かもしれません。

選択理由：なぜ外部AIではなくJunieなのか？

私がチーム内にAIを活用した開発を浸透させていくにあたり、Junie（JetBrains AI）を選択した理由は、外部AIでは解決が難しいプロジェクトコンテキストとの統合にあります。

IDE組み込みのJunieならば、以下の2つのコンテキストを自動でAIに連携できます。

IDEとの深い統合（動的コンテキスト）
IDEと統合されているため、コードの静的解析（エラー・警告）、ファイル間の依存関係、Gitの差分など、IDEが持つ膨大な情報を自動的に理解します。
プロジェクトコンテキストの永続化（静的コンテキスト）
後述する .junie/guidelines.md により、Junieにプロジェクト固有のルールや規約を記憶させることが可能です。

Phase 3の目的は、AIを教育しチームの一員とすることです。

これまでのAI Assistantという「補佐役」から、プロジェクトのルール（静的）とIDEの現状（動的）を理解して協働する「パートナー（Junie）」へとAIを進化させるフェーズであり、私たちのチームはここでJunieの本格検証を開始しました。

実践： `.junie/guidelines.md`でプロジェクト規約を教える

Junieをパートナーとしていくにあたり、まずは.junie/guidelines.mdの整理から着手しました。

.junie/guidelines.mdとは、プロジェクトのコーディング規約やADR（アーキテクチャ決定レコード）などをAIに記憶させておくことができるファイルです。

既存の規約や開発者の暗黙知（好み）をチームで話し合い、最低限のルールをguidelines.mdに記載しました。

ただ、完璧な明文化は大変なため、この時点では作り込みすぎず、 「まずはJunieを触ってみる」 ことを優先しました。
あくまで評価過程であり、AIを「新しいチームメンバー」として育てていくスタンスを取ったためです。

Tips:
JetBrainsは、Spring Boot(Java)、Django(Python)、Gin-Gonic(Go)など、主要フレームワークのガイドライン例をGitHubで公開しています。どのように書けば良いか悩む場合は、参考にすると良いでしょう。

私たちのチームもSpring Bootで開発を行っているため、これを参考にしながら、最低限守ってほしいguidelines.mdを整理し、使ってみることとしました。

検証：ガイドライン適用後のテスト生成結果

Phase 2で使ったFizzBuzzのコードに対し、プロジェクトルートに配置した .junie/guidelines.md を用いて単体テストを作成してみます。
Markdown形式で自然言語で書けるため、既存のWikiや規約ドキュメントからの移植も容易です。

ガイドラインは以下のようにしました。

.junie/guidelines.md

# Project Guidelines

## 1. Refactor for Testability
**DO NOT** test `static void main`.
**MUST** refactor logic from `main` into a new, testable, public method.
All tests **must** target this new method.

## 2. Test Naming Convention
**MUST** use `should_ExpectedResult_when_Condition` naming.

## 3. Use Parameterized Tests
**MUST** use `@ParameterizedTest` with `@CsvSource` for testing multiple input/output pairs.
**DO NOT** create separate test methods for each value.

【ガイドラインの意訳】

ルール1（リファクタリング）:
mainメソッドはテストしない。テストしやすいようにロジックを別メソッドに分離すること

ルール2（命名規則）:
テスト名は「（条件）のとき（結果）になるべき」という形式で命名すること

ルール3（まとめ方）:
似たテストは別々に作らず、@ParameterizedTestで1つにまとめること

ガイドラインの適用後、Junieへの指示はあえて Create unit tests の一言にとどめました。
これは、「具体的な指示がなくても、ガイドラインに従って自律的にリファクタリングするか」を検証するためです。

Junieを実行した結果は以下の通りです。

Junie実行後のリファクタされたFizzBuzz.javaとFizzBuzzTest.javaは以下の通り。

FizzBuzz.java

public class FizzBuzz {
    public static String fizzBuzz(int n) {
        if (n % 15 == 0) return "FizzBuzz";
        if (n % 3 == 0) return "Fizz";
        if (n % 5 == 0) return "Buzz";
        return String.valueOf(n);
    }

    public static void main(String[] args) {
        for (int i = 1; i <= 100; i++) {
            System.out.println(fizzBuzz(i));
        }
    }
}

ルール１の通り、mainメソッドからロジックが切り出され、fizzBuzz(int n)メソッドへとリファクタリングされています。

FizzBuzzTest.java

public class FizzBuzzTest {

    @ParameterizedTest
    @CsvSource({
            // basics
            "1,1",
            "2,2",
            "3,Fizz",
            "4,4",
            "5,Buzz",
            "6,Fizz",
            "10,Buzz",
            "15,FizzBuzz",
            "30,FizzBuzz",
            // some higher numbers in the typical range
            "98,98",
            "99,Fizz",
            "100,Buzz"
    })
    public void should_ReturnExpectedFizzBuzz_when_InputProvided(int input, String expected) {
        // Act
        String actual = FizzBuzz.fizzBuzz(input);
        
        // Assert
        assertEquals(expected, actual);
    }
}

単体テストも、ルール2の命名規則通り（should_Return...）になり、ルール3の通り@ParameterizedTestを使ってシンプルにまとめられました！

評価：チームの反応と所感

この結果にはチーム内でも良い反応がありました。

「AI Assistantと比べても、Junieの方が質の高い単体テストやリファクタ案を出してくれる」
「Junieがプロジェクト固有ルールや今書いているコードを理解して適切に修正してくれる。これこそIDE統合の恩恵だ」
「これなら外部のChatGPTやGeminiよりも使い勝手が良い」

と、チーム内でも肯定的な声が多くなりました。

最終的に、無料Trialの終了を待たずして「AI Proプランを契約しよう」という話になりました。

Phase 3の成果と副産物

✅ 成果: AIが規約を理解し、実用的なコード修正が可能に。「有料プランの価値あり」と合意
✨ 副産物: ガイドライン作成を通じて「暗黙知」が言語化され、チーム内のルール認識が統一
📉 効果: AIの精度向上だけでなく、人間同士のコードレビュー指摘数も減少

なお、一点注意点があります。

.junie/guidelines.mdは、主にJunie エージェント のための設定ファイルです。

Phase 2 まで主に使用していた IntelliJ AI Assistant 本体の挙動制御（コミットメッセージ生成など）は、適用範囲によって設定場所を使い分ける必要があります。

チーム共通のルール（推奨）
プロジェクト直下の .aiassistant/rules ディレクトリに Markdown ファイルを追加します。（例：.aiassistant/rules/general.md）
個人ごとの最適化・Built-in機能の設定
Settings | Tools | AI Assistant | Prompt Library から設定を行います。

ルールの二重管理という課題に対しては、設定ファイル（.junie, .aiassistant/rules）をGit管理下に置きつつ、個人のIDE設定（Prompt Library）はWikiの推奨設定を参照して各自適用するハイブリッド運用でカバーしています。

参考情報：
プロジェクトルールを構成する
 プロンプトを追加してカスタマイズする

プロンプト詳細設定などの深いノウハウは本記事のスコープ外となるため、別途記事化を検討中です。この辺りはまだ知見が少なく手探り状態のため、他の方の記事投稿も切望しています！

Phase 4 【AI Pro】： Junieと一緒に仕事をする

いよいよ、Junieの真骨頂である自律的なタスク実行を本格的に活用し、AIと一緒に仕事を進めていくフェーズに入りました。

Proプランを契約すると決めた時点で、私の「Junieの導入」という目標は完了しています。
しかし、ツールは入れただけでは意味がありません。

使ってこそ価値があります。

最後に、実際の「使い所」と正直な「失敗談」を共有します。

【失敗談】 Junieへの「丸投げ」は通じない

まず、Junieは（そして現行のAIは皆そうですが）全知全能の神ではありません。
ついつい「いい感じにして」というノリで、以下のような曖昧なタスクを投げてしまいがちです。

このWebサイトのデザインを今風にして
古いプロジェクトのコード(oldProject/)に新しいアーキテクチャを適用して
（広範囲の）パフォーマンスを改善して

結果: Junieはタスクの意図を汲み取れず、空のファイルを生成したり、的外れな変更を加えたりして、タスクを完了できませんでした。

今回の記事で使った FizzBuzz.javaのような単一クラス・少量コードであれば、「パフォーマンスを改善して」という曖昧な指示でも意図を汲んでくれることがありますが、実際のプロジェクトではそうはいきません。

「どのファイルを」「具体的にどういった方法で（例えばStream APIを活用して）改善したいのか」まで、具体的に指示を出す必要がありました。

失敗から学んだこと

AIエージェントであるJunieも、人間と同じです。
曖昧な指示では意図を理解できず、開発者が期待した通りに動くことはできません。

一緒に働く同僚や後輩にタスクをお願いするように、「何を」「どのように」して欲しいのかを省略せず、具体例を交えて伝えることが重要だと改めて感じました。

AIエージェントを使いこなす上でも、開発者側にはタスクを適切に分解し、言語化する能力が、引き続き（あるいは、より一層）重要であると痛感させられた失敗談です。

私たちのチームでは、振り返りの際にこうした失敗談と成功談を共有し、ノウハウを蓄積していきました。
その中でも、特にチームの生産性向上に直結した成功例を紹介します！

【成功談】 Junieの真価「テスト実行・検証」サイクル

失敗から学び、タスクを具体化できるようになったことで、AIが生成するコードの質は格段に上がりました。

私たちはさらに一歩進め、Junieが「自分で動作を確かめる」仕組みを活用し、単体テストのサイクルを効率化しました。

これこそが、Junieの真価ともいえる 「テスト実行と検証」機能です。

分析：なぜテスト生成が強力なのか？

Junieは、コードの実装から仕様を読み取りやすい正常系の単体テスト作成において、絶大な効果を発揮します。
ロジックを分析し、人間が書くよりも遥かに高速にテストケースを量産できるためです。

しかし、Junieの強みは生成するだけではありません。

生成したコードを自律的に実行・検証する点にあります。
コンパイルエラーやテスト落ちが発生しても、Junie自身が修正を試みるため、人間が目にする時点ですでに「動くテストコード」になっている確率が高いのが特徴です。

効果：開発者は「バグの温床と仕様」に集中できる

この特性を活かし、私たちは　「AIに叩き台を作らせ、人間がレビューする」　という分業体制を確立しました。

AIの役割（量と速度）
コードから読み取れる正常系や一般的な異常系のテストを網羅的に生成し、動作検証まで行う。
人間の役割（質と仕様）
AIが生成したテストをレビューし、複雑なエッジケースや業務特有のバグの温床になりやすい箇所を重点的に補完する。

このプロセスを経ることで、単なる動作確認用コードではなく、「仕様としてカバーすべき振る舞い」が明記された、生きた仕様書としての単体テストが完成します。

AIの圧倒的な生成力で「カバレッジ（量）」を稼ぎ、人間の洞察力で「テストの信頼性（質）」と「仕様の明確化」を担保する。

これこそが、私たちのチームが辿り着いた成功パターンです。

Phase 4の教訓と成果

⚠️ 教訓: AIへの「丸投げ」は失敗する。人間側に「タスク分解・言語化スキル」が必須
✅ 成果: 正常系テストの「実装と一次検証」をAIに委譲し、工数を削減できた
🤝 協働: 人間は「異常系・エッジケース」の思考に集中する、理想的な分業体制が確立

まとめ：既存プロジェクトへのJunie導入は、スモールステップが鍵

私たちのチームは、まず AI Free プランでリスクゼロで「便利さ」と「限界」を体験し、次にAI Proトライアルで「AIがプロジェクトの規約を理解しない」という壁に直面しました。

この課題は、.junie/guidelines.mdでAIを教育することで解決でき、このプロセスは「チームの暗黙知の明文化」という副産物も生みました。

私たちが感じているJunieの真価は、AIが単なるツールを超え、自律した同僚エンジニアのように協働してくれる点にあります。

例えば、Junieに正常系テストの生成・検証を任せることで、開発者は異常系・エッジケースといった、より重要な作業に集中できるようになりました。

Junieを既存プロジェクトに導入したいと考えている方の参考になれば幸いです。
まずは、AI Freeプランや無料トライアルを使い倒して新しい開発体験をチームに "布教"することをおすすめします！

この他にもJunieを活用したコードレビューやMCPサーバの活用などもありますが、長くなりすぎてしまうので、本アドベントカレンダーに参加している他の方に譲りたいと思います。（また、別の機会に書きます）

長文ではありましたが、ここまで読んでくださりありがとうございました。

おまけ：コストパフォーマンスについて

今回の記事を執筆するにあたり、普段業務で使っているAI Proプラン（会社アカウント）ではなく、私物のPCを使って検証を行いました。

サンプルコードの生成やJunieの利用を一通り行いましたが、実際にかかったコストは以下の通り約1クレジットでした。

当記事は、誤字脱字や可読性の向上等の添削、サンプル用コードのアイディア出しや生成にGemini 3.0 Proを利用しましたが、文章構成や経験は筆者オリジナルのものです。