✨

AIを使ったドキュメント駆動開発でJulesを使った話

に公開
Node.js
Vitest
Jules
tech

1. はじめに

Julesがパブリックベータとして発表されたのが2025年5月20日です。
発表からJulesをコーディング用途で結構使いこんでいます。

最初は5タスク/日だった制限も60タスク/日といつの間にか増加して比較的試しやすい状況になっています。

個人的にはJules結構使えると思っているのですが、Claude Codeや最近話題のGemini CLIの記事と比べると、具体的なノウハウを紹介する記事はまだ少ないように感じています。

そこでこの記事では、約1ヶ月半、試行錯誤の末にたどり着いた、AIエージェントをうまく活用するための個人的なやり方を、備忘録も兼ねてまとめてみることにしました。

（注意書き）
あくまでJulesの記事であってClaude Codeと比較をしてどっちがという記事ではありません。
Julesが修正できないエラーもClaude Sonnet4でも修正できることが多いので、Opus 4を使ったClaude Code方がプログラミングタスクは優れていると思います。

2.Julesのタスクの流れ

Julesはクラウド上のバーチャルマシン(VM)にGitHubのリポジトリをクローンします。
そのVM上でJulesが作業して成果物を生成すると、リポジトリのブランチが自動で作成されて作業完了、というのが基本的なフローです。

VM上で実行するので、複数のタスクを同時実行することができ作業を並行して進められます。
(*)並行作業は、人間側の準備が間に合わないという点が実は一番高いハードルになっており、まだ使いこなせていません。

3.対応プログラミング言語

対応しているプログラミング言語、フレームワークは色々あります。
よく使われそうなのは、Node.js, Python, Go, Java あたりでしょうか。

詳しくは公式サイトを見てください。
リンク：https://jules.google/docs/environment/

私の場合は今回はNode.js(typescript)を使っています。

3.1.環境設定

デフォルトで入っているツールも公式サイトに記載されています。

リンク：https://jules.google/docs/environment/

3.2.追加の環境設定 # Node.jsの場合

一般的にnpm install で導入される ./node_modules ディレクトリは、.gitignore でGitHub リポジトリにコミットしないようになっています。

JulesはGithubからリポジトリをクローンするので、Julesにnpm install させる必要があります。
方法は主に3つ。

  1. なにもしない。
    • npm run xxx でエラーがでるのでJulesに必要性を判断して貰って解決してもらう
  2. タスク指示に記載
    • 計画で環境準備を最初に行うことを指示し、環境準備の指示に npm installを含めて実行させる。
  3. JulesのConfigrationを設定する
    • Julesの左ペインのCodebasesから該当のリポジトリを選択する。
    • Initial setup
      • セットアップコマンドとしてnpm installを設定すると、VM起動後に実行されます。
      • 他にも環境セットアップが必要であれば記述しておきます。
    • Repo commands
      • Run automated testsの設定があるのでnpm testを設定。(*)
      • (*)Package.jsonのscriptに"test": "vitest run" を設定しています。

おすすめは3、2、1の順ですが、最も効果的なのは2と3の併用です。
たまに環境がVMのデフォルト環境に戻ることがあるので、タスク指示にも記載していた方が無難かと思います。

また、lintやコードフォーマッタなど、よく使用するコマンドを指示したい場合は、タスク指示にその目的と使い方を記載しておくと、Julesがスムーズにコマンドを扱えるようになります。

3.3.コマンド実行するパスの指定方法

プロジェクトによっては、ルートディレクトリでない箇所での作業が必要なことがあると思います。
例えば /prjディレクトリ下がコードのルートディレクトリで cd prj して、その後 npm installが必要な場合があります。

その場合の指示ですが、cd /app/prj && npm install みたいな指示が無難です。

これが無難な対応である理由は、cdコマンドでカレントディレクトリを移動しても、いつの間にかルートの/appに戻っていることがあるためです。

