Jira 統合スキル

AI コーディングワークフローから直接 Jira チケットを取得、分析、更新します。MCP ベース（推奨）と直接 REST API の 2 つの方法をサポートしています。

いつ有効にするか

• Jira チケットを取得して要件を理解する
• チケットからテスト可能な受け入れ基準を抽出する
• Jira 問題に進捗コメントを追加する
• チケットの状態を変更する（To Do → In Progress → Done）
• マージリクエストやブランチを Jira 問題にリンクする
• JQL クエリを使用して問題を検索する

前提条件

オプション A：MCP サーバー（推奨）

mcp-atlassian MCP サーバーをインストールします。これにより、AI エージェントに Jira ツールが直接公開されます。

要件：

• Python 3.10+
• uvx（uv から）。パッケージマネージャーまたは公式 uv インストールドキュメントでインストール

MCP 設定に追加（例：~/.claude.json → mcpServers）：

{
  "jira": {
    "command": "uvx",
    "args": ["mcp-atlassian==0.21.0"],
    "env": {
      "JIRA_URL": "https://YOUR_ORG.atlassian.net",
      "JIRA_EMAIL": "your.email@example.com",
      "JIRA_API_TOKEN": "your-api-token"
    },
    "description": "Jira issue tracking — search, create, update, comment, transition"
  }
}

セキュリティ： ソースコードに秘密鍵をハードコードしないでください。JIRA_URL、JIRA_EMAIL、JIRA_API_TOKEN はシステム環境（またはシークレットマネージャー）に設定することをお勧めします。MCP env ブロックはローカルの未コミットファイルのみに使用してください。

Jira API トークンの取得：

1. https://id.atlassian.com/manage-profile/security/api-tokens にアクセス
2. API トークンの作成 をクリック
3. トークンをコピー — 環境に保存し、ソースコードには保存しないでください

オプション B：直接 REST API

MCP が利用できない場合は、curl またはヘルパースクリプトで Jira REST API v3 を直接使用できます。

必須の環境変数：

変数	説明
JIRA_URL	Jira インスタンスの URL（例：https://yourorg.atlassian.net）
JIRA_EMAIL	Atlassian アカウントのメール
JIRA_API_TOKEN	id.atlassian.com からの API トークン

これらをシェル環境、シークレットマネージャー、または追跡されていないローカル環境ファイルに保存します。リポジトリにコミットしないでください。

MCP ツール リファレンス

mcp-atlassian MCP サーバーが設定されている場合、以下のツールが利用可能です：

ツール	目的	例
jira_search	JQL クエリ	project = PROJ AND status = "In Progress"
jira_get_issue	キー別に完全な問題の詳細を取得	PROJ-1234
jira_create_issue	問題を作成（タスク、バグ、ストーリー、エピック）	新しいバグ報告
jira_update_issue	フィールドを更新（サマリー、説明、担当者）	担当者を変更
jira_transition_issue	ステータスを変更	"In Review" に移動
jira_add_comment	コメントを追加	進捗更新
jira_get_sprint_issues	スプリント内の問題をリスト	アクティブスプリント レビュー
jira_create_issue_link	問題をリンク（ブロック、関連）	依存関係の追跡
jira_get_issue_development_info	関連する PR、ブランチ、コミットを表示	開発コンテキスト

ヒント： 移行前に常に jira_get_transitions を呼び出してください — 移行 ID はプロジェクトワークフローによって異なります。

直接 REST API リファレンス

チケットを取得

curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
  -H "Content-Type: application/json" \
  "$JIRA_URL/rest/api/3/issue/PROJ-1234" | jq '{
    key: .key,
    summary: .fields.summary,
    status: .fields.status.name,
    priority: .fields.priority.name,
    type: .fields.issuetype.name,
    assignee: .fields.assignee.displayName,
    labels: .fields.labels,
    description: .fields.description
  }'

コメントを取得

curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
  -H "Content-Type: application/json" \
  "$JIRA_URL/rest/api/3/issue/PROJ-1234?fields=comment" | jq '.fields.comment.comments[] | {
    author: .author.displayName,
    created: .created[:10],
    body: .body
  }'

コメントを追加

curl -s -X POST -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "body": {
      "version": 1,
      "type": "doc",
      "content": [{
        "type": "paragraph",
        "content": [{"type": "text", "text": "Your comment here"}]
      }]
    }
  }' \
  "$JIRA_URL/rest/api/3/issue/PROJ-1234/comment"

チケットを移行

# 1. Get available transitions
curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
  "$JIRA_URL/rest/api/3/issue/PROJ-1234/transitions" | jq '.transitions[] | {id, name: .name}'

