---
title: 别让AI替你捣乱-致零软件工程经验新人的指南
date: "2026-6-9 9:11:00"
desc: GitHub 最近这几个月频繁崩溃，由于我订阅了 GitHub status 的邮件通知，导致某一天半夜连续受到几十封邮件轰炸！
categories: 指南
tags:
    - ai
    - 指南
    - 新人
abbrlink: zero-se-newcomer-guide
cover: https://metrics.lecoq.io/xingwangzhe
---

> 本文核心观点、结构与内容由本人撰写，AI 仅参与排版修饰与润色。目的就是强调人的主观能动性与 AI 指挥协作。

---

## 引言

GitHub 最近这几个月频繁崩溃，由于我订阅了 [GitHub status](https://www.githubstatus.com/) 的邮件通知，导致某一天半夜连续受到几十封**邮件轰炸**！

> **根本原因**：胡乱的 PR，没完没了地跑 CI/CD，让 AI 替代人做各种事情，却不加以任何思考。

最近维护仓库也看到了许多**噪音 PR**。我觉得真的非常有必要讲讲——AI 时代下，**零软件工程经验的人如何去贡献**。

---

## 软件工程的概念

> 将系统化的、规范的、可量化的方法应用于软件的开发、运行和维护，以及对这些方法的研究 —— IEEE

当然不止软件——所有工科都学过至少一门工程管理课。作为外部 contributor，你至少需要一点工程知识，才能做好贡献。不过这只是**充分不必要条件**：

| 条件         | 说明                               |
| ------------ | ---------------------------------- |
| 充分但不必要 | 上过工程管理课不等于一定能做好贡献 |
| 必要但不充分 | 没上过课不等于做不好贡献           |

你不必上那些"务虚"的课——只要你做过项目、参与过软件协作、写过 Issue、提过 PR，自然会懂。

> 有人说这不就成了悖论了吗：没经验很难做好 PR，但不做又没有经验。**你说的对。** 所以本文讲的就是——**面向零软件工程经验新人的指南**。

---

## 万事开头难，先了解项目

AI 提效，首先在于快速了解项目。我可以假定你不会看每一行代码，但至少要看：

- `README.md`
- `CONTRIBUTING.md`
- `AGENTS.md` / `CLAUDE.md`（仓库给 AI 准备的文档）

### 架构分析

让 AI 帮你画出项目架构图，比从零啃代码高效得多：

| 模式         | 适用场景                         | 输出格式     | 稳定性               |
| ------------ | -------------------------------- | ------------ | -------------------- |
| TUI 模式     | 终端命令行工具（如 Claude Code） | ASCII 图表   | 终端宽度变化可能错位 |
| ChatBox 模式 | Web 端 AI 对话工具（如 ChatGPT） | Mermaid 图表 | 渲染稳定，可截图保存 |

**TUI 模式** — 用 ASCII 作画：

```markdown
请你阅读当前仓库的 README, CONTRIBUTING, AGENTS.md 等文档，
然后分析架构，最后画出 ASCII 图表来展现架构。
```

**ChatBox 模式** — 用 Mermaid 渲染：

```markdown
请你阅读当前仓库的 README, CONTRIBUTING, AGENTS.md 等文档，
然后分析架构，最后画出 Mermaid 图表来展现架构。
```

> **新人建议**：优先使用 ChatBox 模式的 Mermaid 图表，渲染稳定、可截图反复参考。

---

### 隐性知识之一：错综复杂的包依赖

> 我想应该没有哪个新人蠢到不自知，去用 AI 贡献基础库却一点人工 review 都不做。

大部分贡献发生在**应用层软件**上。尽管仓库文档看似实现了知识闭包，但这些项目无一例外地依赖：

- 大量**第三方库**
- 一两个**主体框架**

这就是**隐性知识之一**——维护者默认你已经了解这些包了，但对新人来说，这是完全空白的领域。AI 也不会主动提这些事，因为它默认你懂。

<details>
<summary>补充提示词：快速补全依赖知识</summary>

```markdown
分析完架构之后，请你再分析：

1. 当前项目的包管理器（npm / pnpm / yarn / cargo 等）
2. 核心第三方包及其作用
3. 主体框架是什么
4. 这些第三方的文档链接
```

</details>

> **核心目的**：避免**重复造轮子**与低效代码。  
> 明明查文档在配置文件里改一行开关就能实现的功能，非要用 AI vibe 出一个复杂度爆炸、难以 review 的实现——得不偿失。

---

### 隐性知识之二：编码规范与测试要求

每个项目都有自己的代码风格和测试要求。在你动手写代码之前，务必让 AI 帮你理清：

```markdown
请分析当前项目的：

- 代码风格（缩进、命名规范、注释习惯）
- 是否有 linter 配置
- CI 中跑哪些测试
- 提交 PR 前需要通过什么检查
```

> 这一步花不了几分钟，但能避免你辛辛苦苦写出的 PR 因为格式问题或 CI 挂掉而被直接关闭。

---

## 准备贡献，先看 Issue

> **请不要直接 PR！作为新人，应该先去 Issue 看看。**

你也许有奇妙的想法、天马行空的创造，但请先看看 Issue，避免撞车。

安装 [`gh CLI`](https://cli.github.com/)，让 AI agent 帮你快速筛选：

```bash
# 带有 good-first-issue 标签——最适合新人入手
gh issue list --label "good first issue" --limit 20

# 按关键词搜索
gh issue list --search "bug" --limit 20
```

---

### 场景 A：解决现有 Issue

如果你的想法和某个 Issue 吻合：

1. 在 Issue 下留言，表示准备接手
2. 去理解内容，补全必要的隐性知识
3. 再动手写代码

> **重要**：很多仓库要求你先在 Issue 下留言申请被 assign，再开始写代码。直接闷头写完才发现没人 assign 你——PR 可能白做。

---

### 场景 B：提出新 Issue

一个好的 Issue = **清晰表达** + **解决思路** + **结构思考**。

很多仓库的 Issue 都有模板。请你：

- [ ] 按照模板逐项填写
- [ ] **不要删除模板**然后直接粘贴 AI 内容
- [ ] 用 `gh` 命令让 AI 按模板格式填写
- [ ] 完成前置任务（看文档、跑测试、签 CLA 等）
- [ ] 最后再创建 Issue

```markdown
请你查看当前仓库的 Issue 模板，根据我要反馈的内容按照模板格式填写，
不要跳过任何必填项。填写完成后用 gh issue create 命令创建。
```

---

## 准备贡献，最关键的是 PR

**PR** = Pull Request（拉取请求），把你自己的代码变更提交给上游仓库、请求合并。

这是整个贡献流程的**临门一脚**，也是最容易翻车的地方。借助 AI 创建 PR 之前，以下关键点**你必须亲自把关**：

---

### 1. 关联 Issue

PR 描述中加上 `Closes #xxx` 或 `Fixes #xxx`，合入后 Issue 自动关闭。

> 如果你的 PR 没有对应的 Issue——先反思一下：是不是跳过了上一章？

---

### 2. 填写 PR 模板

| 必填项                  | 说明           |
| ----------------------- | -------------- |
| 做了什么（What）        | 变更的具体内容 |
| 为什么这样做（Why）     | 动机和背景     |
| 如何测试（How to test） | 验证方法       |
| 关联的 Issue            | `Closes #xxx`  |

```markdown
请你查看当前仓库的 PR 模板，根据我本次的代码变更按照模板格式填写
PR 描述，关联 Issue #xxx，然后用 gh pr create 命令创建 PR。
```

---

### 3. 自己先 Review 一遍

> **这是最重要的一步。** AI 生成的代码，你必须**逐行看一遍**。

你不一定需要懂每一行逻辑，但至少要能回答这三个问题：

1. **改了什么文件？** 为什么是这些文件？
2. **有没有改到不该改的地方？**（AI 可能顺手"优化"了无关代码）
3. **提交信息**（commit message）是否清晰？

> 三个问题答不上来 = review 没到位 = **请不要提交**。

---

### 4. 保持 PR 小而聚焦

| 正确做法               | 错误做法                             |
| ---------------------- | ------------------------------------ |
| 一个 PR = 只修一个 bug | 一个 PR = 修 bug + 重构 + 改文档错字 |
| 多个功能拆成多个小 PR  | 全部塞进一个 PR                      |

---

> **总结**：Issue -> 模板 -> 关联 -> Review -> 小步提交，串联起来才是一个**正正好的 PR**。

---

## 题外话

虽是题外话，但这恰恰是软件工程之外**最重要的常识**——参与社区合作的隐性知识前提，或者说一种默契的社交礼仪。

> 每个人的容忍程度是有限的，大部分人可能**一次机会也不会给犯错的人**。

---

### 你是来提意见的，不是来搞事情的

有些人在 Issue 里留言吐槽，不附带任何错误信息，只是一味地说"这个不好那个不好"。

| Issue 是议事的地方       | Issue 不是发泄情绪的地方 |
| ------------------------ | ------------------------ |
| 附上复现步骤             | 纯情绪输出               |
| 说明期望行为 vs 实际行为 | "这个真垃圾"             |
| 提供环境信息             | 无凭无据                 |

> 一个好的 Issue（哪怕只是提 bug）必须包含：**复现步骤、期望行为、实际行为、环境信息**。缺了这些，维护者想帮你也无从下手。而且社区是有记忆的——你在 A 仓库的不当言行，可能让你在 B 仓库也寸步难行。

---

### 不要胡乱 PR

| 场景                     | 建议                          |
| ------------------------ | ----------------------------- |
| 有明确 Issue 且被 assign | 放心提 PR                     |
| 目的明确、表述充分       | 可以直接 PR（不强制先 Issue） |
| 新人、不确定、没把握     | 先 Issue 后 PR，证明态度      |

> "先 Issue 后 PR"不是金科玉律，但对于新人来说，遵守这条不成文的规矩至少能证明你是认真的——不至于一上来就被喷。

---

### 说人话

这一条看起来最简单，但 AI 时代下反而成了**重灾区**。

> 很多新人把 AI 生成的回复——充斥着"很高兴收到您的反馈！我将深入分析……"之类的套话——**原封不动**地粘到 Issue 或 PR 里。

请记住：**Issue 和 PR 是人与人之间的交流**，你面对的是另一个真实的维护者，不是 AI。

你应当：

- 删掉 AI 生成的废话套话，只保留实质内容
- 用自己的话重新组织一遍——这个过程本身就是你是否真正理解了问题的**试金石**
- 你自己都看不懂 AI 写的内容？**就不要发出去**

---

> **一句话总结**：用 AI 辅助你思考，而不是让 AI 代替你思考。**你才是那个发 PR 的人。**

---

欢迎关注我

[github:xingwangzhe](https://github.com/xingwangzhe)

![Metrics](https://metrics.lecoq.io/xingwangzhe)


---

**作者：**xingwangzhe

**本文链接：**[https://xingwangzhe.fun/posts/zero-se-newcomer-guide/](https://xingwangzhe.fun/posts/zero-se-newcomer-guide/)

本文采用[知识共享署名-非商业性使用-相同方式共享 4.0 国际许可协议](https://creativecommons.org/licenses/by-nc-sa/4.0/)进行许可。