jira

Jira 作業項目の管理

Atlassian CLI（acli）を使用して、Jira プロジェクト内の作業項目を表示、検索、絞り込み、作成、更新します。

前提条件

コマンドを実行する前に、両方の依存関係が利用可能であることを確認してください。この確認はセッション開始時に一度だけ行い、コマンドを実行するたびに行う必要はありません。

1. acli — acli --version を実行します。見つからない場合は、インストール方法について references/prerequisites.md を確認してください。
2. mdadf — mdadf --version を実行します。見つからない場合は、インストール方法について references/prerequisites.md を確認してください。

いずれかのツールが見つからず、インストールできない場合（例：ネットワークに接続できない場合）は、ユーザーに実行するコマンドを正確に伝え、そこで停止してください。

操作上の制約

• プロジェクトは読み取り専用：Jira プロジェクト自体は決して変更しないでください。プロジェクト内の作業項目のみ作成、更新、削除できます。

• 変更の意図：作成、編集、トランジション、割り当て、コメント、削除の操作では、ユーザーが明示的に変更を依頼した場合にのみ Jira を変更してください。依頼が曖昧な場合は、変更を行う前に確認してください。

• キーを優先した対象指定：ユーザーが MYPROJECT-1455 のような作業項目キーを指定した場合、JQL を記述せず、そのキーを直接使用してください。正確な CLI 構文はサブコマンドによって異なります（view は位置引数を使用し、edit、transition、assign、comment は --key フラグを使用します）。references/commands.md を参照してください。

• JQL：該当する場合は、作業項目の選択、検索、絞り込みに --jql を使用してください。

• 設定済みのデフォルトプロジェクト：ユーザーがプロジェクトを指定しない場合は、以下のプロジェクト解決手順（ワークスペースの .jira-skill.json → ユーザー全体の ~/.config/jira-skill/config.json → ユーザーに確認）に従って解決してください。

• 作業項目のタイプ：Bug、Task、Story、Epic

• リッチテキスト：Jira の説明とコメント本文は、まず Markdown で作成してから、acli を呼び出す前に mdadf --compact で ADF に変換してください。

  acli jira workitem create \
    --summary "Fix the login page" \
    --project "MYPROJECT" \
    --type "Bug" \
    --description-file <(mdadf --compact <<'MD'
  **Short Description**
  The login page returns a 500 on empty email.
  MD
  )
  

  Windows PowerShell など、プラットフォーム固有のパターンについては、references/mdadf-usage.md を確認してください。

プロジェクトの解決

リクエストごとにプロジェクトキーを解決してください。ユーザーがリポジトリを切り替える可能性があるため、リクエスト間でキャッシュしないでください。

1. ユーザーが MYPROJECT-1455 のような Jira 課題キーを指定した場合、その接頭辞をプロジェクトキーとして使用してください。
2. ユーザーが MYPROJECT のようなプロジェクトキーを明示的に指定した場合は、それを使用してください。
3. それ以外の場合は、現在の作業ディレクトリから親ディレクトリをたどり、リポジトリのルート（.git を含むディレクトリ）に到達するまで .jira-skill.json を検索してください。見つかったファイルに有効な defaultProject が設定されている場合は、それを使用してください。
4. それ以外の場合は、~/.config/jira-skill/config.json を読み取ってください。これはユーザー全体に適用され、すべてのリポジトリで共有されるフォールバック設定です。
5. 設定が見つからない場合は、必ず停止し、作業を進める前にユーザーに次の2点を尋ねてください。
   • どのプロジェクトですか？ 利用可能なプロジェクトを（acli jira project list --recent で）一覧表示し、ユーザーに確認してください。返されたプロジェクトが1つだけであっても、推測したり自動選択したりしないでください。
   • どこに保存しますか？ デフォルトをグローバル設定（すべてのリポジトリで共有される ~/.config/jira-skill/config.json）として保存するか、プロジェクトレベルの設定（リポジトリのルートにある .jira-skill.json）として保存するかを尋ねてください。通常は一度に1つのプロジェクトで作業するユーザーが多いため、デフォルトの推奨はグローバルです。ユーザーが両方の質問に答えた後でのみ、設定を書き込んでください。ユーザーが保存場所を指定せずにプロジェクトだけを確認した場合は、グローバルを使用してください。

