---
name: git-main
description: >
  当用户要求创建分支、提交、合并或推送代码时使用此技能，
  确保符合项目 Git 工作流与约定式提交规范，并进行分支校验。
  触发短语：创建分支、提交代码、合并分支、推送、git commit、
  git push、create branch、merge branch。
---

# Git 工作流技能

## 项目约束

- 保护分支：`develop` / `staging` / `production`，三者均禁止直接提交、直接推送与强推，必须走 PR
- 保护分支 PR 必须等待 `agent-assets-check` 状态检查通过后再合并
- 临时分支：`feature/*`、`bugfix/*`、`hotfix/*`，kebab-case 命名
- 不主动执行 `git commit`，除非用户明确要求
- 仅纳入当前任务相关改动；发现无关改动先提示

## 工作流

### 1. 分支安全检查

- `git rev-parse --abbrev-ref HEAD` + `git status -sb` 查看当前分支与变更
- 若在保护分支（`develop` / `staging` / `production`）：允许查看与拉取，禁止直接提交/推送/强推，变更必须转到功能分支并走 PR

### 2. 创建/切换分支

- feature/bugfix 从 `develop` 分出；hotfix 从 `production` 分出
- 生成合规名（kebab-case），执行：
  ```
  git checkout <source> && git pull origin <source>
  git checkout -b <type>/<description>
  git push -u origin <type>/<description>
  ```

### 3. 提交（仅用户要求时执行）

**commit 前自检顺序**：先 ai-review-local（架构纠偏）→ 后 `/simplify`（细节打磨）→ 再 commit。两者正交互补：

| 步骤 | 命令 | 覆盖维度 | 何时跑 |
|---|---|---|---|
| 1. AI Review 本地前置 | `bash scripts/dev/ai-review-local.sh` | 契约面 / 数据迁移 / 测试覆盖 / 安全 / 文档一致性 / 高风险路径合规 / 代码逻辑 | 触碰契约面 / 高风险路径 / >10 文件 PR **强烈推荐**；小改动可跳过 |
| 2. /simplify | skill 调用 | reuse / quality / efficiency | 永远跑（CLAUDE.md 铁律） |
| 3. commit | `git commit` | — | 上述两步无 block 后 |

- 只在功能分支（feature/bugfix/hotfix）上提交，保护分支禁止直接提交
- 首选 `git add -p` 或指定路径，保持最小变更集
- 默认跳过测试；用户要求时运行 `npm run test`
- 提交信息格式（约定式 + 中文主题 + 三段正文）：

  ```
  <type>(<scope>): <中文主题，≤50字符>

  变更摘要：
  - ...

  影响范围：
  - ...

  验证：
  - 已执行命令 / 或注明未运行测试及原因
  ```

  type: `feat` / `fix` / `docs` / `style` / `refactor` / `perf` / `test` / `chore` / `ci` / `revert`

- 使用 here-doc 保证多行正文：
  ```bash
  cat <<'EOF' > /tmp/commit-msg.txt
  <type>(<scope>): <subject>

  变更摘要：
  - ...
  EOF
  git commit -F /tmp/commit-msg.txt
  ```

- 用户未要求提交时，仅输出建议的 `git add` 范围与提交信息草稿

### 4. 合并与推送

- 允许方向：`feature|bugfix → develop → staging → production`
- hotfix 从 `production` 分出，修复后同步回 `develop`、`staging`
- 禁止跳过环境；保护分支走 PR
- 推送前检查 `git status`，必要时 `git diff --staged`

### 5. PR 描述

创建 PR 时按 [`docs/standards/13-pr-description-spec.md`](../../../docs/standards/13-pr-description-spec.md) 写描述（v2 两层设计：上半部分核心叙事 + 下半部分未来回顾段）：

- **解决 issue 的 PR 必填 `Closes #N`**（漏写会让 issue 变孤儿）。一个 issue 一行，不要用逗号合并。
- 「摘要」一句话讲清做了什么 + 为什么。
- 「为什么现在做」承接触发场景（给未来 retro 留 context）。
- 「如何验证」用 checkbox + 有勾选状态，不是"已通过"四个字。
- 「破坏性变更」始终保留（N 时写"否"），便于未来 changelog 检索。
- 触碰契约面 / 架构 / 高风险路径 → 必填「权衡与备选方案」。
- 性能 / 体积 / CI / 覆盖率类 PR → 必填「度量指标」（before/after）。
- 「后续跟进」永远填（无衍生写"无"），强制思考一遍。
- 写"最终状态"，不写"演进过程"；不堆"我们/本 PR/AI"等填充主语。
- 踩坑沉淀放 `.learnings/`，PR body 只引路径不复制全文。
- **PR push 新 commit 后必须 PATCH title + body 反映最终状态**（不要堆"追加 commit"/"补丁式 addendum"等演进史段，违反元规则 #1 + #6）。具体做法：
  - 重写整个 body 按"合并后是什么"视角
  - 在 `## 主要组成` / `## 后续跟进` / `## 权衡与备选方案` 等已有段补充新增内容，不新增 "## 追加 ..." 段
  - **如果 PR 内容已超出原 title 涵盖范围（例如原标题只描述第 1 个 commit），同步 PATCH title**
  - 用 Gitea API `PATCH /repos/<owner>/<repo>/pulls/<num>`，title + body 字段一次传完整新值
- 模板：`.gitea/PULL_REQUEST_TEMPLATE.md`（**仅 Gitea 网页创建 PR 时自动加载；API / CLI 创建需手动遵循结构**）

## 禁止事项

- 在保护分支（develop/staging/production）直接提交、直接推送或强推
- 未经用户确认执行 `git commit`
- 分支命名不合规或合并方向越级
- 提交信息不符合约定式格式（如 `update` / `fix` / `WIP`）