别让AI替你捣乱-致零软件工程经验新人的指南 | 姓王者的博客

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

引言

GitHub 最近这几个月频繁崩溃，由于我订阅了 GitHub status 的邮件通知，导致某一天半夜连续受到几十封邮件轰炸！

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

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

软件工程的概念

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

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

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

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

万事开头难，先了解项目

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

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

架构分析

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

TUI 模式 — 用 ASCII 作画：

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

ChatBox 模式 — 用 Mermaid 渲染：

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

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

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

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

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

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

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

分析完架构之后，请你再分析： 1. 当前项目的包管理器（npm / pnpm / yarn / cargo 等） 2. 核心第三方包及其作用 3. 主体框架是什么 4. 这些第三方的文档链接

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

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

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

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

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

准备贡献，先看 Issue

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

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

安装 gh CLI，让 AI agent 帮你快速筛选：

# 带有 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

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

准备贡献，最关键的是 PR

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

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

1. 关联 Issue

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

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

2. 填写 PR 模板

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

3. 自己先 Review 一遍

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

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

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

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

4. 保持 PR 小而聚焦

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

题外话

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

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

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

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

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

不要胡乱 PR

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

说人话

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

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

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

你应当：

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

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

欢迎关注我

github:xingwangzhe

别让AI替你捣乱-致零软件工程经验新人的指南

作者：xingwangzhe

本文链接： https://xingwangzhe.fun/posts/zero-se-newcomer-guide/

本文采用 知识共享署名-非商业性使用-相同方式共享 4.0 国际许可协议 进行许可。