jira-communication

Jira コミュニケーション

uv run で実行する CLI スクリプトです。すべて --help、--json、--quiet、--debug に対応しています。

自動トリガー

Jira の URL または課題キー（PROJ-123）が指定されたら、意図に応じて選択します。いずれも 1 回の呼び出しで実行できます。

意図	ツール
トリアージ／チケットに取り組む	jira-issue.py work KEY
QA レビューを開始する	jira-issue.py qa KEY
QA 不合格後のフォローアップ	jira-issue.py qa-fail KEY
フィールドのみを検索する	jira-issue.py get KEY --fields ...
ステータスを変更する	jira-issue.py act KEY → jira-transition.py do
監査／関連チケットの検出／「自分の作業を自分でレビューしているか？」	jira-qa-gather.py KEY

認証の問題には jira-setup.py を使用します。アンチパターン： get と comment list の組み合わせではなく、該当する動詞を使用してください。

work は、まだ引き受けていないチケットにフラグを付けます。 自分に割り当てられていない場合、またはステータスから誰も対応していないと判断できる場合（To Do カテゴリー、QA などのレビュー用ステータス、または解決済み）、stderr に !! CLAIM KEY の通知が表示され、--json では claim にコマンドが記載されます。jira-issue.py update KEY --assignee me を実行し、続けて jira-transition.py list KEY から開始または再オープンのトランジションを実行してください。最初のコメント、計測、編集を行う前に実行してください。jira-comment.py add は、チケットが自分に割り当てられておらず、対応中のステータスでもない場合、投稿前に 1 回警告します。そのまま投稿は行われます。

スクリプト

${CLAUDE_SKILL_DIR}/scripts/{core,workflow,utility}/ 以下にあります。

コア： jira-issue.py、jira-search.py、jira-worklog.py、jira-attachment.py、jira-setup.py、jira-validate.py ワークフロー： jira-create.py、jira-transition.py、jira-comment.py、jira-move.py、jira-sprint.py、jira-board.py、jira-version.py、tempo-account.py ユーティリティ： jira-user.py、jira-fields.py、jira-link.py、jira-weblink.py、jira-worklog-query.py、jira-watchers.py、jira-qa-gather.py

実行スタイル

直接実行します。スクリプトは ✓／✗ を表示します。破壊的な操作では --dry-run を使用します。グローバルフラグはサブコマンドの前に指定します：jira-issue.py --json get PROJ-123。

書き込みのたびにチケットの状態を表示します

書き込みが成功すると、次のコマンドはチケットの状態を stderr に表示します：jira-comment.py add／edit、jira-transition.py do／path、jira-issue.py update、jira-worklog.py add、jira-weblink.py add、jira-link.py create（FROM_KEY。名前付き形式では --target）、jira-attachment.py add、jira-create.py issue：

── PROJ-123 · Task · Open · resolution: – · assignee: unassigned
   time: logged 15m / estimate – / remaining – · labels: –
(!) ticket is "Open" while you work on it: claim it (assign + start work)

(!) の行を読み、作業完了を報告する前に対応してください。 書き込み時にチケットが Open または Backlog である場合、In Progress なのに担当者がいない場合、書き込み時に別の人に割り当てられている場合、書き込み時にすでに完了している場合、解決理由なしで完了している場合、未完了なのに解決理由が設定されている場合、または記録された時間が見積もりを超えている場合に表示されます。QA などのレビュー用ステータスで担当者のいないチケットにはヒントは表示されません。これは意図的にチームのプールに回されるためです。トランジション後または作成後は、コマンドが設定した直後のステータスと担当者を除き、解決理由と時間のチェックのみ実行されます。

--json では、同じ情報が出力オブジェクトの ticket_state フィールドに含まれます。既存のキーである key、status、status_category、issuetype、resolution、assignee、assignee_is_you、time_spent_seconds、original_estimate_seconds、remaining_estimate_seconds、labels、hints と並んで表示されます。最後の hints には (!) の行が文字列として格納されます。ticket_state.hints は (!) の行と同様に確認してください。 jira-attachment.py add --json はリストを表示するため、状態はテキストとして stderr に出力されます。--quiet を指定すると状態は表示されません。

状態の確認には、書き込みごとに読み取りが 1 回追加されます（jira-comment.py add は、引き受け状況に関する警告のため、投稿前にさらに 1 回読み取ります）。確認に失敗してもコマンドは失敗せず、検索エラーは 1 行で表示されるか、JSON では "ticket_state": {"key": …, "error": "<type>"} になります。JIRA_TICKET_STATE=0 を設定すると、投稿前に jira-comment.py add が表示する警告とともに、すべての状態確認を無効にします。work の引き受け通知は引き続き表示されます。logged は Jira 独自の時間追跡です。別の場所で記録された時間は、Jira の作業ログに同期されてから表示されます。

Wiki マークアップを投稿する前に書き換えてチェックします

Wiki マークアップを書き込むすべての --comment オプションと --description オプションでは、書き込み前に 3 つのチェックが実行されます。テキストが正しく表示されなくても気づけないため、すべてデフォルトで有効になっています。API はどちらの場合も 2xx を返します。対象は次の 7 つすべてです。jira-comment.py add／edit、jira-transition.py do --comment、jira-transition.py path --comment、jira-worklog.py add --comment、および jira-create.py issue と jira-issue.py update の --description です。--fields-json 経由で渡された本文はチェックされません。このオプションは仕様上、フィールドをそのまま書き込むためです。jira-version.py が書き込む 2 つの --description フィールド（create と update）もチェックされません。Jira がバージョンの説明を Wiki マークアップとして表示するかどうかは未確認であり、ヘルプにそう記載されているのは単なる誤りかもしれません。

