# 给 Vibe Coding 团队的 Git & GitHub 指南

> 你们团队都用 AI（Claude Code / Cursor）写代码，但搞不懂 git、github 到底是什么、为什么天天有人提。这篇用大白话全讲透，外加：**在网页上怎么点**、**怎么用一句话指挥 Claude Code 帮你搞定 git**。
>
> 看完你会懂 7 个词：git、github、issue、action、分支、PR、仓库。整篇就这些。

---

## 先一张图搞懂全局

```
你的电脑                          GitHub（云端网站）
┌──────────────────┐             ┌──────────────────┐
│  项目文件夹       │   push 推上去 │                  │
│  + git（存档功能）│ ───────────→ │   仓库（项目）    │  ← 团友在这里
│                  │              │  issue / PR /    │     协作
│  你让 Claude Code │   pull 拉下来 │  action 都在这   │
│  在这里改代码     │ ←─────────── │                  │
└──────────────────┘             └──────────────────┘
```

一句话：**git 是你电脑上的存档功能，github 是云端，团队在云端协作。** 你不用敲命令，Claude Code 替你敲，但你得懂这几个词的意思，才知道让它干啥、出了问题怎么回事。

---

# 第一部分　先搞懂这些词

## 一、git 是什么 —— 你本地的"自动存档"

你在 Claude Code 里跟它说"改一下登录页"，它帮你改了代码。改完呢？如果不存档，电脑一关、改崩了，就找不回来了。

**git 就是给整个项目文件夹装一个"存档功能"**，跟玩游戏存档一个道理：

- 每存一次档（叫 **commit / 提交**），就拍一个快照
- 随时能**回到任意一个旧存档**——改崩了、删错了，一秒回退
- 每次存档还能写句话说明"这次改了啥"，半年后也看得懂

> 你不用自己敲 `git commit`，跟 Claude Code 说「**提交一下，说明是 xxx**」，它就替你提交了。commit 中文就是"**提交**"——本质像游戏存档，每提交一次就存一个版本，随时能回退。

## 二、github 是什么 —— 把存档放到云端

git 存的档只在你自己电脑上。**github 就是一个网站，把你的存档放到云端。** 好处三个：

1. **备份**：电脑坏了、丢了，代码还在云端
2. **分享**：给别人一个网址就能看你的项目
3. **协作**：团队所有人连到同一个云端仓库，各改各的，最后合到一起

> github ≠ git。**git 是存档技术（在你电脑里），github 是存档的云盘（网站）。** 一个项目放到 github 上，就叫一个**仓库（repository）**。

## 三、仓库（repository）是什么 —— 一个项目

仓库就是 github 上的"一个项目文件夹"。你们团队做一个内部系统，那就是一个仓库。仓库网址长这样：

```
https://github.com/你的组织名/项目名
```

仓库里装着：所有代码文件、所有历史存档、所有 issue、所有 PR。一个项目 = 一个仓库。

## 四、提交（commit） / 推送（push） / 拉取（pull）

这三个是你和 Claude Code 打交道最频繁的动作，必须分清：

| 词 | 干嘛 | 比喻 | 跟 Claude Code 怎么说 |
| :--- | :--- | :--- | :--- |
| **commit 提交** | 在本地存一个版本快照（=游戏存档） | 拍快照 | 「提交一下，说明是：修复登录白屏」 |
| **push 推送** | 把本地存档传到云端 github | 把存档上传到云盘 | 「推送到 GitHub」 |
| **pull 拉取** | 把云端最新的东西拉到本地 | 从云盘下载最新 | 「拉一下最新代码」 |

**节奏**：改完 → 提交（commit）→ 推上去（push）。开工前 → 先拉一下（pull）别人最新的。

> 这三个动作你**永远不用自己敲命令**，上面右边那句话直接发给 Claude Code 就行。

## 五、分支（branch）是什么 —— 平行宇宙（团队不互相踩的关键）

**这是团队协作里最重要的一个概念。**

想象一下：你们 5 个人都直接改同一份代码（主干 main）。张三刚改完登录，李四也改了登录，两人一推——互相覆盖，谁的我都没了。这就是不用分支的灾难。

**分支就是平行宇宙**：

```
         （张三在这条线改登录）  feat/登录
        ┌──────────────────────────────┐
main ───┤
        └──────────────────────────────┘
         （李四在这条线改支付）    feat/支付
```

- 每个人（或每个任务）**开一条自己的分支**，在自己的分支上随便改
- **你改的不会影响主干，别人也看不到你的半成品**
- 改好、测好了，再申请**把你的分支合并回主干**