これが発生すると、Julesは/app/prjにいるつもりでも実際は/appにいる状態となり、パスの誤りに気付かず、ひたすら試行錯誤して時間を無駄にしてしまいます。

cd /app/prj && hogehoge であれば、カレントディレクトリには依存せずに確実に狙ったディレクトリで実行できるのでオススメです。　先ほどのテストも実際は cd /app/prj && npm test などで登録しています。

唐突に /appというディレクトリが出てきましたが、JulesではVMの/appディレクトリ下にクローンされたリポジトリが配置されるようです。

4.階層化ドキュメント

Julesを含めてコーディングAIエージェント、というかLLMを使う上で一番大事なのは言語化だと思っています。

ドキュメント体系も重要で私はドキュメントを4つの階層に分けて管理しました。

  • 階層1 (なぜ作るか): プロジェクトの目的やゴール。
    • ビジネスプラン、プロジェクト憲章、プロダクトビジョンなど
  • 階層2 (どう作るか - 方針): 技術選定やコーディング規約など、プロジェクトの「お約束」。
    • アーキテクチャ選定、コーディング規約、技術選定書など
  • 階層3 (どう作るか - 設計): DBスキーマやAPI仕様など、具体的な「設計図」。
    • API仕様書、データベース設計書
    • 実装計画書
      • プロジェクトの実装計画を立て、個別のタスクへ分割を実施した結果など
  • 階層4 (何を作るか - 指示): Julesへの具体的な「作業指示書」。
    • 分割したタスクの1つに絞っての作業指示書

Julesに直接インプットするのは階層4のドキュメントですが、それ以外の階層のドキュメントが階層4の質に影響します。
階層1と階層2のドキュメントは、人の思想や方針といったこだわりが品質を左右するため、主要な内容は人が考える必要があります。
一方、階層3と階層4のドキュメントはLLMが得意とする分野なので、階層1と階層2のドキュメントを基に、その大部分をLLMに作成させることができます。

とはいえ、イチから作るのは時間がかかる作業です。そのため、そのドキュメント作成自体を効率化していく必要があります。
私の場合はLLMを生かすには、LLMへインプットするSOP(Standard Operating Procedures:標準作業手順書)が大事だと考えており、数ヶ月前からプロジェクト管理というよりは組織運営向けのSOPをせっせと作っていて、それをほぼ流用してプロジェクトを開始し、Node.jsを用いたプロジェクト向けに手を加えながら運用しました。

Julesとは別の話ですが、Gemini2.5proは100万トークン扱えるので全ドキュメントを入力しきれるためドキュメント駆動開発のキモである文書生成や、文書の整合性確認するのに非常に有用です。

この記事では、最終的にある程度固まった階層4のドキュメント構成について、もう少し深掘りします。

4.1.階層4の各種タスク作業指示書の構成

紆余曲折あって以下のような構成で一旦落ち着きました。

  • 1.目的
    • タスクの目的を明確にする
    • 具体的な成果物（具体的なファイル名も指定する）
  • 2.準備
    • 環境の準備に必要な作業を記載する(cd /app/prj && npm install)
  • 3.具体的な作業指示
    • 機能とテストの実装の指示
    • 検証方法の指示
      • 型チェック(cd /app/prj && npx tsc --noEmit --pretty)
      • テスト(cd /app/prj && npm test)
    • 型チェックを行いエラーがあったら修正すること、テストを実施してエラーがあったら修正することを指示
  • 4.期待するアウトプットと確認基準
    • 提出される成果物
      • 新規作成、変更するファイル名の指定
    • 完了の定義(DoD)
      • 関数が***の仕様通りに動作する。
      • npm run tsc がエラーなく成功する。
      • 追加・修正した全てのテストケースが成功する。

一番のポイントは、期待するアウトプットと確認基準を明確に設けることです。
これによって、タスクの出来栄えがレビューしやすくなります。

5.レビュー

レビュー自体はClaudeを使っています。
JulesがGemini 2.5 Proベースなので違うLLMが良いのかなという意味で使いました。

