Gentle AI — 分支與 PR 技能
使用時機
當您需要以下操作時，請載入此技能：
- 為新的修正或功能建立分支
- 在 Gentleman-Programming/gentle-ai 上開啟 Pull Request
- 準備變更以供審查
重要規則
- 每個 PR 都必須連結一個已核准的 Issue — 在 PR 內文中使用
Closes/Fixes/Resolves #<N>，且該 Issue 必須有status:approved標籤。沒有此連結的 PR 將被 自動拒絕 (CI)。 - 一般的
type:*分類 — CI 會拒絕零個或多個 type 標籤。請透過標準的 Issue 建立工作流程合約處理：當前直接的人類指令必須指定確切的目標/動作，目標主機的能力需經驗證，並使用一次性的突變與目標主機回讀；否則請等待，不要進行變更。 - 受保護的政策標籤 — 新增或移除
status:approved或size:exception需要驗證的政策授權，該授權來自目標主機儲存庫管理員或經過儲存庫授權的核准者（針對確切目標/動作），並且已驗證的操作者於目標主機上的viewerPermission為MAINTAIN或ADMIN。另外，size:exception需要提供超出預算的書面理由。 - 400 行程式碼審查預算 — 保持 PR 的變更行數（新增 + 刪除）在 400 行以內，否則需提供
size:exception標籤所需的理由說明。 - 自動檢查必須通過 — 請參閱下方的自動檢查表格。
- 不使用
Co-Authored-By尾綴 — 切勿在提交中新增 AI 貢獻署名。 - 不得強制推送至 main/master — 保護分支。
工作流程
1. 確認 Issue 有 status:approved 標籤
gh issue view <N> --repo Gentleman-Programming/gentle-ai
2. 從 main 分支建立新分支，並遵循下列命名慣例
3. 根據規格與設計實作變更
4. 在本機執行檢查 (格式化 + 單元測試 + 端到端測試)
5. 使用 Conventional Commits 格式提交
6. 開啟 PR 並引用 Issue
→ 在 PR 內文中宣告恰好一個 type:* 結果
→ 在進行任何 PR 標籤突變之前，使用標準的 Issue 建立工作流程合約
→ 使用模板填寫 PR 內文
7. 合併前所有自動檢查必須通過
分支命名
分支名稱必須符合此模式：
^(feat|fix|chore|docs|style|refactor|perf|test|build|ci|revert)\/[a-z0-9._-]+$
| 類型 | 範例 |
|---|---|
feat/ | feat/user-login |
fix/ | fix/duplicate-observation-insert |
docs/ | docs/api-reference-update |
refactor/ | refactor/extract-query-sanitizer |
chore/ | chore/bump-bubbletea-v0.26 |
style/ | style/fix-linter-warnings |
perf/ | perf/optimize-catalog-loading |
test/ | test/add-pipeline-coverage |
build/ | build/update-goreleaser-config |
ci/ | ci/add-e2e-docker-job |
revert/ | revert/undo-model-picker-change |
規則：
- 全部小寫
- 使用連字號、點號或底線作為分隔符（不含空格、不含大寫）
- 描述需簡短且具描述性
PR 內文格式
PR 內文必須遵循 .github/PULL_REQUEST_TEMPLATE.md 中的模板。除非標明為選填，否則所有章節皆為必填。
## 🔗 連結的 Issue
Closes #<N>
## 🏷️ PR 類型
- [ ] `type:bug` — 錯誤修正（非破壞性變更，修正問題）
- [ ] `type:feature` — 新功能（非破壞性變更，新增功能）
- [ ] `type:docs` — 僅文件
- [ ] `type:refactor` — 程式碼重構（無功能變更）
- [ ] `type:chore` — 建置、CI 或工具變更
- [ ] `type:breaking-change` — 破壞性變更
## 📝 摘要
<!-- 清楚說明此 PR 的作用與原因。 -->
## 📂 變更內容
| 檔案 / 區域 | 變更內容 |
|-------------|---------|
| `path/to/file` | 簡短說明 |
## 🧪 測試計畫
**單元測試**
\`\`\`bash
go test ./...
\`\`\`
**Go 格式化**
\`\`\`bash
go run ./internal/gofmtcheck
\`\`\`
**端到端測試** (需要 Docker)
\`\`\`bash
cd e2e && ./docker-test.sh
\`\`\`
- [ ] 單元測試通過 (`go test ./...`)
- [ ] Go 格式化通過 (`go run ./internal/gofmtcheck`)
- [ ] 端到端測試通過 (`cd e2e && ./docker-test.sh`)
- [ ] 已在本機進行手動測試
## ✅ 貢獻者檢查清單
- [ ] PR 已連結至具有 `status:approved` 標籤的 Issue
- [ ] PR 變更行數在 400 行以內，或已提供 `size:exception` 理由並驗證政策授權
- [ ] API 回讀確認此 PR 上恰好有一個適當的 `type:*` 標籤
- [ ] 單元測試通過 (`go test ./...`)
- [ ] 端到端測試通過 (`cd e2e && ./docker-test.sh`)
- [ ] 如有必要，我已更新文件
- [ ] 我的提交遵循 Conventional Commits 格式
- [ ] 我的提交不含 `Co-Authored-By` 尾綴
自動檢查
每個 PR 都會執行以下檢查，所有檢查都必須通過才能合併：
| 檢查項目 | 驗證內容 | 修正方式 |
|---|---|---|
| 檢查 PR 認知負載 | PR 變更行數（新增+刪除）在 400 行以內，或具有 size:exception | 拆分 PR，或提供 size:exception 理由並在標準工作流程操作前驗證政策授權 |
| 檢查 Issue 引用 | PR 內文包含 Closes/Fixes/Resolves #N | 在 PR 內文中加入 Closes #<N> |
檢查 Issue 是否有 status:approved | 連結的 Issue 具有所需的標籤 | 僅在當前直接指令與目標主機能力授權確切動作時，使用標準的 Issue 建立工作流程合約；否則請等待 |
檢查 PR 是否有 type:* 標籤 | PR 上恰好有一個 type:* 標籤 | 僅在當前直接指令與目標主機能力授權確切動作時，使用標準的 Issue 建立工作流程合約；否則請等待 |
| 單元測試 | go test ./... 通過 | 推送前修正失敗的測試 |
| Go 格式化 | go run ./internal/gofmtcheck 通過 | 推送前格式化格式錯誤的 Go 檔案 |
| 端到端測試 | cd e2e && ./docker-test.sh 通過 | 推送前修正失敗的端到端測試案例 |
Conventional Commits
提交訊息必須符合此模式：
^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\([a-z0-9\._-]+\))?!?: .+
格式
<類型>(<選用範圍>)!: <描述>
[選用內文]
[選用頁尾]
允許的類型
| 類型 | 用途 | PR 標籤 |
|---|---|---|
feat | 新功能 | type:feature |
fix | 錯誤修正 | type:bug |
docs | 僅文件 | type:docs |
refactor | 程式碼變更（無行為變更） | type:refactor |
chore | 維護、相依性、工具 | type:chore |
style | 格式化、程式碼風格（無邏輯變更） | type:chore |
perf | 效能改善 | type:feature |
test | 新增或更新測試 | type:chore |
build | 建置系統或外部相依性 | type:chore |
ci | CI 設定 | type:chore |
revert | 還原先前的提交 | 與被還原的類型相同 |
破壞性變更
在類型/範圍後加上 !：
feat(cli)!: rename --config flag to --config-file
BREAKING CHANGE: the --config flag has been renamed to --config-file.
破壞性變更對應到 type:breaking-change 標籤。
範例
feat(tui): add progress bar to installation steps
fix(agent): correct Claude Code detection on macOS
docs: update contributing guide
chore(deps): bump bubbletea to v0.26
refactor(pipeline): extract step executor
style: fix linter warnings in catalog package
perf(system): cache OS detection result
test(installer): add coverage for catalog step execution
build: update goreleaser config for arm64
ci: split unit and e2e test jobs
revert: undo model picker redesign
feat(cli)!: change default config path
指令
設定
# 開始前確認 Issue 已核准
gh issue view <N> --repo Gentleman-Programming/gentle-ai
# 建立分支
git checkout main && git pull
git checkout -b fix/<簡短描述>
在本機測試
# 單元測試
go test ./...
# Go 格式化
go run ./internal/gofmtcheck
# 單元測試 — 特定套件
go test ./internal/tui/...
# 單元測試 — 詳細輸出
go test -v ./...
# 端到端測試 (必須執行 Docker)
cd e2e && ./docker-test.sh
開啟 PR
gh pr create \
--repo Gentleman-Programming/gentle-ai \
--title "fix(agent): correct Claude Code detection on Linux" \
--body "$(cat <<'EOF'
## 🔗 連結的 Issue
Closes #42
## 🏷️ PR 類型
- [x] \`type:bug\` — 錯誤修正（非破壞性變更，修正問題）
## 📝 摘要
修正當 HOME 未設定時，Claude Code 二進位檔在 Linux 上偵測失敗的問題。
## 📂 變更內容
| 檔案 / 區域 | 變更內容 |
|-------------|---------|
| \`internal/agents/claude.go\` | 新增 HOME 環境變數備援機制 |
## 🧪 測試計畫
- [x] 單元測試通過 (\`go test ./...\`)
- [x] 端到端測試通過 (\`cd e2e && ./docker-test.sh\`)
- [x] 已在本機進行手動測試
## ✅ 貢獻者檢查清單
- [x] PR 已連結至具有 \`status:approved\` 標籤的 Issue
- [x] PR 變更行數在 400 行以內，或已提供 \`size:exception\` 理由並驗證政策授權
- [x] API 回讀確認此 PR 上恰好有一個適當的 \`type:*\` 標籤
- [x] 單元測試通過 (\`go test ./...\`)
- [x] 端到端測試通過 (\`cd e2e && ./docker-test.sh\`)
- [x] 如有必要，我已更新文件
- [x] 我的提交遵循 Conventional Commits 格式
- [x] 我的提交不含 \`Co-Authored-By\` 尾綴
EOF
)"
檢查 PR 狀態
gh pr checks --repo Gentleman-Programming/gentle-ai <PR-number>
gh pr view --repo Gentleman-Programming/gentle-ai <PR-number>