為儲存庫初始化 Issues 與 Project
設定其他 issue-* 技能所依賴的慣例。所有操作都會寫入 GitHub(標籤、看板、儲存庫連結):請先說明即將建立的內容並取得使用者同意。不會進行任何 git push。
先決條件:gh auth status 顯示 repo 和 project 範圍(否則請執行 gh auth refresh -s project);已安裝 jq。
1. 檢查(唯讀)
REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner); OWNER=${REPO%%/*}
gh label list --repo "$REPO" --limit 100
gh project list --owner "$OWNER"
2. 標籤
建立下方標準標籤(名稱|說明|顏色)。加入儲存庫本身的元件標籤(預設為 backend、frontend;視情況刪減或新增)。除非被要求,否則保留 GitHub 的預設標籤(enhancement、documentation……)。
while IFS='|' read -r n d c; do
gh label create "$n" --repo "$REPO" --description "$d" --color "$c" --force
done <<'EOF'
bug|Something isn't working|d73a4a
feature|New user-facing capability|a2eeef
tech-debt|Tracked technical debt|fbca04
epic|Multi-issue effort|5319e7
backend|Backend / services|0e8a16
frontend|Frontend / web app|1d76db
performance|Performance|fef2c0
security|Security|d93f0b
testing|Tests / CI / E2E|c5def5
privacy|Privacy / GDPR|bfdadc
ai|Addressable by an AI agent without human intervention|7057ff
needs-context|AI-addressable once a quick check or decision is answered (also carries ai)|fbca04
needs-human|Needs a device, store/legal/owner decision, external access or a roadmap choice|d93f0b
wontfix|This will not be worked on|ffffff
EOF
gh label list --repo "$REPO" # 建立成功時無輸出,請務必驗證
3. 看板
A. 複製參考看板(欄位與視圖,不包含項目):
gh project copy <source-number> --source-owner <owner> --target-owner "$OWNER" --title "<Repo name>"
B. 從空白開始:
gh project create --owner "$OWNER" --title "<Repo name>" --format json -q '.number' # 記下此編號 $N
for f in Reach Impact "Confidence (%)" "Effort (days)" RICE; do
gh project field-create "$N" --owner "$OWNER" --name "$f" --data-type NUMBER
done
新看板已內建 Status 欄位,包含 Todo、In Progress、Done;這已足夠(可在看板 UI 中新增 Defer 選項)。
接著連結看板並驗證:
gh project link "$N" --owner "$OWNER" --repo "$REPO"
# 然後遵循 issue-project-fields 中的「先解析 ID」步驟:它必須能找到看板與所有欄位
4. 在儲存庫中記錄
將此段落加入儲存庫的代理程式指令檔案(AGENTS.md、CLAUDE.md 或兩者),填入 <...> 佔位符(儲存庫、看板網址,以及你在步驟 2 建立的元件標籤;若技能來自外掛,請說明並命名外掛)。在分支上提交,不要在預設分支上提交。
## 工作追蹤(GitHub Issues)
待辦事項存放在 **GitHub Issues**(`<owner/repo>`),並在 **<board title>** 專案(<board URL>)中追蹤。議題是情境與狀態的真實來源;請以議題編號(`#123`)和標籤來引用工作。工作流程技能:`issue-search`、`issue-file`、`issue-start`、`issue-pr-refs`、`issue-close-out`、`issue-project-fields`、`issue-score`、`issue-link`、`issue-plan-doc`、`issue-file-found`、`issue-audit-scores`、`issue-project-init`(<技能來源>)。
### 標籤
| 群組 | 標籤 | 規則 |
|---|---|---|
| 類型 | `bug`、`feature`、`tech-debt`、`epic` | 每個議題恰好一個 |
| 元件 | <例如 `backend`、`frontend`> | 可選多個 |
| 主題 | `performance`、`security`、`testing`、`privacy` | 可選 |
| 代理程式路由 | `ai`、`needs-context`、`needs-human` | 可選。`ai` = 代理程式可無人值守執行;`needs-context` = 代理程式在快速問題得到回答後即可執行(同時帶有 `ai`);`needs-human` = 需要裝置、外部存取或擁有者決定 |
### 專案欄位
| 欄位 | 值 | 說明 |
|---|---|---|
| Status | Todo / In Progress / Done | 僅由編排代理程式設定 |
| Reach | 1–5 | 影響的使用者數量 |
| Impact | 0.5–3 | 影響的幅度 |
| Confidence (%) | 整數百分比,例如 `70` | |
| Effort (days) | 數字 | |
| RICE | `(Reach × Impact × Confidence) / Effort` | 同時在本文中寫成 `**Score:** RICE x = (R × I × C%) / Ed`,以便議題可單獨閱讀 |
### 議題本文與工作流程
**議題本文**包含完整記錄:描述、當前狀態、需要完成的事項、重要性、相關檔案、估算。使用 `#n` 連結相關工作;使用「blocked by」(本文與 dependencies API,參見 issue-link)來表達順序。大型工作為 `epic`,其計劃存在於議題本文中,子項目則為子議題。
- **開始之前:** 先搜尋(`issue-search`);盡量重複使用或擴展現有議題,不要提重複的。
- **工作進行中:** 將項目設為 In Progress 並指派給自己(`issue-start`);分支名稱應包含議題編號(`feat/123-short-desc`)。Bug 與技術債需從失敗的測試開始。將未預期發現的項目記錄為新議題,而非擴大範圍(`issue-file-found`)。
- **完成時:** 每個 PR 都應引用其對應的議題(每個議題使用 `Closes #n`,史詩級議題使用 `Part of #n`;`issue-pr-refs`);合併後將 Status 設為 Done 並更新相關議題(`issue-close-out`)。
- `gh` 需要 `project` 範圍(`gh auth refresh -s project`)。只有編排代理程式可以更改議題/專案狀態;委派的子代理程式不得建立、編輯或關閉議題。
5. 選用:建立一個史詩級議題
issue-file(類型 epic)→ issue-plan-doc → 對每個子項目執行 issue-file + issue-link + issue-project-fields + issue-score。
注意事項
gh label create、gh project copy|link|item-edit在成功時皆無輸出:務必驗證。- 複製的看板會是空的;
item-add具冪等性。 - 子議題與依賴關係的 REST 呼叫使用議題的數字資料庫 ID(參見
issue-link)。 - Confidence 是整數百分比(
70);ID 因看板而異,因此請務必重新發現它們(issue-project-fields)。