Ralph TUI - JSONタスク作成
PRDをralph-tuiの自律実行用のprd.json形式に変換します。
注: このスキルはralph-tuiのJSONトラッカープラグインにバンドルされています。将来のトラッカープラグイン(Linear、GitHub Issuesなど)は、それぞれ独自のタスク作成スキルをバンドルする予定です。
⚠️ 重要: 出力は必ずルートレベルに「name」と「userStories」を持つフラットなJSONオブジェクトでなければなりません。内容を「prd」オブジェクトでラップしたり、「tasks」配列を使用したりしないでください。以下の「スキーマアンチパターン」セクションを参照してください。
ジョブ
PRD(マークダウンファイルまたはテキスト)を取得し、prd.jsonファイルを作成します:
- PRDの「品質ゲート」セクションから品質ゲートを抽出する
- PRDからユーザーストーリーを解析する
- 各ストーリーの受け入れ基準に品質ゲートを追加する
- ストーリー間の依存関係を設定する
ralph-tui run --prd <path>で実行可能な状態で出力する
ステップ1: 品質ゲートを抽出
PRD内の「品質ゲート」セクションを探します:
## 品質ゲート
以下のコマンドはすべてのユーザーストーリーで成功する必要があります:
- `pnpm typecheck` - 型チェック
- `pnpm lint` - リンター
UIストーリーの場合は、以下も含めます:
- dev-browserスキルを使用してブラウザで確認する
抽出するもの:
- 普遍的なゲート: すべてのストーリーに適用されるコマンド(例:
pnpm typecheck) - UIゲート: UIストーリーにのみ適用されるコマンド(例: ブラウザ確認)
品質ゲートセクションが存在しない場合: ユーザーにどのコマンドを成功させるべきか尋ねるか、npm run typecheck などの妥当なデフォルトを使用します。
出力形式
JSONファイルはルートレベルでフラットなオブジェクトでなければなりません:
{
"name": "[PRDまたはディレクトリからのプロジェクト名]",
"branchName": "ralph/[機能名-ケバブケース]",
"description": "[PRDからの機能説明]",
"userStories": [
{
"id": "US-001",
"title": "[ストーリータイトル]",
"description": "[ユーザー]として、[機能]をしたいので、[利点]を得たい",
"acceptanceCriteria": [
"PRDからの基準1",
"PRDからの基準2",
"pnpm typecheck が成功",
"pnpm lint が成功"
],
"priority": 1,
"passes": false,
"notes": "",
"dependsOn": []
},
{
"id": "US-002",
"title": "[US-001に依存するUIストーリー]",
"description": "...",
"acceptanceCriteria": [
"...",
"pnpm typecheck が成功",
"pnpm lint が成功",
"dev-browserスキルを使用してブラウザで確認"
],
"priority": 2,
"passes": false,
"notes": "",
"dependsOn": ["US-001"]
}
]
}
重要: スキーマアンチパターン(使用禁止)
以下のパターンは無効であり、バリデーションエラーが発生します:
❌ 誤り: ラッパーオブジェクト
{
"prd": {
"name": "...",
"userStories": [...]
}
}
これはすべてを「prd」オブジェクトでラップしています。絶対に行わないでください。 「name」と「userStories」フィールドはルートレベルに配置する必要があります。
❌ 誤り: 「tasks」の代わりに「userStories」を使用
{
"name": "...",
"tasks": [...]
}
配列名は「userStories」であり、「tasks」ではありません。
❌ 誤り: 複雑なネスト構造
{
"metadata": {...},
"overview": {...},
"migration_strategy": {
"phases": [...]
}
}
PRDがフェーズやマイルストーンを記述していても、これらを単一の「userStories」配列にフラット化する必要があります。
❌ 誤り: 「status」の代わりに「passes」を使用
{
"userStories": [{
"id": "US-001",
"status": "open" // 誤り!
}]
}
未完了のストーリーには "passes": false、完了したストーリーには "passes": true を使用します。
✅ 正しい: ルートレベルのフラット構造
{
"name": "Android Kotlin移行",
"branchName": "ralph/kotlin-migration",
"userStories": [
{"id": "US-001", "title": "Scraperインターフェースを作成", "passes": false, "dependsOn": []},
{"id": "US-002", "title": "WeebCentralScraperを実装", "passes": false, "dependsOn": ["US-001"]}
]
}
ストーリーサイズ: 最も重要なルール
各ストーリーは、1回のralph-tuiイテレーション(約1エージェントコンテキストウィンドウ)で完了可能でなければなりません。
Ralph-tuiはイテレーションごとに新しいエージェントインスタンスを生成し、以前の作業のメモリは保持されません。ストーリーが大きすぎると、エージェントがコンテキストを使い切る前に終了できなくなります。
適切なサイズのストーリー:
- データベース列とマイグレーションの追加
- 既存ページへのUIコンポーネントの追加
- サーバーアクションのロジック更新
- リストへのフィルタードロップダウンの追加
大きすぎるストーリー(分割する):
- 「ダッシュボード全体を構築する」→ スキーマ、クエリ、UIコンポーネント、フィルターに分割
- 「認証を追加する」→ スキーマ、ミドルウェア、ログインUI、セッション管理に分割
- 「APIをリファクタリングする」→ エンドポイントまたはパターンごとに1ストーリーに分割
目安: 変更内容を2〜3文で説明できない場合は、大きすぎます。
dependsOn を使った依存関係
dependsOn 配列を使用して、先に完了する必要があるストーリーを指定します:
{
"id": "US-002",
"title": "APIエンドポイントを作成",
"dependsOn": ["US-001"], // US-001が成功するまで選択されない
...
}
Ralph-tuiは:
- US-001が完了するまでUS-002を「ブロック済み」と表示する
- US-001が未完了の間、US-002を実行対象として選択しない
- US-002に取り組む際のプロンプトに「前提条件: US-001」を含める
正しい依存関係の順序:
- スキーマ/データベース変更(依存関係なし)
- バックエンドロジック(スキーマに依存)
- UIコンポーネント(バックエンドに依存)
- 統合/洗練(UIに依存)
受け入れ基準: 品質ゲート + ストーリー固有
各ストーリーの受け入れ基準には以下を含めます:
- PRDからのストーリー固有の基準(このストーリーが達成すること)
- PRDの品質ゲートセクションからの品質ゲート(末尾に追加)
良い基準(検証可能):
- 「タスクテーブルにデフォルト値'open'の
status列を追加する」 - 「フィルタードロップダウンにオプション: すべて、開く、閉じるを含む」
- 「削除をクリックすると確認ダイアログが表示される」
悪い基準(曖昧):
- ❌ 「正しく動作する」
- ❌ 「ユーザーがXを簡単に実行できる」
- ❌ 「優れたUX」
- ❌ 「エッジケースを処理する」
変換ルール
- PRDから品質ゲートを抽出する
- 各ユーザーストーリー → 1件のJSONエントリ
- ID: 連番(US-001、US-002など)
- 優先度: 依存関係の順序に基づく(1 = 最高)
- dependsOn: このストーリーが必要とするストーリーIDの配列
- すべてのストーリー:
passes: falseと空のnotes - branchName: 機能名から派生、ケバブケース、先頭に
ralph/を付ける - 受け入れ基準: ストーリー基準 + 品質ゲートを追加
- UIストーリー: UI固有のゲート(ブラウザ確認)も追加
出力場所
デフォルト: ./tasks/prd.json(PRDマークダウンファイルと同じ場所)
これにより、すべてのPRD関連ファイルが tasks/ ディレクトリにまとめられます。
または別のパスを指定することもできます。ralph-tuiは以下で使用します:
ralph-tui run --prd ./path/to/prd.json
例
入力PRD:
# PRD: タスク優先度システム
タスクに優先度レベルを追加します。
## 品質ゲート
以下のコマンドはすべてのユーザーストーリーで成功する必要があります:
- `pnpm typecheck` - 型チェック
- `pnpm lint` - リンター
UIストーリーの場合は、以下も含めます:
- dev-browserスキルを使用してブラウザで確認する
## ユーザーストーリー
### US-001: データベースに優先度フィールドを追加
**説明:** 開発者として、タスクの優先度を保存する必要があります。
**受け入れ基準:**
- [ ] 優先度列を追加: 1-4(デフォルト2)
- [ ] マイグレーションが正常に実行される
### US-002: タスクカードに優先度バッジを表示
**説明:** ユーザーとして、タスクの優先度を一目で確認したい。
**受け入れ基準:**
- [ ] バッジがP1/P2/P3/P4を色付きで表示する
- [ ] バッジがホバーなしでも表示される
### US-003: 優先度フィルタードロップダウンを追加
**説明:** ユーザーとして、優先度でタスクをフィルタリングしたい。
**受け入れ基準:**
- [ ] フィルタードロップダウン: すべて、P1、P2、P3、P4
- [ ] フィルターがURLに保持される
出力 prd.json:
{
"name": "my-app",
"branchName": "ralph/task-priority",
"description": "タスクに優先度レベルを追加",
"userStories": [
{
"id": "US-001",
"title": "データベースに優先度フィールドを追加",
"description": "開発者として、タスクの優先度を保存する必要があります。",
"acceptanceCriteria": [
"優先度列を追加: 1-4(デフォルト2)",
"マイグレーションが正常に実行される",
"pnpm typecheck が成功",
"pnpm lint が成功"
],
"priority": 1,
"passes": false,
"notes": "",
"dependsOn": []
},
{
"id": "US-002",
"title": "タスクカードに優先度バッジを表示",
"description": "ユーザーとして、タスクの優先度を一目で確認したい。",
"acceptanceCriteria": [
"バッジがP1/P2/P3/P4を色付きで表示する",
"バッジがホバーなしでも表示される",
"pnpm typecheck が成功",
"pnpm lint が成功",
"dev-browserスキルを使用してブラウザで確認"
],
"priority": 2,
"passes": false,
"notes": "",
"dependsOn": ["US-001"]
},
{
"id": "US-003",
"title": "優先度フィルタードロップダウンを追加",
"description": "ユーザーとして、優先度でタスクをフィルタリングしたい。",
"acceptanceCriteria": [
"フィルタードロップダウン: すべて、P1、P2、P3、P4",
"フィルターがURLに保持される",
"pnpm typecheck が成功",
"pnpm lint が成功",
"dev-browserスキルを使用してブラウザで確認"
],
"priority": 3,
"passes": false,
"notes": "",
"dependsOn": ["US-002"]
}
]
}
ralph-tuiでの実行
prd.json作成後:
ralph-tui run --prd ./tasks/prd.json
Ralph-tuiは:
- prd.jsonからストーリーを読み込む
passes: falseでブロックする依存関係がない最も優先度の高いストーリーを選択する- ストーリーの詳細と受け入れ基準を含むプロンプトを生成する
- ストーリーを実装するエージェントを実行する
- 完了時に
passes: trueをマークする - すべてのストーリーが成功するまで繰り返す
保存前のチェックリスト
- PRDから品質ゲートを抽出した(または不足している場合はユーザーに尋ねた)
- 各ストーリーが1回のイテレーションで完了可能である
- ストーリーが依存関係の順序で並んでいる(スキーマ → バックエンド → UI)
- 各ストーリーに
dependsOnが正しく設定されている - 品質ゲートがすべてのストーリーの受け入れ基準に追加されている
- UIストーリーにブラウザ確認が含まれている(品質ゲートで指定されている場合)
- 受け入れ基準が検証可能である(曖昧ではない)
- 循環依存がない