Jules API統合スキル

前提条件

• Jules APIキー — JulesウェブアプリのSettings > APIキーで取得（最大3つ）。下記「認証情報の設定」参照
• GitHubトークン — PRブランチ取得時のみ必要（repoまたはpublic_repoスコープ）
• JulesウェブアプリからJules GitHubアプリを対象リポジトリにインストール済みであること

認証情報の設定

scripts/jules.shは以下の優先順で認証情報を解決する:

優先	環境変数	内容
1	JULES_API_KEY_OP_URI / GITHUB_TOKEN_OP_URI	1Passwordシークレット参照（op://<vault>/<item>/<field>）。実行時にop readで取得
2	JULES_API_KEY / GITHUB_TOKEN	シークレットの直接指定（後方互換）
3	JULES_USE_CLOUD_CREDENTIAL=1	Jules宛リクエストの認証をClaude Codeクラウド環境のAPI credentials機能に委ねる（下記「クラウド環境でAPI credentialsを使う場合」参照）。GitHub側（get-pr-branch）は対象外で、従来通りGITHUB_TOKEN_OP_URI/GITHUB_TOKENが必要

1Passwordシークレット参照を推奨する。 環境変数には参照URIのみが載り、シークレット本体はプロセス環境・シェル履歴・設定ファイルに残らない。1Password CLI（op）のインストールとサインインが前提。

JULES_USE_CLOUD_CREDENTIAL=1を設定した場合、JULES_API_KEY_OP_URIまたはJULES_API_KEYが同時に設定されているとスクリプトはエラーで停止する（どちらの認証方式を使うか曖昧なまま進めないため）。

Claude Codeのsettings.json（.claude/settings.jsonまたは~/.claude/settings.json）に設定する例:

{
  "env": {
    "JULES_API_KEY_OP_URI": "op://Private/Jules/api-key",
    "GITHUB_TOKEN_OP_URI": "op://Private/GitHub/token"
  }
}

JULES_API_KEY_OP_URIの設定時にopコマンドの不在やop readの失敗を検知した場合、スクリプトはエラーで停止する（直接指定へ黙ってフォールバックしない）。

クラウド環境でAPI credentialsを使う場合

この方式を使う場合、settings.jsonにJULES_API_KEY_OP_URI/JULES_API_KEYを設定しないこと（上記「Claude Codeのsettings.jsonに設定する例」とは併用しない。既に設定済みなら削除してから使う。同時設定はスクリプトがエラーで停止する）。

Claude Code のクラウド環境設定 → 対象環境を編集 → 「認証情報を追加」で以下を入力する。

項目	値
追加先	対象のCloud environment
名前	任意（例: Jules API）
認証情報タイプ	Bearer のまま
許可ウェブサイト	jules.googleapis.com
カスタムヘッダー名	x-goog-api-key に書き換える
プレフィックス	空にする（Bearer のままだと認証失敗する）
値	jules.google.com の Settings で発行したAPIキー

保存後は新しいセッションを開始してから反映される （実行中のセッションには反映されない）。

設定後は以下で疎通確認する:

JULES_USE_CLOUD_CREDENTIAL=1 ./scripts/jules.sh list-sources

スクリプト

scripts/jules.shのサブコマンドでAPIを操作する（jq依存）:

サブコマンド	引数	説明
list-sources	—	接続済みリポジトリ一覧（全ページを自動取得）
create-session	<source> <branch> <title> [--force] / prompt: stdin	セッション作成（同名タイトルの重複作成を自動検知して中断）
list-sessions	[page_size=100]	セッション一覧（全ページを自動取得。page_sizeは1リクエストあたりの件数）
get-session	<session_id>	セッション詳細・状態確認
approve-plan	<session_id>	プラン承認
send-message	<session_id> / message: stdin	メッセージ送信
list-activities	<session_id> [page_size=100]	アクティビティ一覧（全ページを自動取得しcreateTime昇順に整列。.activities[-1]が最新）
close-session	<session_id>	セッションを削除（DELETE）する。元に戻せないため、PRのマージを確認した後にのみ実行する
get-pr-branch	<owner> <repo> <pr_number>	PRのheadブランチ名取得

