Gentle AI — 分支与 PR 技能

Gentle AI — 分支与 PR 技能 是做什么的？

何时使用

当您需要执行以下操作时，请加载此技能：

• 为新修复或功能创建分支
• 在 Gentleman-Programming/gentle-ai 上打开拉取请求
• 准备变更以供审查

关键规则

1. 每个 PR 必须链接一个已批准的问题 — PR 正文中需包含 Closes/Fixes/Resolves #<N>，且该问题必须带有 status:approved 标签。未满足此条件的 PR 将被 CI 自动拒绝。
2. 常规 type:* 分类 — CI 会拒绝零个或多个 type 标签。请遵循规范的问题创建工作流契约：仅在当前直接人工指令明确指定目标/操作、已验证目标宿主能力，并使用一次边界突变和目标宿主回读时执行；否则等待，不进行任何突变。
3. 受保护策略标签 — 添加或删除 status:approved 或 size:exception 标签需要来自目标仓库维护者或仓库授权审批者的已验证策略授权，且认证参与者的目标宿主 viewerPermission 必须为 MAINTAIN 或 ADMIN。size:exception 标签还需要提供超出预算的理由文档。
4. 400 行审查预算 — 保持 PR 的变更行数（additions + deletions）在 400 行以内，或为 size:exception 标签记录理由。
5. 自动化检查必须通过 — 请参阅下面的自动化检查表。
6. 不要添加 Co-Authored-By 尾注 — 永远不要在提交中为 AI 添加署名。
7. 禁止强制推送到 main/master 分支 — 这些是受保护分支。

工作流

1. 确认问题具有 status:approved 标签
   gh issue view <N> --repo Gentleman-Programming/gentle-ai

2. 按照下面的命名规范从 main 分支创建新分支

3. 根据规范和设计实现变更

4. 本地运行检查（格式化 + 单元测试 + 端到端测试）

5. 使用 Conventional Commits 格式提交

6. 打开一个 PR 并引用相关 issue
   → 在 PR 正文中声明**恰好一个** type:* 结果
   → 在任何 PR 标签突变之前使用规范的问题创建工作流契约
   → 使用模板填写 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 中的模板。除非标记为可选，否则所有部分均为必填。

## 🔗 链接的问题

Closes #<N>

## 🏷️ PR 类型

- [ ] `type:bug` — 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` 标签的问题
- [ ] PR 变更行数保持在 400 行以内，或已记录 `size:exception` 理由并验证策略授权
- [ ] API 回读确认此 PR 上恰好有一个合适的 `type:*` 标签
- [ ] 单元测试通过（`go test ./...`）
- [ ] 端到端测试通过（`cd e2e && ./docker-test.sh`）
- [ ] 如有必要，我已更新文档
- [ ] 我的提交遵循 Conventional Commits 格式
- [ ] 我的提交不包含 `Co-Authored-By` 尾注

---

自动化检查

以下检查会在每个 PR 上运行，并且所有检查都必须通过才能合并：

检查项	验证内容	修复方法
检查 PR 认知负载	PR 变更行数（additions + deletions）在 400 行以内，或带有 size:exception 标签	拆分 PR，或记录 size:exception 理由并在执行规范工作流操作前验证策略授权
检查 Issue 引用	PR 正文包含 Closes/Fixes/Resolves #N	在 PR 正文中添加 Closes #<N>
检查 Issue 具有 status:approved 标签	链接的问题具有所需标签	仅在当前直接指令和目标宿主能力授权执行确切操作时，才使用规范的问题创建工作流契约；否则等待
检查 PR 具有 type:* 标签	PR 上应用了恰好一个 type:* 标签	仅在当前直接指令和目标宿主能力授权执行确切操作时，才使用规范的问题创建工作流契约；否则等待
单元测试	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\._-]+\))?!?: .+

格式

<type>(<optional-scope>)!: <description>

[optional body]

[optional footer]

允许的类型

类型	用途	PR 标签
feat	新功能	type:feature
fix	Bug 修复	type:bug
docs	仅文档变更	type:docs
refactor	代码变更（无行为变化）	type:refactor
chore	维护、依赖、工具	type:chore
style	格式化、lint 检查（无逻辑变化）	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/<short-description>

本地测试

# 单元测试
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'
## 🔗 链接的问题

Closes #42

## 🏷️ PR 类型

- [x] \`type:bug\` — Bug 修复（非破坏性修复）

## 📝 摘要

修复了当 HOME 环境变量未设置时，Claude Code 二进制检测在 Linux 上失败的问题。

## 📂 变更文件

| 文件 / 区域 | 变更内容 |
|-------------|---------|
| \`internal/agents/claude.go\` | 添加了 HOME 环境变量回退 |

## 🧪 测试计划

- [x] 单元测试通过（\`go test ./...\`）
- [x] 端到端测试通过（\`cd e2e && ./docker-test.sh\`）
- [x] 已手动在本地测试

## ✅ 贡献者检查清单

- [x] PR 已链接到带有 \`status:approved\` 标签的问题
- [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>