Initial commit
This commit is contained in:
Zhongwei Li
422
skills/jules-cli/README.md
Normal file
422
skills/jules-cli/README.md
Normal file
@@ -0,0 +1,422 @@
|
||||
# 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ライセンスの下で公開されています。
|
||||
Reference in New Issue
Block a user