ヘルプ表示: scripts/jules.sh help

ページネーション（最新状況の誤判定防止）: Activities APIは古い順に返り、1ページ（pageSize件）しか返さない。1ページ目だけを見ると、アクティビティが増えたセッションで最新のagentMessage・completed等が2ページ目以降に隠れ、「Julesが応答なし・停止している」と誤判定する。list-activities/list-sessions/list-sourcesはnextPageTokenを辿って全ページを取得するため、必ずスクリプト経由で確認し、curlで1ページ目だけを見て停止判定しないこと。停止の判断は.activities[-1]（最新）のcreateTimeと、get-sessionのstate・updateTimeの両方で行う。

ワークフロー

起動時の判定

Q. ユーザーの依頼はレビュー指摘・仕様変更への対応か？
   YES → レビュー対応フロー（既存セッションを再利用）
   NO  → 基本フロー（新規セッション作成）

レビュー指摘対応に新セッションを作成してはならない。新セッションは新ブランチ・新PRを生成し、元のPRを更新できない。

基本フロー

1. 認証情報の確認（JULES_API_KEY_OP_URI／JULES_API_KEY／JULES_USE_CLOUD_CREDENTIAL=1のいずれか。
   手順12のPRブランチ取得まで行う場合はGITHUB_TOKEN_OP_URI または GITHUB_TOKEN も確認。
   上記「認証情報の設定」参照）
2. scripts/jules.sh list-sources でソース名（sources/github/{owner}/{repo}）を確認
   （全ページを自動取得するため、対象リポジトリが多数の接続先の後方にあっても見落とさない）
3. docs/sdd/tasks/ でTODOタスクを確認・選択
4. ユーザーにベースブランチを確認
5. cat <<'EOF' | scripts/jules.sh create-session <source> <branch> <title>
   <依頼文（特殊文字・日本語を含んでも安全）>
   EOF
   同名タイトルの既存セッションがある場合はスクリプトがエラーで中断する
   （下記「リトライ時の重複防止」を参照。曖昧な失敗時に承認を待たず再実行しないこと）
6. /goal を設定してJulesセッションの監視を開始
   （下記「Claudeの監視責任」を参照）
7. scripts/jules.sh list-activities ${SESSION_ID} で planGenerated を待機
   （sleep がブロックされる環境は下記「プラン待機の代替手段」を参照）
8. プランを評価してユーザーに確認 → scripts/jules.sh approve-plan ${SESSION_ID}
   （問題があれば先に echo "<修正依頼>" | scripts/jules.sh send-message ${SESSION_ID}）
9. scripts/jules.sh list-activities ${SESSION_ID} で completed を待機
10. scripts/jules.sh get-session ${SESSION_ID} | jq -r '.output.pullRequests[0].url' でPR URL取得
    （webUrl が null の場合は下記「webUrl が null の場合」を参照）
11. PRの差分を確認する（下記「PR差分の確認（必須）」を参照）
    既存機能の意図しない削除・変更を検知したら scripts/jules.sh send-message で修正依頼 → 9に戻る
12. scripts/jules.sh get-pr-branch <owner> <repo> <pr_number> でJulesブランチ名取得・記録
13. docs/sdd/tasks/ をREVIEWに更新

レビュー対応フロー

既存セッションを再利用する。

1. タスクファイルの「Jules Session ID」を確認
2. scripts/jules.sh get-session ${SESSION_ID} | jq '{state, webUrl}'
3. echo "<レビュー指摘と修正内容>" | scripts/jules.sh send-message ${SESSION_ID}
   - 「既存のPRブランチに修正してください」と明記
   - 「新しいPRは作成しないでください」と明記
4. scripts/jules.sh list-activities ${SESSION_ID} でプラン生成を確認（必要に応じて scripts/jules.sh approve-plan ${SESSION_ID}）
5. 完了後、タスクファイルにレビュー対応履歴を追記

セッション状態別の対応:

state	対応
WORKING	send-message で追加指示
DONE	send-message で修正依頼（Jules が同一ブランチで再作業）
FAILED	下記フォールバック参照

