spec-to-backlog

仕様書からバックログへ

概要

Confluence の仕様書を構造化された Jira バックログに自動変換します。このスキルは Confluence から要件ドキュメントを読み込み、論理的な実装タスクに適切に分割し、作業を整理するためにまずエピックを作成してから、そのエピックにリンクされた個別の Jira チケットを生成します。これにより、面倒な手動でのコピー＆ペーストをなくします。

コアワークフロー

重要：必ず次の順序を守ってください。

1. Confluence ページを取得 → 仕様書の内容を取得します
2. プロジェクトキーを確認 → 対象の Jira プロジェクトを特定します
3. 仕様書を分析 → 論理的なタスクに分割します（内部で分析し、まだ作成しません）
4. 分割案を提示 → 作成予定のエピックとチケットをユーザーに提示します
5. 最初にエピックを作成 → 親エピックを作成し、そのキーを取得します
6. 子チケットを作成 → エピックにリンクされたチケットを生成します
7. 概要を提示 → 作成したすべての項目とリンクを提示します

エピックを最初に作成する理由： 子チケットを作成時に正しくリンクするには、エピックのキーが必要です。先にチケットを作成すると、どのエピックにも属さないチケットになってしまいます。

---

ステップ 1：Confluence ページを取得

起動されたら、Confluence ページの内容を取得します。

ユーザーが Confluence の URL を指定した場合：

URL の形式から cloud ID とページ ID を抽出します。

• 標準形式：https://[site].atlassian.net/wiki/spaces/[SPACE]/pages/[PAGE_ID]/[title]
• cloud ID は [site].atlassian.net から抽出するか、getAccessibleAtlassianResources を呼び出して取得できます
• ページ ID は URL のパスに含まれる数値です

ユーザーがページのタイトルまたは説明のみを指定した場合：

CQL クエリを使用して searchConfluence でタイトルからページを検索します。

searchConfluence(
  cloudId="...",
  cql="type=page AND title ~ '[search terms]'"
)

CQL を search に渡さないでください。 search ツールは Rovo のセマンティック検索で、クエリ構文ではなく自然言語を受け付けます。CQL を渡すとページを見つけられません。自然言語で検索する場合（query="one-click checkout spec"）にのみ search を使用し、タイトルや種類で絞り込む場合は searchConfluence を使用してください。

複数のページが一致した場合は、どのページを使用するかユーザーに確認してください。

ページを取得する：

cloudId と content ID を指定して getConfluenceContent を呼び出します。

getConfluenceContent(
  cloudId="...",
  content_id="123456",
  content_format="markdown",
  detail="full"
)

ページの内容が Markdown 形式で返されます。ステップ 3 でこの内容を分析します。

---

ステップ 2：プロジェクトキーを確認

仕様書を分析する前に、対象の Jira プロジェクトを確認します。

ユーザーに確認する：

「これらのチケットをどの Jira プロジェクトに作成しますか？プロジェクトキーを指定してください（例：PROJ、ENG、PRODUCT）。」

ユーザーがわからない場合：

listJiraProjects を呼び出して、利用可能なプロジェクトを表示します。これは主要なツールではないため、execute を通じて実行します（主要ではないツールの呼び出しを参照）。

executeRead(   # or execute(...) if your client exposes a single execute tool
  name="listJiraProjects",
  cloudId="...",
  inputs={"action": "create"}
)

一覧を提示します：「課題を作成できるプロジェクトが見つかりました：PROJ（Project Alpha）、ENG（Engineering）、PRODUCT（Product Team）。」

プロジェクトキーを取得したら：

listJiraProjectIssueTypesMetadata を呼び出して、利用可能な課題タイプを確認します。
これも主要なツールではありません。

executeRead(   # or execute(...) if your client exposes a single execute tool
  name="listJiraProjectIssueTypesMetadata",
  cloudId="...",
  inputs={"projectIdOrKey": "PROJ"}
)

利用可能な課題タイプを確認します：

• 「Epic」（または「Initiative」のような類似の親タイプ）がどの課題タイプか
• 利用可能な子課題タイプ：「Story」、「Task」、「Bug」、「Sub-task」など

子チケットに適切な課題タイプを選択します：

スキルは、仕様の内容に基づいて課題タイプを適切に選択します。

仕様に以下の内容が記載されている場合は、「Bug」を使用します：

• 既存の問題や欠陥の修正
• エラーや誤った動作の解決
• パフォーマンスの問題への対処
• データの不整合の修正
• キーワード：「fix」、「resolve」、「bug」、「issue」、「problem」、「error」、「broken」

