gh-windschord-claude-skils-jules-cli/skills/jules-cli/README.md

# Jules CLI統合スキル

docs/tasks.mdに記載されたタスクをGoogleの非同期コーディングエージェントJulesに依頼・管理するスキルです。SDDで分割したタスクを効率的にJulesに割り当て、進捗を追跡します。

## 特徴

- **タスク自動依頼**: docs/tasks.mdからタスクを読み取り、選択したタスクをJulesに依頼
- **日本語対応**: すべての依頼文を日本語でフォーマット
- **進捗追跡**: Julesの作業状況を管理し、完了後にtasks.mdを更新
- **並行処理**: 依存関係のないタスクを並行してJulesに依頼可能
- **詳細な文脈提供**: タスクの説明、受入基準、技術的文脈を含む完全な依頼文を生成

## 使用方法

### 基本的な使い方

1. **スキルを有効化**

   Claude Codeで以下のように依頼します：
   ```
   次のタスクをJulesに依頼してください
   ```
   または
   ```
   タスクをJulesで実行してください
   ```

2. **タスクを選択**

   スキルがdocs/tasks.mdから利用可能なタスクを表示するので、実行したいタスクを選択します。

3. **依頼文を確認**

   スキルが生成した依頼文を確認し、問題がなければ承認します。

4. **Julesが作業を実行**

   julesコマンドが実行され、タスクがJulesに送信されます。進捗は`jules list`や`jules status`で確認できます。

5. **完了後の処理**

   タスクが完了したら、スキルが結果をレビューし、tasks.mdを更新します。

### 詳細な例

#### シナリオ: ユーザー認証APIを実装する

**docs/tasks.md の内容**:
```markdown
#### タスク1.1: ユーザー認証APIエンドポイントの実装
**説明**: POST /api/auth/login と POST /api/auth/logout のエンドポイントを実装
**受入基準**:
- src/api/auth.tsが存在する
- すべてのテストが通過する（npm test）
- ESLintエラーがゼロである
**ステータス**: `TODO`
**依存関係**: なし
**推定工数**: 2時間
```

**ユーザーの依頼**:
```
タスク1.1をJulesに依頼してください
```

**スキルの動作**:
1. docs/tasks.mdを読み取る
2. タスク1.1の情報を抽出
3. 日本語の依頼文を作成：
   ```
   タスク: ユーザー認証APIエンドポイントの実装

   概要:
   POST /api/auth/login と POST /api/auth/logout のエンドポイントを実装してください。
   JWTトークンを使用した認証方式を採用し、パスワードはbcryptでハッシュ化します。

   受入基準:
   - src/api/auth.tsが存在し、login/logoutエンドポイントが実装されている
   - すべてのテストが通過する（npm test）
   - ESLintエラーがゼロである

   技術的文脈:
   - フレームワーク: Next.js 14
   - 認証: JWT + bcrypt
   - 参照実装: src/api/users.ts

   推定工数: 2時間
   ```
4. ユーザーに確認を求める
5. 承認後、julesコマンドを実行
6. タスクIDを記録（例: task-abc123）
7. tasks.mdのステータスを`IN_PROGRESS`に更新

**完了後**:
```
jules status task-abc123  # 完了を確認
jules result task-abc123  # 結果を取得
```
スキルが結果をレビューし、tasks.mdのステータスを`REVIEW`に更新します。

## Jules依頼文の構造

スキルが生成する依頼文は以下の構造を持ちます：

```
タスク: [タスクタイトル]

概要:
[タスクの詳細な説明]

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

技術的文脈:
- [フレームワークやライブラリ]
- [参照すべきファイルやコード]
- [制約事項]

推定工数: [時間]
```

すべて日本語で記述され、Julesが理解しやすい形式になっています。

## ワークフロー

```
1. ユーザーがスキルを起動
   「次のタスクをJulesに依頼してください」
   ↓
2. スキルがdocs/tasks.mdを読み取る
   TODO状態のタスクを特定
   ↓
3. タスクリストを表示
   ユーザーがタスクを選択
   ↓
4. 依頼文を日本語で作成
   タスクの説明、受入基準、技術的文脈を含む
   ↓
5. ユーザーに依頼文を確認してもらう
   承認後、次へ進む
   ↓
6. julesコマンドを実行
   依頼文をJulesに送信
   ↓
7. タスクIDを記録
   ユーザーに報告
   ↓
8. tasks.mdを更新
   ステータスをIN_PROGRESSに変更
   ↓
9. 進捗を確認（必要に応じて）
   jules listやjules statusを使用
   ↓
10. 完了後、結果をレビュー
    受入基準を満たしているか確認
    ↓
11. tasks.mdを最終更新
    ステータスをREVIEWまたはDONEに変更
```

## 並行処理

依存関係のない複数のタスクを並行してJulesに依頼できます：

**例**:
```
ユーザー: タスク1.1、1.2、1.3をJulesに依頼してください
```

スキルは各タスクについて：
1. 個別の依頼文を作成
2. 順次julesコマンドを実行
3. すべてのタスクIDを記録
4. 各タスクの進捗を個別に追跡

**並行実行の条件**:
- 依存関係が存在しない
- 異なるファイル・コンポーネントを対象とする
- 相互に影響を与えない

## tasks.mdの更新

スキルは以下のようにtasks.mdを更新します：

### ステータスの遷移

```
TODO → IN_PROGRESS（Jules実行中）→ REVIEW（完了、レビュー待ち）→ DONE（承認済み）
```

### 記録される情報

