Issue Init
互動式建立 .issue-config.json，類似 npm init 的體驗。自動偵測 GitLab 專案資訊，引導使用者完成設定。
使用方式
code
/issue-init
無需參數，全程互動引導。
工作流程
Step 0: 環境檢查
- •檢查
.issue-config.json是否已存在（按優先順序搜尋）- •專案目錄:
./.issue-config.json - •使用者目錄:
~/.claude/.issue-config.json - •若任一存在 → 使用 AskUserQuestion 詢問：
- •覆寫（重新建立）
- •修改（互動式修改現有設定）
- •取消
- •專案目錄:
- •驗證 GitLab MCP Server 可用性
- •嘗試呼叫
mcp__GitLab_communication_server__list_namespaces測試連線 - •若失敗 → 顯示以下錯誤訊息並終止：
code
✗ GitLab MCP Server 無法連線 請確認： 1. ~/.claude/.mcp.json 中已設定 GitLab MCP Server 2. GitLab Personal Access Token 有效且具備 api scope 3. 網路連線正常
- •嘗試呼叫
Step 1: GitLab 連線偵測
按以下優先順序自動偵測：
- •
讀取
.release-config.json（若存在）- •直接複用
gitlab.projectId和gitlab.projectPath - •顯示：「已從 .release-config.json 偵測到 GitLab 設定」
- •直接複用
- •
解析 git remote URL
- •執行
git remote get-url origin - •解析出 group/project 路徑
- •執行
- •
GitLab API 查詢
- •呼叫
mcp__GitLab_communication_server__list_namespaces取得 Group 清單 - •呼叫
mcp__GitLab_communication_server__list_group_projects取得專案清單
- •呼叫
使用 AskUserQuestion 確認偵測結果：
- •問題：「已偵測到以下 GitLab 設定，請確認」
- •選項：
- •確認，使用偵測到的設定（推薦）
- •選擇其他 Group/專案
- •手動輸入 Project ID 和 Path
Step 2: 子專案設定（可選）
使用 mcp__GitLab_communication_server__list_group_projects 查詢 Group 下所有專案。
使用 AskUserQuestion：
- •問題：「是否要設定關聯子專案？（用於 /issue-create 的跨專案影響分析）」
- •選項：
- •自動加入偵測到的所有專案（推薦）
- •手動選擇要加入的專案
- •跳過，之後再設定
Step 3: 預設 Labels
呼叫 mcp__GitLab_communication_server__list_labels 取得專案可用的 Labels。
使用 AskUserQuestion：
- •問題：「請選擇建立 Issue 時的預設標籤」
- •選項：
- •使用建議的預設標籤: ["from-claude"]（推薦）
- •從專案現有 Labels 中選擇
- •不使用預設標籤
- •自訂輸入
Step 4: Issue 模板
使用 AskUserQuestion：
- •問題：「是否使用預設的 Issue 模板？（包含 bug、feature 兩種）」
- •選項：
- •使用預設模板（推薦）
- •自訂模板
- •跳過模板設定
預設模板內容：
bug（自動附加 label: Bug）:
描述模板包含以下區段：
- •狀況描述（客戶/客成訊息、工程人員簡述、反應用戶表格）
- •如何重現（重現步驟、出錯連結/截圖、重現環境裝置與瀏覽器 checklist）
- •完成定義（預期行為、API 邏輯、支援情境、可能解決方案）
- •關聯 Issue
feature（自動附加 label: Feature）:
描述模板包含以下區段：
- •功能描述（提出用戶表格）
- •完成定義
- •關聯 Issue
Step 5: 進階設定
使用 AskUserQuestion：
- •問題：「是否要配置進階設定？（拆分規則、整理規則）」
- •選項：
- •使用預設值（推薦）— maxSubIssues: 8, staleDays: 90
- •自訂設定
- •跳過
若選擇自訂：
- •拆分規則：最大子 Issue 數（預設 8）、是否繼承標籤（預設 true）
- •整理規則：過期天數（預設 90）、是否自動標籤（預設 true）
Step 6: 預覽與確認
顯示完整的 .issue-config.json 內容預覽（格式化 JSON）。
使用 AskUserQuestion：
- •問題：「以上是將要寫入的設定，確認嗎？」
- •選項：
- •確認，寫入檔案
- •返回修改
- •取消
Step 7: 選擇存放位置與寫入
使用 AskUserQuestion 詢問存放位置：
- •問題：「設定檔要存放在哪裡？」
- •選項：
- •使用者目錄 ~/.claude/.issue-config.json（推薦，所有專案共用）
- •專案目錄 ./.issue-config.json（僅此專案使用）
- •兩者都寫入（專案層級可覆蓋使用者層級）
根據使用者選擇，執行對應的寫入操作：
- •寫入
.issue-config.json到選定位置 - •合併更新
.claude/settings.local.json：- •讀取現有內容
- •在
permissions.allow中加入 Issue 相關的 MCP 權限（去重） - •需要加入的權限：
code
mcp__GitLab_communication_server__create_issue mcp__GitLab_communication_server__update_issue mcp__GitLab_communication_server__get_issue mcp__GitLab_communication_server__list_labels mcp__GitLab_communication_server__create_label mcp__GitLab_communication_server__create_issue_link mcp__GitLab_communication_server__list_issue_links mcp__GitLab_communication_server__create_issue_note mcp__GitLab_communication_server__list_issue_discussions mcp__GitLab_communication_server__list_namespaces mcp__GitLab_communication_server__get_namespace mcp__GitLab_communication_server__list_issues mcp__GitLab_communication_server__list_milestones mcp__GitLab_communication_server__update_issue_note mcp__GitLab_communication_server__get_project mcp__GitLab_communication_server__list_projects mcp__GitLab_communication_server__execute_graphql mcp__GitLab_communication_server__delete_issue
- •保留所有既有權限
Step 8: 完成訊息
根據實際存放位置顯示對應訊息：
若寫入使用者目錄：
code
✓ ~/.claude/.issue-config.json 已建立（全域共用） ✓ .claude/settings.local.json 已更新（Issue MCP 權限已加入） 下一步： /issue-create "Issue 標題" 建立 Issue /issue-split #123 拆分 Issue /issue-discuss 從對話建立 Issue /issue-organize 整理舊 Issue
若寫入專案目錄：
code
✓ ./.issue-config.json 已建立（僅此專案） ✓ .claude/settings.local.json 已更新（Issue MCP 權限已加入） 下一步： /issue-create "Issue 標題" 建立 Issue /issue-split #123 拆分 Issue /issue-discuss 從對話建立 Issue /issue-organize 整理舊 Issue
若寫入兩處：
code
✓ ~/.claude/.issue-config.json 已建立（全域共用） ✓ ./.issue-config.json 已建立（專案覆蓋） ✓ .claude/settings.local.json 已更新（Issue MCP 權限已加入） 下一步： /issue-create "Issue 標題" 建立 Issue /issue-split #123 拆分 Issue /issue-discuss 從對話建立 Issue /issue-organize 整理舊 Issue
.issue-config.json 完整結構
json
{
"$schema": "issue-config-v1",
"configVersion": "1.0",
"gitlab": {
"groupPath": "BizForm",
"defaultProjectId": "2183",
"defaultProjectPath": "BizForm/Home",
"projects": {
"home": { "projectId": "2183", "projectPath": "BizForm/Home" }
}
},
"defaults": {
"labels": ["from-claude"],
"confidential": false,
"dryRun": true,
"batchLimit": 50
},
"templates": {
"bug": {
"labels": ["Bug"],
"titlePrefix": "[Bug]",
"descriptionTemplate": "# 狀況描述\n\n- 客戶/客成訊息 (或附上 Mattermost 討論連結)\n \n- 工程人員簡述\n \n\n| 反應的用戶 | 聯繫人員 |\n| ---------- | ---------- |\n| xxx | xxxx |\n\n# 如何重現\n\n## 重現步驟\n 1. \n 2. \n\n- 出錯表單/畫面的連結/截圖\n - 表單、表單樣板網址請記得加上參數指定站台 `?depotId=gss_test`\n\n- 重現環境\n - 裝置\n - [ ] Win\n - [ ] Mac\n - [ ] iPhone\n - [ ] iPad\n - [ ] Android\n - 特定瀏覽器\n - [ ] Chrome\n - [ ] Edge\n - [ ] Safari\n - [ ] FireFox\n\n# 完成定義\n\n## 完整的預期行為\n\n- 設計稿/畫面截圖標示\n \n \n- API 預期回傳資料、處理邏輯\n - [API 名稱](swagger 連結)\n - \n\n- 需支援的情境/範例情境\n - \n\n## 可能解決方案\n\n- \n\n\n\n# 關聯 Issue\n\n- \n"
},
"feature": {
"labels": ["Feature"],
"titlePrefix": "[Feature]",
"descriptionTemplate": "# 功能描述\n\n\n| 提出的用戶 | 聯繫的人員 |\n| ---------- | ---------- |\n| xxx | xxxx |\n\n# 完成定義\n\n\n\n# 關聯 Issue\n\n\n"
}
},
"split": {
"maxSubIssues": 8,
"inheritLabels": true,
"linkType": "relates_to"
},
"organize": {
"staleDays": 90,
"autoLabels": true
}
}
GitLab MCP 工具使用
| 步驟 | 工具 | 用途 |
|---|---|---|
| 環境檢查 | list_namespaces | 測試 MCP 連線 |
| 連線偵測 | list_namespaces | 取得 Group 清單 |
| 連線偵測 | list_group_projects | 取得專案清單 |
| 子專案 | list_group_projects | 列出 Group 下所有專案 |
| Labels | list_labels | 取得可用標籤 |
注意事項
- •Token 不存在 config 中，由 GitLab MCP Server 管理（~/.claude/.mcp.json）
- •整份 .issue-config.json 全部可安全 commit 到 repo
- •多次執行 /issue-init 不會產生重複的權限條目（冪等合併）
- •若偵測到 .release-config.json，優先複用其 GitLab 設定