仕様に以下の内容が記載されている場合は、「Story」を使用します：

• ユーザー向けの新機能や機能性
• ユーザーエクスペリエンスの改善
• 顧客から要望された機能
• 製品の機能強化
• キーワード：「feature」、「user can」、「add ability to」、「new」、「enable users」

仕様に以下の内容が記載されている場合は、「Task」を使用します：

• ユーザーへの直接的な影響がない技術的作業
• インフラストラクチャや DevOps の作業
• リファクタリングや最適化
• ドキュメントやツール
• 設定やセットアップ
• キーワード：「implement」、「setup」、「configure」、「optimize」、「refactor」、「infrastructure」

フォールバックロジック：

1. 「Story」が利用可能で、内容が新機能を示している場合 → 「Story」を使用
2. 「Bug」が利用可能で、内容が修正を示している場合 → 「Bug」を使用
3. 「Task」が利用可能な場合 → 技術的作業には「Task」を使用
4. 上記のいずれも利用できない場合 → 利用可能な課題タイプのうち、最初の「Epic」でも「Subtask」でもないものを使用

ステップ 6 で使用するため、選択した課題タイプを保存します：

• Epic の課題タイプ名（例：「Epic」）
• デフォルトの子課題タイプ（例：「Story」または「Task」）
• 利用可能な場合は Bug の課題タイプ名（例：「Bug」）

---

ステップ 3：仕様を分析する

Confluence ページの内容を読み、内部で次のように分解します：

Epic レベルの目標

実装する全体的な目的または機能は何ですか？これが Epic になります。

Epic の要約例：

• 「ユーザー認証システム」
• 「決済ゲートウェイの統合」
• 「ダッシュボードのパフォーマンス最適化」
• 「モバイルアプリの通知機能」

実装タスク

作業を、論理的で個別に実装可能なタスクに分割します。

分割の原則：

• 規模： 仕様ごとに通常 3～10 件のタスク（細分化しすぎない）
• 明確さ： 各タスクは具体的で、実行可能な内容にします
• 独立性： 可能な場合、タスクを個別に進められるようにします
• 網羅性： 必要に応じて、バックエンド、フロントエンド、テスト、ドキュメント、インフラストラクチャを含めます
• グループ化： 関連する機能は同じチケットにまとめます

次の観点を検討します：

• 技術レイヤー：バックエンド API、フロントエンド UI、データベース、インフラストラクチャ
• 作業の種類：実装、テスト、ドキュメント、デプロイ
• 機能：複雑な機能はサブ機能に分割
• 依存関係：前提となる作業を特定

一般的なタスクのパターン：

• 「[component] のデータベーススキーマを設計する」
• 「[feature] の API エンドポイントを実装する」
• 「[component] の UI コンポーネントを構築する」
• 既存の「[system]」に「[integration]」を追加する
• 「[feature]」のテストを作成する
• 「[feature]」のドキュメントを更新する

動作を表す動詞を使用します：

• 実装する、作成する、構築する、追加する、設計する、統合する、更新する、修正する、最適化する、設定する、デプロイする、テストする、ドキュメントを作成する

---

ステップ 4：分割案をユーザーに提示する

何かを作成する前に、予定している分割案をユーザーに提示します。

形式：

I've analyzed the spec and here's the backlog I'll create:

**Epic:** [Epic Summary]
[Brief description of epic scope]

**Implementation Tickets (7):**
1. [Story] [Task 1 Summary]
2. [Task] [Task 2 Summary]  
3. [Story] [Task 3 Summary]
4. [Bug] [Task 4 Summary]
5. [Task] [Task 5 Summary]
6. [Story] [Task 6 Summary]
7. [Task] [Task 7 Summary]

Shall I create these tickets in [PROJECT KEY]?

課題タイプのラベルは、各チケットがどのタイプで作成されるかを示します：

• [Story] - ユーザー向けの新機能
• [Task] - 技術的な実装作業
• [Bug] - 問題の修正または解決

先に進む前に、ユーザーの確認を待ちます。これにより、ユーザーは次のことができます：

• 分割案の変更を依頼する
• スコープが正しいことを確認する
• チケットの数や重点を調整する

ユーザーから変更の依頼があった場合は、分割案を調整して再度提示します。

---

ステップ 5：最初に Epic を作成する

重要： 子チケットを作成する前に、Epic を作成する必要があります。

エピックを作成する：

以下を指定して createJiraIssue を呼び出します。