```markdown
#### タスク1.1: ユーザー認証APIエンドポイントの実装
**説明**: POST /api/auth/login と POST /api/auth/logout のエンドポイントを実装
**受入基準**:
- src/api/auth.tsが存在する
- テストが通過する
**ステータス**: `REVIEW`
**依存関係**: なし
**推定工数**: 2時間
**Jules Task ID**: task-abc123
**開始日時**: 2024-01-15 10:30
**完了日時**: 2024-01-15 12:15
**作業時間**: 1時間45分
```

## エラーハンドリング

### Julesでエラーが発生した場合

スキルは以下の手順で対処します：

1. **エラー内容を確認**
   ```
   jules status <task-id>
   ```

2. **ユーザーに報告**
   - エラーの詳細
   - 推定される原因
   - 推奨される対処方法

3. **対処を提案**
   - 依頼文を修正して再実行
   - 依存関係を解決
   - 手動で対処

4. **tasks.mdを更新**
   - ステータスをBLOCKEDに変更
   - エラー内容を記録

### タスクが長時間完了しない場合

1. 現在の状態を確認
2. ユーザーに状況を報告
3. キャンセルまたは待機を提案

## Jules CLIコマンドリファレンス

このスキルが使用する主なコマンド：

### タスクの作成
```bash
jules "タスクの説明"
```

### タスクの管理
```bash
jules list               # タスクリスト表示
jules status <task-id>   # タスクの状態確認
jules show <task-id>     # タスクの詳細表示
jules result <task-id>   # 完了したタスクの結果取得
```

### タスクの制御
```bash
jules cancel <task-id>   # タスクのキャンセル
jules retry <task-id>    # タスクの再実行
```

## ベストプラクティス

### 1. タスクの粒度を適切に

- 1つのタスクは1-3時間程度
- 1つの明確な目的を持つ
- 独立して完結する
- 検証が容易

### 2. 受入基準を明確に

検証可能な受入基準をtasks.mdに記載：

**良い例**:
```
受入基準:
- src/components/LoginForm.tsxが存在する
- npm testを実行してすべてのテストが通過する
- npm run lintを実行してエラーがゼロである
```

**悪い例**:
```
受入基準:
- ちゃんと動く
- きれいなコード
```

### 3. 技術的文脈を提供

Julesが適切に作業できるよう、必要な情報をtasks.mdに含める：
- プロジェクトの技術スタック
- 参照すべき既存コード
- コーディング規約
- 制約事項

### 4. 依存関係を明示

tasks.mdで依存関係を明確に記載：
```markdown
**依存関係**: Task 1.1, Task 1.2
```

これにより、スキルが適切な実行順序を判断できます。

## 制約事項

### 実行の制限

以下の場合はJulesへの依頼を控えます：

1. **タスクの曖昧性**
   - 受入基準が不明確
   - 実装方法が複数考えられる
   - 技術的文脈が不足している

2. **リスクの高い操作**
   - 本番環境への直接的な変更
   - データベースの削除操作
   - 認証情報の変更

3. **ユーザーの判断が必要な場合**
   - 技術選択が必要
   - アーキテクチャの決定が必要
   - トレードオフの判断が必要

### 環境要件

- Jules CLIがインストールされている必要がある
- julesコマンドがPATHに含まれている必要がある
- 認証が正しく設定されている必要がある
- ネットワーク接続が必要

## トラブルシューティング

### julesコマンドが見つからない

**原因**: Jules CLIがインストールされていない、またはPATHに含まれていない

**解決**:
1. Jules CLIのインストールを確認
2. PATHを設定
3. `which jules`で確認

### 認証エラーが発生する

**原因**: Jules CLIの認証が設定されていない

**解決**:
```bash
jules auth login
```
でGoogle認証を完了してください。

### タスクが失敗する

**原因**: 依頼文が不明瞭、または依存関係が不足

**解決**:
1. tasks.mdのタスク説明を詳細化
2. 受入基準を明確にする
3. 技術的文脈を追加
4. 依存関係を解決

### 並行実行で競合が発生する

**原因**: 同じファイルを編集するタスクを並行実行した

**解決**:
1. 依存関係を見直す
2. 順次実行に変更
3. タスクの粒度を調整

## SDD-Docsスキルとの連携

このスキルはSDD-Docsスキルと組み合わせて使用することで、最大の効果を発揮します：

### 推奨ワークフロー

1. **SDD-Docsスキルで設計**
   ```
   docsディレクトリを初期化してください
   ```
   - requirements.md（要件定義）を作成
   - design.md（技術設計）を作成
   - tasks.md（タスク管理）を作成

2. **Jules CLIスキルで実装**
   ```
   次のタスクをJulesに依頼してください
   ```
   - tasks.mdからタスクを選択
   - Julesに依頼
   - 進捗を追跡

3. **Task Executorスキルでレビュー**（オプション）
   ```
   完了したタスクをレビューしてください
   ```
   - 受入基準を確認
   - コード品質をチェック
   - tasks.mdを更新

### 連携の利点

- **一貫した文書管理**: SDDドキュメントとタスク管理を統合
- **効率的な実装**: タスクを自動的にJulesに割り当て
- **進捗の可視化**: tasks.mdで進捗を一元管理
- **品質保証**: 受入基準に基づいた検証

## さらに詳しく

- Jules CLIの公式ドキュメント: https://developers.googleblog.com/ja/meet-jules-tools-a-command-line-companion-for-googles-async-coding-agent/
- SDD-Docsスキル: [../sdd-docs/README.md](../sdd-docs/README.md)
- Task Executorスキル: [../task-executor/README.md](../task-executor/README.md)

## ライセンス

このスキルはMITライセンスの下で公開されています。