别让第一个 PR 死在 README 里：AI 生成仓库的新人贡献者上手手册

一个 AI 生成的仓库最怕的不是没人 star，而是第一个想帮忙的人打开仓库、看了半小时、默默关掉页面。代码是现成的，文档也写得像模像样，可新人就是不知道从哪里下手：改哪一行不会牵一发动全身？跑起来要哪些密钥？这个 agent 规则文件到底管什么？提了 PR 会不会被一句“不符合架构”打回来？

本文讲的不是“新用户上手引导”——那是给产品使用者的，站内已有专门指南；也不是“开源发布”，那是把仓库推出去的动作。本文只解决一个问题：当一个外人想给你的 AI 搭建的仓库贡献代码时，怎样让他在七天内交出第一个被合并的 PR，并且还想交第二个。本文面向的维护者是独立开发者和小团队，仓库的特点是：大部分代码由 AI 生成、原始作者的记忆不在代码里、agent 规则文件和提示词历史散落在各处。

先划界：新人卡住的地方，和你想的不一样

传统开源项目的新人障碍是“代码太多、看不懂”。AI 生成仓库的新人障碍恰恰相反：代码看起来都懂，每一行都工整、注释都齐全，可新人仍然不敢动。原因有四条，每一条都和“代码由 AI 生成”直接相关。

第一，作者记忆缺失。人类手写的项目里，作者脑子里有“这里本来想这么写但妥协了”的上下文；AI 生成的项目里，这段上下文只存在于某次已经关闭的对话里，仓库里找不到。新人看到一段别扭的代码，分不清它是深思熟虑的妥协，还是模型随手写的凑合。

第二，规则不在一处。agent 的工作方式可能同时写在 AGENTS.md、Cursor Rules、README 的某一段和 CI 配置里，新人不知道听谁的。更糟的是，其中几份可能已经过期：规则说“用 Prisma”，代码里却还有一半手写 SQL。

第三，运行门槛被低估。AI 生成的 README 常常写“npm install 即可运行”，却不提需要三个第三方密钥、一个本地数据库和一个特定版本的 Node。新人第一步就卡住，而且不好意思问——因为文档说“很简单”。

第四，评审标准不透明。新人不知道这个仓库的 PR 到底看什么：是功能对不对？是风格像不像？还是“不要动 agent 生成的那部分”？标准不写出来，新人只能靠猜，而猜错一次就可能再也不来了。

所以贡献者上手手册的目标不是“把文档写厚”，而是把上面四条逐一消除：把记忆写进仓库、把规则收敛到一处、把运行步骤做成可复制的命令、把评审标准变成清单。

四张地图：新人进仓库先看什么

不要让新人从根目录的文件列表开始漫游。给他四张地图，每张地图一页纸能讲完，放在仓库最显眼的位置，并且互相链接。

第一张是产品地图：这个产品给谁用、解决什么问题、哪三个功能是核心、哪几个页面是主流程。用一句话写定位，再用一张流程图或一串链接指向主流程的入口文件。不要写愿景口号，写“用户打开首页→点这个按钮→发生这件事”。

第二张是代码地图：目录是干什么的、数据从哪里流到哪里、哪几个模块最关键、哪几个目录是生成的不要手改。重点标出“禁区”：比如 migrations 目录、生成的 API 客户端、第三方 SDK 的封装层。禁区不是不让看，而是不让新人第一次就改。

第三张是 agent 地图：这个仓库用哪个 agent 工作流、规则文件是哪一个、提示词模板放在哪里、AI 生成代码的标识是什么。明确写出三条：新人自己用 AI 辅助时要遵守什么；AI 生成的代码提交前要经过哪几步人工检查；哪些决定必须由人做、不能交给模型。

第四张是决策地图：过去做过哪些关键决定、为什么这样选、被否决的方案是什么。形式可以很轻：docs/decisions 里每条决定一个小文件，写清背景、选项、决定、后果。没有决策记录的新人，每次改动都是在和看不见的历史争论。

四张地图的检验标准很简单：找一个没看过仓库的朋友，给他地图和仓库，30 分钟后问他“如果让你修登录页的一个文案错别字，你改哪个文件、怎么验证、提 PR 时写什么”。答得出来，地图就合格；答不出来，缺的那张地图就是你要补的。

七天上手计划：把“欢迎贡献”变成日程

“欢迎任何贡献”是最无效的欢迎。新人需要一条有终点的路。下面是一份给兼职贡献者的七天计划，维护者可以直接抄进 CONTRIBUTING.md，时间按每天一小时估算，赶时间的可以压缩到一个周末。

第零天，跑起来。目标只有一个：在本地把项目跑起来并看到主流程。新人按 README 的命令操作，遇到任何一步和文档不符，立刻记下来——这就是他第一份有价值的反馈。维护者要保证：环境变量有 .env.example 且每个变量都写清去哪里申请、是不是必填；数据库能用一条命令初始化；种子数据能一键生成。