createJiraIssue(
  cloudId="...",
  projectKey="PROJ",
  issueType="Epic",
  summary="[Epic Summary from Step 3]",
  description="[Epic Description - see below]"
)

エピックの説明の構成：

## Overview
[1-2 sentence summary of what this epic delivers]

## Source
Confluence Spec: [Link to Confluence page]

## Objectives
- [Key objective 1]
- [Key objective 2]
- [Key objective 3]

## Scope
[Brief description of what's included and what's not]

## Success Criteria
- [Measurable criterion 1]
- [Measurable criterion 2]
- [Measurable criterion 3]

## Technical Notes
[Any important technical context from the spec]

エピックキーを取得する：

応答にはエピックのキー（例：「PROJ-123」）が含まれます。すべての子チケットで必要になるため、このキーを保存してください。

応答例：

{
  "key": "PROJ-123",
  "id": "10001",
  "self": "https://yoursite.atlassian.net/rest/api/3/issue/10001"
}

エピックの作成をユーザーに確認する： 「✅ エピックを作成しました：PROJ-123 - ユーザー認証システム」

---

ステップ 6：子チケットを作成する

続いて、各実装タスクをエピックにリンクされた子チケットとして作成します。

タスクごとに：

タスクの内容に適した課題タイプを選択します：

• 課題の修正や解決を伴うタスクの場合 → 「Bug」を使用します（利用可能な場合）
• ユーザー向けの新機能を伴うタスクの場合 → 「Story」を使用します（利用可能な場合）
• 技術面やインフラ関連の作業を伴うタスクの場合 → 「Task」を使用します（利用可能な場合）
• それ以外の場合 → ステップ 2 のデフォルトの子課題タイプを使用します

以下を指定して createJiraIssue を呼び出します。

createJiraIssue(
  cloudId="...",
  projectKey="PROJ",
  issueType="[Story/Task/Bug based on task content]",
  summary="[Task Summary]",
  description="[Task Description - see below]",
  parent="PROJ-123"  # The Epic key from Step 5
)

課題タイプの選択例：

• 「認証のタイムアウトバグを修正する」→ 「Bug」を使用します
• 「ユーザーダッシュボードの UI を構築する」→ 「Story」を使用します
• 「CI/CD パイプラインを設定する」→ 「Task」を使用します
• 「パスワードリセット API を実装する」→ 「Story」を使用します（ユーザー向けの新機能）

タスクの要約の形式：

動作を示す動詞を使い、具体的に記述します。

• ✅ 「ユーザー登録 API エンドポイントを実装する」
• ✅ 「認証データベースのスキーマを設計する」
• ✅ 「ログインフォームの UI コンポーネントを構築する」
• ❌ 「バックエンド作業をする」（曖昧すぎます）
• ❌ 「フロントエンド」（実行可能な内容ではありません）

タスクの説明の構成：

## Context
[Brief context for this task from the Confluence spec]

## Requirements
- [Requirement 1]
- [Requirement 2]
- [Requirement 3]

## Technical Details
[Specific technical information relevant to this task]
- Technologies: [e.g., Node.js, React, PostgreSQL]
- Components: [e.g., API routes, database tables, UI components]
- Dependencies: [e.g., requires PROJ-124 to be completed first]

## Acceptance Criteria
- [ ] [Testable criterion 1]
- [ ] [Testable criterion 2]
- [ ] [Testable criterion 3]

## Related
- Confluence Spec: [Link to relevant section if possible]
- Epic: PROJ-123

受け入れ条件のベストプラクティス：

テスト可能で、具体的な条件にします。

• ✅ 「ユーザーの作成に成功すると、API が 201 ステータスを返す」
• ✅ 「パスワードは 8 文字以上で、bcrypt でハッシュ化されている」
• ✅ 「ログインフォームは送信前にメールアドレスの形式を検証する」
• ❌ 「ユーザーがログインできる」（曖昧すぎます）
• ❌ 「正しく動作する」（テストできません）

すべてのチケットを順番に作成する：

要約に記載できるよう、作成した各チケットのキーを記録します。

---

ステップ 7：概要を提示する

すべてのチケットを作成したら、詳細な概要を提示します。

✅ Backlog created successfully!

**Epic:** PROJ-123 - User Authentication System
https://yoursite.atlassian.net/browse/PROJ-123

**Implementation Tickets (7):**

1. PROJ-124 - Design authentication database schema
   https://yoursite.atlassian.net/browse/PROJ-124

2. PROJ-125 - Implement user registration API endpoint
   https://yoursite.atlassian.net/browse/PROJ-125

