撰寫 issue
根據使用者的描述($ARGUMENTS 及對話內容)準備 issue 的文字內容。使用者會將文字複製到問題追蹤系統中,並在那裡建立 issue、設定負責人、優先順序、版本等。此技能不會在問題追蹤系統上建立 issue。
問題追蹤系統:僅限讀取
在問題追蹤系統(Redmine、GitHub、GitLab)上,AI 只能讀取 issue。絕對不得修改它們,即使使用者提出要求也不行:
- 不得建立、修改、關閉、重新開啟或刪除 issue;
- 不得新增留言、備註、附件、記錄工時;
- 不得變更狀態、負責人、優先順序、版本、標籤。
僅使用讀取請求:不帶 -X 或資料的 curl(即 GET)、gh issue view、gh issue list。絕對不得使用 POST、PUT、PATCH、DELETE,也不得使用 gh issue create、edit、comment、close、reopen、delete 等指令。如果需要將文字寫入問題追蹤系統,請將其寫入 issues/ 資料夾中的檔案,由使用者自行複製。
1. issues 資料夾
在專案根目錄(若存在 git 倉庫則為其根目錄)下,必須存在 issues/ 資料夾,內含一個忽略所有內容(除了自身)的 .gitignore 檔案:
*
!.gitignore
如果缺少資料夾或 .gitignore,請建立它們。如果 .gitignore 已存在但內容不同,請勿修改,並通知使用者。
2. 資訊收集與驗證
- 將請求分類為:錯誤、功能 或 任務(維護、更新、重構、文件等)。
- 在專案程式碼中驗證描述:搜尋提及的檔案、類別、路由、資料表及行為,確認它們存在且運作正常。記錄涉及的檔案。
- 找出遺漏或模糊的資訊,例如:
- 錯誤:重現步驟、預期行為與實際行為、環境(正式、測試、本機)、錯誤訊息或日誌;
- 功能:使用者對象、應能執行的操作、邊界情況、限制條件;
- 所有類型:判斷 issue 已解決的標準。
- 如果缺少必要資訊,或程式碼與描述不符,請先詢問使用者。將所有問題一次提出,且只問真正需要的內容。
請勿提出或實作解決方案:issue 只需要描述問題與預期結果。技術備註僅供後續處理人員參考。
3. 檔案寫入
將檔案寫入 issues/<YYYY-MM-DD>-<slug>.md,其中 slug 為全小寫標題,單字間以 - 分隔,不含特殊字元(最多 50 個字元)。如果檔案已存在,則加上 -2、-3 等後綴。
檔案結構:
# <簡短且具體的標題>
## 背景
[問題或任務的所在位置及其必要性。]
## 描述
[錯誤:當前行為。功能/任務:需要完成的事項。]
## 重現步驟
1. [...]
## 預期行為
[...]
## 驗收條件
- [ ] [可驗證的條件]
## 技術備註
- `檔案/路徑` — [相關原因]
## 參考資料
- [連結、相關 issue、日誌、螢幕截圖]
規則:
- 重現步驟 僅限錯誤類型使用;預期行為 適用於錯誤與功能。若 技術備註 或 參考資料 為空則可省略。
# 標題這一行對應問題追蹤系統的標題欄位;其餘從##級別標題開始的內容則放入描述欄位。- 使用 CommonMark 格式;程式碼與日誌需使用含語言標記的程式碼區塊。
- 語言:繁體中文。不使用表情符號。
- 文字簡潔明確,讓未參與對話的人也能理解:避免使用「如上述所提」或提及當前會話。
4. 回應使用者
告知使用者:
- 建立的檔案路徑;
- 建議的標題與類型(錯誤、功能、任務);
- 在問題追蹤系統中建立 issue 後,建議將檔案重新命名,加入 issue 編號(例如
issues/123-<slug>.md):這樣即使無法連線問題追蹤系統,open-issue 123也能找到該檔案。