.jira-skill.json はワークスペース内でのみ有効です。リポジトリごとに異なるデフォルトを設定できます。共有しない場合は .gitignore に追加してください。~/.config/jira-skill/config.json はユーザー全体に適用され、スキルの更新後も保持されます。

設定スキーマ：

{
  "defaultProject": "YOUR_PROJECT_KEY"
}

安全ルール

これらのルールは、Jira でよくあるミスを防ぐためのものです。例外なく従ってください。

1. 現在のステータスを取得せずに、ステータスを絶対に変更しないでください。 Jira のワークフローでは、中間ステータスが必要な場合があります（例：To Do → In Progress → In Review → Done）。手順を飛ばすと、何も通知されずに失敗したり、分かりにくいエラーが発生したりします。ステータスを変更する前に、必ず acli jira workitem view <KEY> --fields "status" を実行してください。

2. ユーザーから明示的な承認を得ずに、複数の項目を一括変更しないでください。 編集するたびにウォッチャーに通知されます。チケットを10件編集すると、通知が10件届くことになります。複数の作業項目を操作する前に、必ずユーザーに確認してください。

3. 元の説明を表示せずに、説明を編集しないでください。 Jira には取り消し機能がありません。説明を置き換える前に現在の内容を表示し、内容が失われないことをユーザーに確認してもらってください。

4. ステータスの遷移名がどのプロジェクトでも共通だと思い込まないでください。 「Done」「Closed」「Complete」「Resolved」は、プロジェクトやワークフロースキームによって異なります。判断に迷う場合は、acli jira workitem view <KEY> --fields "status" で現在のステータスを確認し、どのステータスを目標とするかユーザーに尋ねてください。

5. 新しいチケットで「Priority」「Technical Impact」「Business Urgency」を設定しないでください。 これらのフィールドは、リードやプロダクト担当者がトリアージで使用します。許可なく「Critical」チケットを作成すると、トリアージプロセスが損なわれます。ユーザーから優先度の指定を明示的に求められた場合は、その旨を確認し、通常、優先度はトリアージ時に設定されることを説明してください。

実行手順

1. リクエストで変更が発生する場合は、上記の安全ルールを確認してください。コマンドを実行する前に、どのルールが該当するか特定してください。
2. 上記のプロジェクト解決ルールを使用して、プロジェクトキーを特定してください。
3. リクエストの対象が特定の作業項目キーの場合は、JQL ではなくそのキーを直接使用してください。サブコマンドでキーを位置引数として指定するか、--key フラグを使用するかは、references/commands.md を参照してください。検索する場合、または複数の作業項目を対象とする場合にのみ JQL を使用してください。
4. リッチテキストが必要な場合は、Markdown で内容を作成し、acli の実行前に mdadf --compact で ADF に変換してください。プラットフォーム固有の構文が必要な場合は、references/mdadf-usage.md をお読みください。
5. 作業項目を作成または書き直す場合は、references/ticket-drafting.md の作成形式に従ってください。
6. 適切な acli コマンドを実行してください。すべてのフラグについては、references/commands.md をお読みください。
7. 出力を読み、分析してください。エラーが発生した場合は、acli --help または該当するサブコマンドのヘルプを実行して、対処方法を確認してください。

出力形式

• 作成、編集、ステータス変更、コメント追加、または担当者割り当ての操作後は、必ず Jira の直接 URL を含めてください。acli の出力から URL を取得し（例：✓ Work item MYPROJECT-100 created: https://…/browse/MYPROJECT-100）、クリック可能なリンクとして提示してください。URL なしで課題キーだけを報告しないでください。
• 検索結果や調査結果を報告する際は、作業項目へのリンクを含む表形式を使用してください。