フォールバック（セッション再利用不能時）

git fetch origin
git checkout <julesブランチ名>  # タスクファイルの「Jules ブランチ名」を使用
# 修正を実施
git add -p && git commit -m "fix: レビュー指摘への対応" && git push origin <julesブランチ名>

startingBranchは「Julesがブランチを切り出すベース（PR作成先）」であり、既存PRのブランチを指定しても既存PRへのコミット追加にはならない。

Claudeの監視責任

Julesへのタスク委任は「委任して終わり」ではない。Claudeがタスクの受け入れ条件を満たす最終責任を持ち、Julesの実行を能動的に監視・指示する。

/goal による継続監視（推奨）

セッション作成後すぐに /goal でコンプリーション条件を設定する。Claudeはターン間で自動的に監視を続け、条件が満たされると停止する:

/goal scripts/jules.sh list-activities ${SESSION_ID} の結果に completed イベントが存在し、
scripts/jules.sh get-session ${SESSION_ID} | jq '.output.pullRequests[0].url' でPR URLが取得でき、
タスクの受け入れ基準がすべてPR内容で確認できること。または30ターン経過したら停止する。

/goal がアクティブな間、Claudeは各ターンで自動的に以下を実行する:

1. scripts/jules.sh list-activities ${SESSION_ID} でアクティビティを確認
2. planGenerated があれば内容を評価し、問題があれば scripts/jules.sh send-message で修正を依頼してから scripts/jules.sh approve-plan で承認
3. completed になったらPRの内容を確認し、受け入れ基準との照合を報告

/loop によるポーリング（sleep不可環境）

sleep がブロックされる環境や定期確認に /loop を使う:

/loop 5m scripts/jules.sh list-activities ${SESSION_ID} | jq '.activities[-3:]' を確認し、
planGenerated があれば評価・scripts/jules.sh approve-plan を実行、completed であれば受け入れ基準を照合して報告

介入のタイミング

以下を検知した場合は scripts/jules.sh send-message で即座に介入する:

• プランが受け入れ条件をカバーしていない
• 実装の方向性が設計書と乖離している
• Julesが追加情報を求めている（ユーザーに確認後、回答を転送）
• コードの品質問題（テスト不足・エラーハンドリングの欠如等）

「これでいいだろう」と介入を省略しない。受け入れ条件を満たすまで監視・指示を継続する。

---

プラン待機の代替手段

sleep が hooks 環境でブロックされる場合、以下のいずれかを使用する:

方法1: Julesウェブアプリで手動確認（最も確実）

1. セッション作成後、ユーザーに案内:
   「プランが生成されたら https://jules.google でご確認ください。
    確認できたら「承認してください」とお伝えください。」
2. ユーザーから確認の返答を受け取ったら scripts/jules.sh approve-plan ${SESSION_ID} を実行

方法2: バックグラウンド実行 + 完了通知待ち

# Bash ツールで run_in_background: true を指定して投げ、通知を受けてから次ステップへ
scripts/jules.sh list-activities ${SESSION_ID} | jq '.activities[] | select(.planGenerated)'

完了通知が届いたら scripts/jules.sh approve-plan を実行する。

方法3: Monitor ツールによるポーリング

# Monitor ツールにこのコマンドを渡す（sleep は Monitor 内で実行される）
until scripts/jules.sh list-activities ${SESSION_ID} 2>/dev/null \
  | jq -e '.activities[] | select(.planGenerated)' > /dev/null; do sleep 15; done

---

リトライ時の重複防止

scripts/jules.sh create-session はセッション作成前に同名タイトルの既存セッションを検索し、見つかった場合はエラーで中断する。

曖昧な失敗（タイムアウト・応答なし等）が起きても、ユーザーの作業承認を待たずにscripts/jules.sh create-sessionを再実行してはならない。 リクエストがJules側では成功していた場合、再実行は同一タスクの重複セッションを生成する。