这样 5 个人各开各的分支同时干活，互不干扰，最后一个个合进去。

**分支命名**有个约定（让 Claude Code 开分支时告诉它用哪个前缀）：

| 前缀 | 用途 | 例子 |
| :--- | :--- | :--- |
| `feat/` | 新功能 | `feat/登录页` |
| `fix/` | 修 bug | `fix/白屏` |
| `docs/` | 改文档 | `docs/说明` |

> 跟 Claude Code 说「**开一个 feat/登录页 分支**」，它就替你开了。

## 六、issue 是什么 —— 项目里的任务卡

**issue 就是项目里的"留言 + 任务卡"**。在 github 仓库页有个 Issues 标签，点进去就能看到所有 issue。

issue 能用来干三件事：

1. **提需求**：我想要个新功能 / 想改个东西
2. **报 bug**：这里出错了
3. **提问**：这个怎么用

每个 issue 有编号（#12、#13…）、标题、描述、状态（开着 / 关闭）。团队长在里面排优先级、分配给谁。

> 你们的团队长用 **git-master** 这个工具一键配好后，提 issue 时会**弹出一张表单**让你填（而不是空白框），照着填就行——bug 表单会逼你写"怎么复现"，这样开发不用追着问。

## 七、PR（Pull Request）是什么 —— 申请把我的成果合进主干

你开了一条分支改完代码，怎么把它合回主干 main？**不能自己直接合**（会乱），要**申请**——这个申请就叫 **PR（合并请求）**。

流程：

```
你开分支改代码 → 推上去 → 在网页上提 PR（"请把我的分支合进 main"）
                                    ↓
                          负责人来看你的代码
                                    ↓
                          自动跑测试（action）+ 至少 1 人同意
                                    ↓
                                  合并 ✅
```

提 PR 时会**自动弹出一张表**让你填（git-master 配好的）：改了什么、关联哪个 issue（写 `Closes #12`，合并后那个 issue 自动关闭）、有没有测过。

**PR 是团队互相把关的机制**：谁的代码都不能直接进主干，必须有人审过、测试过了才行。

## 八、action（GitHub Actions）是什么 —— 自动跑的机器人

**action 是 github 上的"自动化机器人"**。你给它定个规则，它就自动干活，不用人盯。

最常见的一个：**每次有人提 PR，自动在云端把项目测试跑一遍，全绿了才允许合并。** 这个就叫 **CI（持续集成）**，是 action 最典型的用法。

- 你在网页上提了个 PR
- 底部自动出现一个 **CI** 的进度条：⏳ 跑测试中… → ✅ 通过 / ❌ 失败
- 失败了，这个 PR 就**合不了**，必须改到通过为止

> action 不用你写，团队长跑 **git-master** 时它会**自动检测你们用的技术栈**（Node/Python/Go…），自动生成对应的测试 action。你要做的只是：提完 PR 等底下那个 ✅ 亮起来。

---

# 第二部分　你们团队怎么协作（团队长看）

团队协作的规范，**团队长跑一次 git-master 就全配好了**，其他人自动受益。

## git-master 一键配的东西

团队长在项目里跟 Claude Code 说「**配置 git 协作**」，回答几个选择题（托管在 github / 内部团队 / 谁负责 review / 要不要 CI），它就自动生成：

| 配好的东西 | 解决什么 |
| :--- | :--- |
| 提需求表单 / 报 bug 表单 | 提 issue 时有结构化表单填，不用写空白 |
| PR 模板 | 提 PR 时自动弹表，写清改了啥、关联哪个 issue |
| CODEOWNERS | 改了哪个目录，自动 @ 负责人来 review |
| CI（action） | 提 PR 自动跑测试，不绿不让合 |
| 分支保护指引 | 把主干 main 锁住，谁都不能直接改，必须走 PR |

> 分支保护要团队长照 git-master 给的指引，去 github 设置里点一下打开（一次性）。开了之后 main 就锁了，保护你们不被手抖改崩主干。

配完之后，**全团队的协作规则就统一了**：提需求走表单、改代码走分支+PR、合并前自动测+有人审。

---

# 第三部分　在网页上怎么操作（github.com）

> 你不用装任何东西，浏览器打开你们仓库的网址，登录 github 账号就行。

## 1. 看仓库

打开 `https://github.com/你的组织/项目名`，看到的就是仓库主页。从上往下：
- 仓库名
- 一排标签页：**Code**（看代码）/ **Issues**（任务卡）/ **Pull requests**（合并申请）
- Code 页中间是文件列表，下面是 README（项目说明）
- 右上角绿色的 **Code** 按钮 = 下载代码