手順としては

  • Julesが作ったブランチと元のブランチ(main)の差分を抽出
  • 差分があったファイルの変更前のファイルを抽出
  • 抽出した情報にレビュー用のプロンプトを付加して、1つのファイルにします。

(ファイル先頭)
解説(主要機能、技術的詳細、差分)と総評(優れている点、考慮点や、改善提案)をしてください。
変更提案があってもコード提示は不要です。
1ファイルずつ解説と総評を行ってください。
特に要求事項のどの部分を実現するために変更されているかを説明してください。

(ここに差分を提示)

(ファイル末尾)
最後のファイルの解説と総評が終わったら、以下を出力してください：
これで全部です。
今回コーディング担当者から上がってきた資料は以上です。
・コーディング担当者にコード生成の要求文書と比較した際に優先度の高い項目を順にファイル名-項目で簡潔にまとめます。
・なお実際のコードの提示は、実装の幅を狭めてしまうため不要とします。言葉で表現します。
・完了の定義（DoD）の達成のチェックは必ず行います。

(ここに変更前のファイルを提示)
(ここに作業指示書を提示)

上記のようなファイルを作成し、Claudeに渡して実行すればレビューが始まります。

以下のような視点でチェック

  • 指示通りの成果物ができているか
  • 完了の定義を全て満たしているか
  • 勝手に機能を追加したりしていないか

レビューはまだまだ改善の余地があり、特に出力フォーマットに関しては改善の可能性を感じています。

  • レビュー出力形式
  • 問題がある場合のJulesへのフィードバックの形式
  • 問題がない場合の評価レポートの形式

6.問題解決

6.1. Julesが解決できなかったときの選択肢

  • 1. タスクを分割してStep by Stepで解決する
    • LLMを活用すればタスクの分割は比較的容易。
  • 2. LLMとVibeコーディングしてエラーを解消する
  • 3. エラーの内容をLLMに投げて改善策を考えてもらい、Julesにフィードバックする。
  • 4. エラーの内容をLLMに投げ改善策を考えて貰ってJulesに新しいタスクとして依頼する。
  • 5. 3〜4つ同じ内容のタスクを並列に実行し、筋の良いものを選ぶ。
    • 失敗例を見て少しずつ　やること/やってはいけないことのエッセンスを加える。

5.の力技で解決することもあるので侮れない。
全てを一度に解決できなくても、一部でも解決すれば作業指示書にフィードバックできるため、成功例と失敗例を集めるための同時実行は有効です。1日60タスクの制限に余裕があれば、一考の価値はあります。

6.2 Julesの課題

Julesの課題として、純粋なプログラミング能力の不足があるかと思っています。
今回のプロジェクトでいうと

  • 1.TypeScriptの型エラーの自力解決が苦手。
  • 2.Vitestの少し特殊なMockの構成が苦手。
  • 3.フレームワーク特有の事情により発生するエラーの自力解決が苦手
  • 4.上記の問題を解決したファイルが別途あるにもかかわらず、上手く流用できない。

といったところが苦手で、結構沼るときは沼る。

個人の所感ですが、何も指示しないとまずJulesの実力でコードを書き、その後エラーに対して後付けで対処するみたいな動作をするため、最初のJulesのコーディング品質が、その後の問題解決の難易度に直接影響しているように感じます。

タスク指示で、最初にコーディング計画を立てgrepで流用できるコードを検索して列挙した上でコーディング計画を立てること、などとすると多少改善する可能性を感じましたが、試行回数が少なく、まだ改善の余地がありそうです。これは今後の課題です。

まとめ

Julesを1ヶ月半使い込んだ結果、階層化されたドキュメント駆動開発はやはり有用であることがわかりました。

一方で、TypeScriptの型エラーやフレームワーク特有の問題に対するJulesの解決能力には限界があるので、そこを解決するためのインプットやワークフローを充実する改善が必要そうです。

Discussion