# 2. Execute transition (replace TRANSITION_ID)
curl -s -X POST -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"transition": {"id": "TRANSITION_ID"}}' \
  "$JIRA_URL/rest/api/3/issue/PROJ-1234/transitions"

JQL で検索

curl -s -G -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
  --data-urlencode "jql=project = PROJ AND status = 'In Progress'" \
  "$JIRA_URL/rest/api/3/search"

チケットを分析

開発またはテスト自動化のためにチケットを取得する場合、以下を抽出します：

1. テスト可能な要件

• 機能要件 — 機能が何をするか
• 受け入れ基準 — 満たす必要のある条件
• テスト可能な動作 — 具体的な操作と期待される結果
• ユーザーロール — この機能を使用する人とその権限
• データ要件 — どのデータが必要か
• 統合ポイント — 関連する API、サービス、またはシステム

2. 必要なテストタイプ

• ユニットテスト — 個別の関数とユーティリティ
• 統合テスト — API エンドポイントとサービス相互作用
• エンドツーエンドテスト — ユーザー向け UI フロー
• API テスト — エンドポイント契約とエラー処理

3. エッジケースとエラーシナリオ

• 無効な入力（null、超過長、特殊文字）
• 未認可アクセス
• ネットワーク障害またはタイムアウト
• 同時ユーザーまたは競合状態
• 境界条件
• データ不足または空
• ステート遷移（戻る、リフレッシュなど）

4. 構造化分析出力

Ticket: PROJ-1234
Summary: [チケットタイトル]
Status: [現在のステータス]
Priority: [高/中/低]
Test Types: ユニットテスト, 統合テスト, エンドツーエンドテスト

Requirements:
1. [要件1]
2. [要件2]

Acceptance Criteria:
- [ ] [受け入れ基準1]
- [ ] [受け入れ基準2]

Test Scenarios:
- Happy Path: [説明]
- Error Case: [説明]
- Edge Case: [説明]

Test Data Needed:
- [テストデータ1]
- [テストデータ2]

Dependencies:
- [依存関係1]
- [依存関係2]

チケットを更新

いつ更新するか

ワークフロー ステップ	Jira 更新
作業を開始	"In Progress" に移行
テストを作成	テストカバレッジサマリーでコメント
ブランチを作成	ブランチ名でコメント
PR/MR を作成	リンク付きコメント、問題をリンク
テスト合格	結果サマリーでコメント
PR/MR をマージ	"Done" または "In Review" に移行

コメント テンプレート

作業を開始：

このチケットの実装を開始します。
Branch: feat/PROJ-1234-feature-name

テストが実装されました：

自動化テストが実装されました：

ユニットテスト：
- [テストファイル1] — [カバー内容]
- [テストファイル2] — [カバー内容]

統合テスト：
- [テストファイル] — [カバーされるエンドポイント/フロー]

すべてのテストはローカルでパスしました。カバレッジ：XX%

PR が作成されました：

Pull request created:
[PR Title](https://github.com/org/repo/pull/XXX)

Ready for review.

作業が完了：

Implementation complete.

PR merged: [link]
Test results: All passing (X/Y)
Coverage: XX%

セキュリティ ガイドライン

• ソースコードまたはスキル ファイルに Jira API トークンをハードコードしないでください
• 常に環境変数またはシークレット マネージャーを使用してください
• .env を各プロジェクトの .gitignore に追加してください
• トークンが git 履歴に公開された場合は、すぐに回転させてください
• 最小権限 API トークンを使用し、必要なプロジェクトにスコープを制限してください
• API 呼び出しを実行する前に認証情報が設定されていることを確認してください — 素早く失敗して明確なメッセージを表示してください

トラブルシューティング

エラー	原因	修正
401 Unauthorized	API トークンが無効または期限切れ	id.atlassian.com で再生成
403 Forbidden	トークンがプロジェクト権限を欠いている	トークンスコープとプロジェクトアクセスを確認
404 Not Found	チケット キーまたはベース URL が間違っている	JIRA_URL とチケット キーを確認
spawn uvx ENOENT	IDE が PATH で uvx を見つけられない	完全パスを使用（例：~/.local/bin/uvx）または ~/.zprofile で PATH を設定
接続タイムアウト	ネットワーク/VPN の問題	VPN 接続とファイアウォール ルールを確認

ベストプラクティス

• 作業しながら Jira を更新し、最後に一度に更新しないでください
• コメントは簡潔ですが有益に保つ
• 複製せずにリンク — PR、テストレポート、ダッシュボードにポイント
• 他者の入力が必要な場合は @mention を使用
• 開始前に関連問題をチェックして、完全な機能範囲を理解
• 受け入れ基準が曖昧な場合、コードを書く前に明確にを要求