3. PROJ-126 - Implement user login API endpoint
   https://yoursite.atlassian.net/browse/PROJ-126

4. PROJ-127 - Build login form UI components
   https://yoursite.atlassian.net/browse/PROJ-127

5. PROJ-128 - Build registration form UI components
   https://yoursite.atlassian.net/browse/PROJ-128

6. PROJ-129 - Add authentication integration to existing features
   https://yoursite.atlassian.net/browse/PROJ-129

7. PROJ-130 - Write authentication tests and documentation
   https://yoursite.atlassian.net/browse/PROJ-130

**Source:** https://yoursite.atlassian.net/wiki/spaces/SPECS/pages/123456

**Next Steps:**
- Review tickets in Jira for accuracy and completeness
- Assign tickets to team members
- Estimate story points if your team uses them
- Add any additional labels or custom field values
- Schedule work for the upcoming sprint

---

エッジケースとトラブルシューティング

複数の仕様書またはページ

ユーザーが複数の Confluence ページを参照している場合：

• 各ページを個別に処理するか、どれを優先するか尋ねます
• 機能が異なる場合は、それぞれに別のエピックを作成することを検討します
• 「仕様書のページを 3 つ提供していただきました。それぞれにエピックを作成しますか？それとも、まず 1 つに絞って進めますか？」

既存のエピック

ユーザーが既存のエピックにチケットを追加したい場合：

• エピックの作成（ステップ 5）をスキップします
• 既存のエピックキーを尋ねます：「チケットを追加するエピックキーを教えてください（例：PROJ-100）」
• 提供されたエピックキーを使用して、ステップ 6 に進みます

独自の必須フィールド

必須フィールドが原因でチケットの作成に失敗した場合：

1. getJiraIssueTypeMetaWithFields を使って必須フィールドを特定します。これは主要なツールではないため、execute を通じて実行します。

   executeRead(   # or execute(...) if your client exposes a single execute tool
     name="getJiraIssueTypeMetaWithFields",
     cloudId="...",
     inputs={"projectIdOrKey": "PROJ", "issueTypeId": "10001"}
   )
   

2. 値をユーザーに尋ねます：「このプロジェクトでは『Priority』フィールドが必須です。どの優先度を設定しますか？（例：High、Medium、Low）」

3. ネイティブのパラメーターを直接渡します。priority はトップレベルの文字列であり、additional_fields の項目ではありません。additional_fields はカスタムフィールド専用です。

   priority="High",
   additional_fields={"customfield_10001": {"value": "Production"}}
   

大規模な仕様書

15 件以上のチケットが生成される仕様書の場合：

• 全体の内訳をユーザーに提示します
• 「この仕様書からは 18 件のチケットが作成されます。すべて作成しますか？それとも範囲を調整しますか？」と尋ねます
• まず一部を作成することを提案します：「最初の 10 件を作成して、残りを作成する前にフィードバックをお待ちすることもできます」

サブタスクとタスク

「Subtask」課題タイプを使用するプロジェクトもあります：

• メタデータに「Subtask」がある場合は、作業をより細分化するために使用できます
• サブタスクはエピックではなく、親タスクにリンクします
• 構成：エピック → タスク → サブタスク

曖昧な仕様

Confluence ページの詳細が不足している場合：

• チケットの数を減らし、より包括的な内容にします
• チケットの説明に「詳細な要件はリファインメント中に定義する必要があります」と記載します
• ユーザーに「仕様には実装の詳細があまり記載されていません。後からリファインメントできるように、概要レベルのチケットを作成しますか？」と確認します

API 呼び出しの失敗

createJiraIssue が失敗した場合：

1. エラーメッセージを確認し、具体的な問題（権限、必須フィールド、無効な値など）を特定します
2. executeRead(name="listJiraProjectIssueTypesMetadata", ...) を使用して、課題タイプが利用可能か確認します
3. ユーザーに「チケットの作成中にエラーが発生しました：[error message]。プロジェクトの権限または必須フィールドが原因の可能性があります。」と伝えます

---

質の高い内訳を作成するためのヒント

具体的にする

• ❌「フロントエンドの作業を行う」
• ✅「メールアドレス／パスワード入力欄とバリデーションを備えたログインフォームの UI を作成する」

技術的な背景を含める

• 仕様から明確な場合は、具体的な技術に言及します
• コンポーネント、サービス、モジュールを参照します
• 統合ポイントを記載します

論理的にグループ化する