失敗時の対応:
1. scripts/jules.sh list-sessions で同名タイトルのセッションが既に存在しないか確認する
2. 存在する場合はそのセッションを使う（再作成しない）
3. 存在しない場合のみ、失敗原因（認証・パラメータ等）を特定してから再実行する
4. 原因が不明なまま闇雲にリトライしない。2-3回失敗した場合はユーザーに報告し、指示を仰ぐ
5. 意図的に同名タイトルで再作成する必要がある場合のみ、scripts/jules.sh create-session の第4引数に --force を指定する

---

PR差分の確認（必須）

Julesは既存機能との差分を十分理解せずに、関係のないコードを削除してしまうことがある。**PRをREVIEW・マージ判断する前に、必ず実際の差分内容を読む。**サマリーや +N/-M の統計だけで判断しない。

1. GitHub MCPツール（pull_request_read等）や git diff でPR全体の差分を取得する
2. 削除・変更された行ごとに、今回のタスクの受入基準・変更目的と関連があるか確認する
3. 以下に該当する削除を検知したら、REVIEW/DONEにせず scripts/jules.sh send-message で理由を確認する:
   - タスクのスコープ外のファイル・関数・分岐が削除されている
   - 既存のテストケースが削除・スキップされている（失敗回避のための削除を含む）
   - 既存の公開API・設定・エクスポートが削除されている
4. 不要な削除であればJulesに復元を依頼し、再度差分を確認してからREVIEWに進める
5. 削除の意図が不明な場合はマージ前にユーザーへ報告し、承認を得る

---

webUrl が null の場合

セッション作成直後は webUrl が null になる。state が WORKING に遷移後に再取得すると得られる場合がある:

scripts/jules.sh get-session ${SESSION_ID} | jq '{state, webUrl}'

webUrl が取得できない間は https://jules.google にアクセスしてセッション一覧から該当タイトルを探すようユーザーに案内する。

---

JSONペイロードと特殊文字・日本語

スクリプト（scripts/jules.sh create-session・scripts/jules.sh send-message）は内部で jq --arg を使用してJSONを生成するため、バッククォート・シングルクォート・日本語を含む任意のテキストを安全に送れる。ヒアドキュメント（<<'EOF'）を使うとシェル展開なしで渡せる:

cat <<'EOF' | scripts/jules.sh create-session "$SOURCE" "$BRANCH" "TASK-001: 設定修正"
タスク: `config.yaml` の設定修正（TASK-001）

概要:
`production` 環境でO'Brien形式のキーが読み込まれない問題を修正する。

受入基準:
- テスト環境・本番環境で設定が正常に読み込まれること
EOF

api_reference_ja.md のcurlサンプルは説明用の簡略形式であり、特殊文字を含む場合はそのまま使用できない。curlを直接実行する必要がある場合はPythonでJSONファイルを生成してから送ること:

python3 - <<'PYEOF' > /tmp/jules_payload.json
import json, sys
payload = {
    "prompt": """タスク: `config.yaml` の設定修正

O'Brien形式のキーが読み込まれない問題を修正する。""",
    "sourceContext": {
        "source": "sources/github/owner/repo",
        "githubRepoContext": {"startingBranch": "develop"}
    },
    "automationMode": "AUTO_CREATE_PR",
    "requirePlanApproval": True,
    "title": "TASK-001: 設定修正"
}
print(json.dumps(payload, ensure_ascii=False))
PYEOF

curl -s 'https://jules.googleapis.com/v1alpha/sessions' \
  -X POST \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $JULES_API_KEY" \
  --data-binary @/tmp/jules_payload.json

---

Jules依頼文の形式

タスク: [タスクタイトル]（[TASK-XXX]）

概要:
[詳細な説明]

受入基準:
- [基準1]
- [基準2]

技術的文脈:
- [フレームワーク、ライブラリ]
- [参照ファイル、制約事項]

コミット規約:
- feat/fix/docs等のprefixを使用し、タスクIDを含める

PRの作成先ブランチは依頼文ではなくstartingBranchパラメータで指定する。依頼文は日本語で、技術用語・ファイルパスは英語のまま使用する。

セッション作成パラメータ