第一天，读地图。按上面四张地图的顺序读，读完在 issue 里留一句话：哪张地图最不清楚。这句话本身就是贡献，不需要写代码。维护者要回得快：24 小时内回复，哪怕只回“收到，这张图我周末补”。新人最怕的不是任务难，而是石沉大海。

第二到三天，做一件不需要理解全局的小事。从下面的任务梯子里选一级任务（见下节），比如修一个文案、补一个空状态、给一个函数加测试。关键是任务要小到“改动文件不超过三个”，并且验收标准写在任务里。

第四天，提第一个 PR。PR 模板（见下节）填好，CI 跑过，截图或录屏贴上。这个 PR 不求大，求完整：描述、改动、验证、风险四项齐全。维护者评审时先肯定“跑通了流程”，再谈代码细节。

第五到七天，复盘与认领。维护者和新人一起复盘：哪一步卡最久、哪份文档误导了人。复盘结论直接写进文档——新人走过的坑，就是下一位新人的路标。复盘完再认领一个二级任务，进入正常贡献节奏。

七天计划里最重要的一条是：维护者要把“回复速度”当作基础设施。新人提 issue 三天没人理，等于告诉所有围观者“这个仓库不欢迎外人”。如果实在忙不过来，宁可把仓库的 CONTRIBUTING 里写明“每周三、周日集中回复”，也不要让新人猜。

任务梯子：一级、二级、三级任务怎么写

好的 first issue 不是“简单”，而是“边界清晰”。按下面三个级别维护任务池，新人按级别往上爬，维护者按级别控制风险。

一级任务：只改一处、只影响一处。例子：修文案错别字、给空状态加一句提示、把一处硬编码文案抽成常量、给已有函数补一个单测。每个一级任务必须写清：改哪个文件、改成什么样算完成、怎么验证（命令或截图）。不要写“优化一下首页”这种没有完成标准的话。

二级任务：改一处逻辑、影响有限。例子：给列表加一个排序选项、给表单加一项校验、修一个有复现步骤的轻微 bug。二级任务要附上：复现步骤、相关文件、预期行为、不建议碰的相邻模块。还要标明“需不需要先讨论方案”——需要讨论的，先在 issue 里定方案再动手，省得白写。

三级任务：跨模块或涉及架构。例子：换一个缓存策略、重构一个模块、接入一个新的第三方服务。三级任务不对新人开放认领，但可以开放“先写方案”：新人先交一份方案文档，维护者认可后再动手。这是把三级任务变成二级任务的办法，也是考察新人是否理解架构的办法。

任务池的维护也有纪律：每个任务贴上级别标签；已认领的任务标出认领人和日期，超过两周没动静的自动释放；已完成的一级任务不要留在池子里凑数，定期归档。任务池里长期挂着十几个“没人做也没人管”的任务，比没有任务池更打击人。

PR 模板与评审清单：让标准看得见

新人最怕的评审意见是“感觉不太对”。把评审标准写成模板和清单，感觉就变成事实核查。下面是一份可以直接用的 PR 模板，维护者把它存为 .github/pull_request_template.md：

## 改了什么（一句话）
## 为什么改（关联 issue 编号）
## 怎么验证（命令 / 截图 / 录屏）
## 影响范围（改了哪些模块，有没有动禁区）
## 是否用了 AI 辅助（用了哪个工具、人工检查了哪几处）

最后一项不是审问，而是 AI 生成仓库的诚实机制：用了 AI 很正常，写出来反而让评审者知道该重点看哪里——比如模型重构过的边界条件、它“自信地”写出的第三方 API 用法。评审清单则给维护者用，收到 PR 后逐项打勾：

• 改动是否只做一件事？顺带重构超过三个文件的，打回拆分。
• 有没有动禁区目录？动了有没有说明理由？
• 测试有没有覆盖新逻辑的边界条件，而不只是 happy path？
• AI 生成的部分有没有人工核对过第三方 API、权限、金额、时间等高风险点？
• 文档和代码是否一起改？只改代码不改文档的，下次新人还会踩同一个坑。
• 破坏性变更有没有写迁移说明？数据库字段、接口返回、环境变量，变一项就要写一项。

评审的语气也有讲究：先说“这个 PR 解决了什么问题，谢谢”，再说“这里建议改成这样，原因是……”，最后说“改完我就可以合并”。新人第一次被评审，最怕的是不知道“改完能不能过”。把结论写在最后，让新人带着确定性去改第二版。

给 AI 生成代码立三条规矩

贡献者用 AI 写代码不是问题，没有规矩才是问题。下面三条规矩建议写进 AGENTS.md 或 CONTRIBUTING.md，并且对维护者自己同样适用——只约束新人的规矩没人信服。