• 関連する作業は同じチケットにまとめます
• 人為的に分割しないでください。「ユーザープロフィールページの構築」には UI と API の統合の両方が含まれます
• 専門分野が異なる場合は分割します。担当者が異なる場合は、バックエンド API のタスクとフロントエンド UI のタスクを分けます

重複を避ける

• 同じ機能に対して重複するチケットを作成しないでください
• 複数の機能で同じインフラストラクチャが必要な場合は、それらすべてが依存するインフラストラクチャのチケットを 1 つ作成します

テストを明記する

• 機能タスクにテストを含めます（「単体テストを含めて X を実装する」）
• または、複雑な機能については、個別のテストタスクを作成します（「認証フローの統合テストを作成する」）

ドキュメントのタスク

• ユーザー向け機能の場合：「ユーザードキュメントを更新する」または「ヘルプ記事を作成する」を含めます
• 開発者向けツールの場合：「API ドキュメントを更新する」または「統合ガイドを作成する」を含めます

依存関係

• チケットの説明に前提条件を記載します
• Jira で利用できる場合は、「Depends on」または「Blocks」の関係を使用します
• チケットを論理的な順序で並べます（インフラストラクチャ → 実装 → テスト）

---

良い内訳の例

例 1：新機能 - 検索機能

エピック： 商品の検索とフィルタリング

チケット：

1. [Task] 検索インデックスのスキーマとデータ構造を設計する
2. [Task] Elasticsearch を使用してバックエンド検索 API を実装する
3. [Story] 検索入力欄と検索結果の UI コンポーネントを構築する
4. [Story] 高度なフィルタリング（価格、カテゴリ、評価）を追加する
5. [Story] 検索候補とオートコンプリートを実装する
6. [Task] 検索パフォーマンスを最適化し、キャッシュを追加する
7. [Task] 検索の統合テストとドキュメントを作成する

例 2：バグ修正 - パフォーマンスの問題

エピック： ダッシュボードの読み込み時間の問題を解決する

チケット：

1. [Task] プロファイリングを行い、パフォーマンスのボトルネックを特定する
2. [Bug] インデックスとキャッシュを使用してデータベースクエリを最適化する
3. [Bug] ダッシュボードウィジェットに遅延読み込みを実装する
4. [Bug] 大規模なデータテーブルにページネーションを追加する
5. [Task] パフォーマンスの監視とアラートを設定する

例 3：インフラストラクチャ - CI/CD パイプライン

エピック： デプロイメントパイプラインの自動化

チケット：

1. [Task] GitHub Actions のワークフロー設定を行う
2. [Task] CI パイプラインに自動テストを実装する
3. [Task] ステージング環境へのデプロイを設定する
4. [Task] 本番環境へのブルーグリーンデプロイメントを実装する
5. [Task] デプロイメントのロールバック機構を追加する
6. [Task] デプロイメント手順書とドキュメントを作成する

---

プライマリ以外のツールを呼び出す

Atlassian Rovo MCP サーバーは、ツール一覧にプライマリツールを少数しか直接公開していません。それ以外はカタログにあり、メタツールから呼び出します。

• discover — 操作名がわからない場合は、自然言語で目的を説明します。使用する正確なnameとinputsが返されます。すでにプライマリツールとして利用できる操作に対して、discoverを呼び出さないでください。
• execute系ツール — 名前を指定してカタログの操作を実行します。ツール一覧を確認してください。クライアントによっては単一の**executeを公開し、別のクライアントではexecuteRead／executeWrite／executeDestructive**を公開しており、操作に対応するティアのツールを使う必要があります。引数は同じです。

executeRead(   # or execute(...) if your client exposes a single execute tool
  name="<operationName>",
  cloudId="...",
  inputs={"param": "value"}
)

重要なルール：

• cloudIdはトップレベルの引数であり、nameやinputsと同じ階層に指定します。 inputsの中には決して入れないでください。getContentFormatGuideなど、omitCloudIdとして宣言された操作ではcloudIdを指定しません。
• inputsはフラットなオブジェクトです。 サーバーが各パラメーターをパス、クエリ、または本文に振り分けます。
• 実際のツールスキーマにある正確なパラメーター名を使用してください。 認識されないパラメーターはエラーとして報告されずに破棄されるため、名前が間違っていても警告は表示されません。呼び出しは成功し、指定した値は無視されます。迷った場合は、まずスキーマまたはdiscoverの結果を確認してください。
• 呼び出しで不明な操作が報告された場合は、異なるキーワードでdiscoverを実行し、推測するのではなく、返された名前を使用してください。