1. Jira で取り消し線として表示されるダッシュはエスケープされます。 \- は通常のハイフンとして表示されるため、投稿されたテキストは入力どおりに読めます。stderr には変更された行数と、最初の 5 行が表示されます。（エスケープが見える唯一のケースは、スペースを空けずに 2 つのマクロを連続して書いた場合です。ダッシュがリンク先の中に入ることがあります。通常の文章ではこのケースは発生しません。）--no-auto-escape を指定すると、マークアップはそのまま維持されます。ただし、これだけでは意図的な -strikethrough- は投稿されません。リンターとレンダリングチェックのどちらも、その範囲を引き続き拒否します。その場合は --no-auto-escape --force を使用してください。
2. マークアップとチケットの言語がリンターでチェックされます。 インラインで使用されたブロックタグ（{code}、{noformat}、{quote}、{panel} はブロックレベルです）、タグ数の不一致、英語のみのプロジェクトにおけるドイツ語の文章があると、書き込みは中止されます。--force を指定すると、検出内容を警告に変えて投稿を続行します。
3. インスタンスでテキストをレンダリングし、取り消し線が付いて返された場合は投稿を拒否します。 投稿ごとに API 呼び出しが 1 回発生しますが、ローカルのチェックでは検出できない問題も見つけられます。自動リンクされた課題キーによって生じる境界は、そのキーが解決されるインスタンス上でのみ存在します。解決済み課題のキーは、Jira がステータスの装飾として取り消し線を付けて表示しますが、報告されません。--no-preflight を指定すると、このチェックをスキップします。レンダラーに接続できない場合は警告を 1 回表示して、投稿を続行します。

--force を指定すると、3 つのチェックの結果にかかわらず投稿します。フラグ名は各コマンドで同じです。7 つすべてで --dry-run も使用できます。エスケープとリンターによるチェックは引き続き実行され、プレビューには実際に書き込む場合のテキストが表示されますが、レンダリング呼び出しと書き込みは行われません。詳細は references/comments.md を参照してください。

基本的な使い方

uv run ${CLAUDE_SKILL_DIR}/scripts/core/jira-issue.py get PROJ-123
uv run ${CLAUDE_SKILL_DIR}/scripts/core/jira-search.py query "assignee = currentUser() AND status != Closed" -n 5 -f key,summary,status
uv run ${CLAUDE_SKILL_DIR}/scripts/core/jira-issue.py update PROJ-123 --assignee me --priority Critical
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-comment.py add PROJ-123 "Comment text"
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-comment.py add PROJ-123 "Comment text" --no-auto-escape --force  # deliberate -strikethrough-
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-transition.py do PROJ-123 "In Progress"
uv run ${CLAUDE_SKILL_DIR}/scripts/core/jira-worklog.py add PROJ-123 2h --comment "Work done"
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-create.py issue PROJ "Summary" --type Task

トランジション：list は各トランジションの ID と、画面で必要な項目を表示します。do には ID を渡してください。名前や遷移先のステータスは一意とは限らず、曖昧な場合は推測せずに拒否されます。 終了トランジション：--resolution <value>（Done、Won't do）を渡します。「設定できない」と拒否された場合は、指定を外して再試行してください。references/intent-verbs.md を参照してください。バージョン：jira-version.py を使う前に references/versions.md を読んでください。 メンション：投稿コマンドは [~username] を検証します（一致しない場合は候補を表示します）。get／work はユーザー名を出力します（references/fields-and-users.md を参照）。

関連スキル

jira-syntax：説明やコメントには Markdown ではなく、Jira Wiki マークアップを使用します。

編集者の意見を加えない

良し悪しではなく、何が起きたかを記述してください。references/no-editorializing.md を参照してください。

参考資料

• references/jql-quick-reference.md、references/jql-cookbook.md
• references/multi-profile.md — --profile
• references/troubleshooting.md — 認証、401/403
• references/issue-editing.md — 編集、削除、フィールドのクリア、--fields-json
• references/creation.md — 作成、--parent、フィールド、管理者スコープ（project、tempo-account.py）
• references/comments.md — 編集、削除、lint、- による本文の指定、制限付きコメント（--visibility）
• references/worklog.md — --started、期間、--tempo-account、delete
• references/attachments.md — アップロード、ダウンロード
• references/links.md — リンク
• references/agile.md — スプリント／ボード
• references/no-editorializing.md — 自画自賛をしない
• references/fields-and-users.md — カスタムフィールド ID、ユーザー、課題タイプ、画面フィールド（jira-fields.py meta）
• references/watchers.md — ウォッチ、登録、ウォッチャー一覧
• references/versions.md — 修正バージョン／影響バージョン、リリース、バージョンの CRUD
• references/qa-gather.md — 監査バンドル（関連項目、文章中の URL、変更履歴と作業ログに基づく自己レビュー確認 — 担当者ではありません）
• references/intent-verbs.md — work / qa / qa-fail / act、正確なトランジション名

認証

Cloud：JIRA_URL + JIRA_USERNAME + JIRA_API_TOKEN。Server/DC：JIRA_URL + JIRA_PERSONAL_TOKEN。~/.env.jira または ~/.jira/profiles.json で設定します。