## 2. 提一个 issue（提需求 / 报 bug）

1. 点 **Issues** 标签 → 绿色 **New issue** 按钮
2. 选表单：**提需求** 或 **报 Bug**
3. 照表单填（报 bug 重点写"怎么复现"——按 1.2.3.4 步骤写）
4. 提交

## 3. 提一个 PR（代码改完，申请合并）

代码在分支上改完、推上去后：

1. 打开仓库，点 **Pull requests** 标签 → **New pull request**
2. 左边选 `main`，右边选你的分支（比如 `feat/登录页`）
3. 点 **Create pull request**
4. PR 模板自动弹出，填：改了什么、关联 issue（写 `Closes #12`）
5. 提交

然后等：底部 CI 自动跑测试 → 负责人 review → 全绿+同意 → 合并 ✅

## 4. 看 action 的结果

提了 PR 后，PR 页面底部会自动出现一个 **CI** 的状态：
- ⏳ 黄色 = 测试在跑
- ✅ 绿色 = 通过，可以合并
- ❌ 红色 = 失败，点进去看哪条测试挂了，改完重新推

---

# 第四部分　怎么跟 Claude Code 说（让它帮你操作 git）

> **这是 vibe coding 团队的核心技能。** 你不用记任何 git 命令，把下面这些话发给 Claude Code 就行。它全替你干了。

## 日常话术卡（存下来照着发）

| 你想干嘛 | 直接发给 Claude Code |
| :--- | :--- |
| 开始干一个新活 | 「拉一下最新代码，然后开一个 `feat/xxx` 分支」 |
| 改完了，提交 | 「提交一下，说明是：修复了登录页白屏」 |
| 传到云端 | 「推送到 GitHub」 |
| 同步别人的最新改动 | 「拉一下最新代码」 |
| 代码改崩了，回退 | 「帮我回退到上一个版本」 |
| 推送被拒（别人先推了） | 「拉一下最新，有冲突帮我解决」 |
| 第一次关联云端仓库 | 「帮我把这个项目关联到 GitHub 上的 xxx 仓库」 |

**第一次推送时，Claude Code 会自动帮你配好 SSH key**（云端身份验证），你不用管它具体干了啥。

## 一次完整改动的标准流程（背下来）

```
1. 「拉一下最新代码」           ← 同步昨晚别人的改动
2. 「开一个 feat/xxx 分支」     ← 开自己的平行宇宙
3. （让 AI 改代码）
4. 「提交一下，说明是：xxx」      ← 提交（commit）
5. 「推送到 GitHub」            ← 传到云端
6. 去网页提 PR                  ← 申请合并
7. 等 CI 绿 + 有人同意 → 合并
```

> 铁律一句话：**永远先开分支再改，绝不在 main 上直接动。** 这不是规矩死板，是保护你不把别人的代码覆盖掉。

---

# 第五部分　每天的节奏 + 避坑

## 节奏

**开发的一天**：开工拉一下（pull）→ 开分支改 → 提交推上去（commit+push）→ 网页提 PR → 等审 → 合并

**提需求/报 bug 的人**：网页 Issues → New issue → 选表单填 → 提交。跟踪进度看 Issues 列表。

## 避坑

**Q：我能直接在 main 上改吗？**
不能。分支保护开着时，main 谁都直接动不了，必须走分支+PR。这是防你手抖改崩主干。

**Q：代码改崩了怎么办？**
跟 Claude Code 说「回退到上一个版本」。git 的核心就是能随时回退。**千万别让它 `force push` 强推**，那会覆盖别人代码。

**Q：CI 一直红怎么办？**
点进 PR 底部那个 ❌ 看报错，跟 Claude Code 说「CI 挂了，帮我看看 xxx 测试为什么失败」。

**Q：推送被拒绝（rejected）？**
别人比你先推了。跟 Claude Code 说「拉一下最新，有冲突帮我解决」，它自动处理。

**Q：issue / PR 上不会写？**
照自动弹出来的表单填就行，不用自己想格式。

---

## 最后，记住这张总图

```
git = 本地存档      github = 云端        仓库 = 一个项目
commit = 提交       push = 传上去        pull = 拉下来
分支 = 平行宇宙     PR = 申请合并        action = 自动机器人（跑测试）
issue = 任务卡
```

**团队协作就三句话**：提需求/报 bug 走 issue 表单，改代码先开分支再提 PR，主干 main 锁住谁都不能直接动。剩下的，跟 Claude Code 说话就行。