Issue Organize

批量智慧整理舊有 GitLab Issue。AI 分析所有 Issue 後，建議標籤補充、關聯建立、描述完善等改進方案，經確認後批量執行。

使用方式

基本用法（整理所有開放 Issue）

code

/issue-organize

指定範圍

code

/issue-organize --milestone="Sprint 60"

指定標籤過濾

code

/issue-organize --labels=backend,performance

指定狀態

code

/issue-organize --state=all

參數說明：

•--milestone（可選）：限定特定里程碑的 Issue
•--labels（可選）：限定特定標籤的 Issue
•--state（可選）：opened（預設）/ closed / all
•--limit（可選）：最多處理的 Issue 數量（預設來自 config 的 batchLimit）

前置條件

需要 .issue-config.json 存在。按以下優先順序搜尋：

•專案目錄: ./.issue-config.json
•使用者目錄: ~/.claude/.issue-config.json

若均不存在，提示：「找不到 .issue-config.json，請先執行 /issue-init 建立設定。」

工作流程

1. 讀取設定

從搜尋到的 .issue-config.json 讀取（專案層級優先於使用者層級）：

•gitlab.defaultProjectPath
•defaults.batchLimit（預設 50）
•defaults.dryRun（預設 true）
•organize.staleDays（預設 90）
•organize.autoLabels（預設 true）
•templates（用於分類參考）

2. 拉取 Issue 清單

使用 mcp__GitLab_communication_server__list_issues 取得目標範圍的 Issue：

•依據參數過濾（milestone、labels、state）
•分頁處理（每頁 100 筆，尊重 batchLimit 上限）

使用 mcp__GitLab_communication_server__list_labels 取得專案現有標籤。

顯示：

code

📋 已載入 47 個 Issue（開放狀態）
   現有 Labels: bug, feature, task, backend, frontend, ...

3. AI 批量分析

AI 對所有載入的 Issue 進行分析，產生「變更計畫」：

分析面向：

a. 標籤缺失或不一致

•有描述但缺少分類標籤（如 bug/feature/task）
•標籤與內容不符
•缺少模組標籤（如 backend/frontend）

b. 可建立關聯的 Issue

•標題或描述中提到其他 Issue（如 "參見 #123"）
•內容相關但尚未建立連結的 Issue
•可能重複的 Issue

c. 描述不完整

•缺少重現步驟（bug 類）
•缺少驗收條件（feature 類）
•描述過於簡短

d. 過期 Issue 標記

•超過 staleDays 未更新的 Issue

4. 產生變更計畫

以結構化格式顯示建議的變更：

code

📋 變更計畫（共 12 項建議）

【標籤補充】 5 個 Issue
┌─────┬────────────────────────┬───────────────┬──────────────────┐
│ IID │ 標題                   │ 現有 Labels   │ 建議新增 Labels  │
├─────┼────────────────────────┼───────────────┼──────────────────┤
│ #89 │ 表單送出後沒有回應     │ (無)          │ bug, frontend    │
│ #92 │ 新增匯出 CSV 功能      │ feature       │ backend          │
│ #95 │ 重構 API 路由結構      │ (無)          │ task, backend    │
└─────┴────────────────────────┴───────────────┴──────────────────┘

【建議關聯】 3 組
┌──────────┬──────────┬──────────────────────────┐
│ Issue A  │ Issue B  │ 關聯原因                 │
├──────────┼──────────┼──────────────────────────┤
│ #89      │ #91      │ 相似問題：表單送出相關   │
│ #92      │ #96      │ #96 的描述提到 #92       │
└──────────┴──────────┴──────────────────────────┘

【過期標記】 4 個 Issue
  #45, #52, #61, #68 - 超過 90 天未更新

5. 確認變更

使用 AskUserQuestion：

•問題：「以上是整理建議，請選擇要執行的項目」
•
選項：
1. •全部執行（推薦）
2. •只執行標籤補充
3. •只執行關聯建立
4. •逐項確認
5. •取消

若選擇「逐項確認」，對每個變更逐一詢問。

6. 批量執行

dryRun 判斷邏輯：

若 defaults.dryRun 為 true：

•只顯示「將會執行」的變更清單，不實際呼叫 API
•提示：「目前為 dryRun 模式，以上變更不會實際執行。若要執行，請在 .issue-config.json 中設定 defaults.dryRun 為 false，或使用 --execute 參數。」
•跳到完成報告（Step 7），但標記為「模擬執行」

若 defaults.dryRun 為 false（或使用 --execute 參數），依確認的變更計畫批量執行：

•標籤補充：mcp__GitLab_communication_server__update_issue（更新 labels）
•建立關聯：mcp__GitLab_communication_server__create_issue_link（建立 relates_to）
•過期標記：mcp__GitLab_communication_server__update_issue（新增 stale 標籤）

每處理 10 個 Issue 回報一次進度：

code

⏳ 進度: 10/12 項變更已執行...

7. 完成報告

code

✓ Issue 整理完成！

執行摘要：
  ✓ 標籤補充: 5 個 Issue 已更新
  ✓ 關聯建立: 3 組關聯已建立
  ✓ 過期標記: 4 個 Issue 已標記 stale

  跳過: 0 項（全部成功）

GitLab MCP 工具使用

步驟	工具	用途
載入 Issue	`list_issues`	批量取得 Issue 清單
載入標籤	`list_labels`	取得現有標籤
查詢關聯	`list_issue_links`	檢查既有關聯
更新 Issue	`update_issue`	補充標籤、描述
建立關聯	`create_issue_link`	建立 Issue 間關聯
建立標籤	`create_label`	若需要的標籤不存在

安全機制

•dryRun 預設開啟：首次使用時只顯示建議，不實際執行
•batchLimit：單次最多處理的 Issue 數量（預設 50）
•不會刪除：永遠不刪除任何 Issue
•不會關閉：不會自動關閉任何 Issue（過期只加標籤）
•可回溯：每個變更都記錄 before/after，完成報告中可看到

注意事項

•大量 Issue 的分頁處理可能需要數分鐘
•AI 分析品質取決於 Issue 描述的充分度
•建議先用 --limit=10 小範圍測試，確認 AI 建議品質後再擴大範圍
•標籤建議基於 config 中定義的模板和現有標籤系統