パラメータ	型	説明
prompt	string	タスクの依頼文（必須）
sourceContext.source	string	sources/github/{owner}/{repo}
sourceContext.githubRepoContext.startingBranch	string	ベースブランチ
automationMode	string	AUTO_CREATE_PRでPR自動作成
requirePlanApproval	boolean	trueでプラン承認要求（推奨）
title	string	セッションタイトル

Claude協調ワークフロー

プラン評価観点

Julesがプランを生成したらClaudeが以下の観点で評価し、ユーザーに確認を求める:

1. 受入基準との整合（カバーされているか）
2. 技術的妥当性（適切な技術・パターンか）
3. 過不足の確認（不要・欠如ステップ）
4. リスク評価（既存コードへの影響、破壊的変更、既存機能の削除の有無）

問題がある場合はscripts/jules.sh send-messageで修正を依頼してからscripts/jules.sh approve-planで承認する。プラン承認は差分内容の保証にはならないため、完了後は必ず「PR差分の確認（必須）」を実施する。

実行中のフィードバック

アクティビティを定期確認し、以下の場合にscripts/jules.sh send-messageで介入する:

• コードの品質問題を検知した場合
• 進行方向が受入基準から逸れている場合
• 追加情報が必要な場合（ユーザーに確認してから伝達）

複数タスクの並行処理

依存関係のないタスクは複数セッションを同時作成できる:

1. 並行実行可能タスクを特定（依存関係グラフ分析）
2. 各タスクの scripts/jules.sh create-session（共通ベースブランチ）
3. 全セッションの scripts/jules.sh list-activities を監視
4. 各セッションのプランを順次確認・承認
5. 完了後 docs/sdd/tasks/ を更新

セッション一覧の確認: scripts/jules.sh list-sessions

docs/sdd/tasks/更新

ステータス遷移: TODO → IN_PROGRESS → REVIEW → DONE

段階1（セッション作成時）:

## 実行情報
**実行方式**: Jules API
**Jules Session ID**: {SESSION_ID}
**PR作成先**: {ベースブランチ}
**開始日時**: {日時}

段階2（PR作成時）:

**Jules ブランチ名**: {jules/task-xxx-xxxxxxxx}
**PR番号**: #{番号}
**PR URL**: {URL}
**PR作成日時**: {日時}

重要: Julesブランチ名はフォールバック時に必要。scripts/jules.sh get-pr-branchで取得して必ず記録する。

段階3（マージ時）:

**マージ日時**: {日時}

PRのマージを確認したらscripts/jules.sh close-session ${SESSION_ID}でJulesセッションを削除する（下記「PRマージ後のセッションクローズ」参照）。

段階4（レビュー対応時）:

## レビュー対応履歴

### {日時} レビュー指摘対応
**対応方法**: {既存セッション再利用（sendMessage）|ローカル修正}
**指摘内容**: [内容]
**対応内容**: [要約]

---

PRマージ後のセッションクローズ

Julesの作業完了後、PRがマージされたら、scripts/jules.sh close-session ${SESSION_ID}でJulesセッションを削除する。

1. GitHub側でPRがマージ済み（state: merged）であることを確認する
   （pull_request_read等でmerged: trueを確認。マージ前・マージ判定不明の状態で実行しない）
2. scripts/jules.sh close-session ${SESSION_ID}
3. docs/sdd/tasks/のタスクファイルにクローズ日時を記録する

注意（元に戻せない）: close-sessionはDELETE /v1alpha/sessions/{sessionId}を呼び出し、Jules側のセッション記録を完全に削除する。復元手段は無い。削除後はget-session・list-activitiesが404になるため、PR URL・Julesブランチ名など後で必要な情報は段階1〜3で必ずタスクファイルに記録してから実行すること。PRやコード自体（既にマージ済み）には影響しない。

レビュー対応フローで既存セッションを再利用する可能性が残っている間（マージ前）はクローズしない。マージ後にレビュー指摘が来た場合はセッションを再利用できないため、新規セッションまたはローカル修正で対応する。

リソース

• APIリファレンス: jules-api/references/api_reference_ja.md
• Jules API公式: https://developers.google.com/jules/api
• Julesウェブアプリ: https://jules.google