第一条，AI 不能是唯一作者。任何 AI 生成的改动，提交者必须能讲清三件事：这段代码做什么、边界条件是什么、如果出问题怎么验证。讲不清的，先缩小改动范围，直到能讲清为止。这条规矩把“贴了一大段模型输出”挡在门外，却不挡“用模型加速、但自己负责”的做法。

第二条，高风险点必须人工核对。列一张高风险清单贴在仓库里：权限判断、支付金额、密码与密钥处理、删除与批量操作、第三方 API 的参数与返回值、时间与时区计算。凡是碰到清单里的内容，PR 描述里要单独写一句“我人工核对了某某处，依据是官方文档或测试结果”。评审者看到这句话，就知道该重点复核哪里。

第三条，生成代码也要留痕。要求 PR 里说明 AI 参与的程度：是“模型起草、我重写了关键部分”，还是“模型只补了测试”，还是“全程手写”。这不是为了评判，而是为了日后排查：某段代码出问题时，维护者能判断它是模型幻觉的残留，还是人的设计失误，两种问题的修法不一样。

三条规矩之外，还有一条底线要提前说清：不要把密钥、真实用户数据、生产数据库连接串贴进任何 AI 对话或 issue。AI 生成仓库的新人常常为了“让模型复现问题”随手贴上真实配置，维护者要在 CONTRIBUTING 首页用一句话堵住这个口子。

反模式：五种把新人赶走的做法

第一种，README 写“很简单”，实际跑起来要半天。文档里的每一步都要有人按字面操作验证过，验证者最好就是上一位新人。文档不是写出来的，是被新人踩出来的。

第二种，issue 标题是“求助”“优化一下”，没有复现步骤、没有完成标准。新人认领这种任务，等于认领了一次返工。维护者宁可少发任务，也不要发模糊任务。

第三种，评审只说“不行”，不说“怎么才行”。每一轮评审意见都要带可执行的下一步，否则新人只能猜，猜错了又被打回，两轮之后就走了。

第四种，合并全靠维护者心情，标准时松时紧。今天因为赶进度合并了没测试的 PR，明天因为心情不好打回了有测试的 PR——新人会立刻学会“这个仓库的规则是看人”，然后离开。

第五种，把新人当免费劳动力。只派脏活累活、从不解释背景、从不公开致谢。贡献者留存的真正燃料是两样：被认真评审，和被公开感谢。合并后在更新日志或 README 的贡献者名单里写上名字，成本为零，效果最大。

走一遍：一个虚构例子的完整上手路径

假设仓库是一个 AI 生成的记账小工具：用户记一笔支出，列表按月份汇总，数据存在本地数据库。维护者在任务池里放了一个一级任务：“设置页的货币符号目前写死为人民币，改成跟随用户在设置里选的货币显示”。任务里写清：改动文件是设置页组件和金额格式化函数；完成标准是切换货币后列表和详情页的金额都跟着变；验证方法是改完跑一遍现有测试并贴一张切换前后的截图。

新人按七天计划走：第零天跑起项目，发现 README 漏写了数据库初始化命令，他把这一步记下来，顺手提了一个文档 PR——这是他第一个被合并的改动，虽然只有两行。第一天读地图，发现代码地图里没有标出“金额格式化函数是禁区还是可改区”，他在 issue 里问了一句，维护者当天回复并补上了标注。第二到三天做货币任务，改动两个文件，加了一个测试，PR 模板五项填齐，评审只提了一个意见：格式化函数还要处理“货币符号缺失时回退到默认符号”的边界。改完第二版当天合并，维护者把他的名字写进贡献者名单。

注意这个例子里的关键点：新人的第一个 PR 不是货币任务，而是文档修正。任务梯子的意义就在于此——先用一件两小时能完成的小事建立“这个仓库会认真对待我”的信任，再去做需要理解业务的任务。反过来，如果维护者一上来就把“重构金额模块”交给新人，哪怕新人能力够，也会在“不知道评审标准”的焦虑里拖延。顺序对了，能力自然跟得上；顺序错了，再好的任务池也没用。

维护者自查表：上线这套手册之前

最后给维护者一张上线检查表，全部打勾再宣布“欢迎贡献”：

• 四张地图齐全，且每张都有指向具体文件的链接，不是空话。
• 本地运行步骤被一个没看过仓库的人按字面跑通过。
• 任务池里至少有五个一级任务，每个都有完成标准和验证方法。
• PR 模板已存入仓库，评审清单维护者自己先用过一遍。
• AGENTS.md 里三条 AI 规矩齐全，且维护者自己的 PR 也遵守。
• 回复节奏已写明：几天内回复 issue 和 PR，忙时也一样。
• 贡献者名单有地方写，第一个合并的 PR 就有人名可填。

做完这些，仓库才算真正“打开了门”。AI 可以一夜之间生成一万行代码，却生成不了一个愿意留下来的人。愿意留下来的人，是靠一张地图、一个小任务、一次被认真对待的评审留住的。把这三样准备好，第一个 PR 就不会死在 README 里。