Vibe Coding 陌生仓库冷启动：第一次编辑前的只读勘察协议

陌生仓库中的第一条 AI 指令常是“先看看项目，然后实现这个功能”。“看看”没有完成条件，Agent 可能列目录、读 README，随后根据训练中熟悉的框架约定直接编辑。真实仓库却可能把生成文件当只读区，只允许远程运行某类验证，或已经存在用户未提交的修改。冷启动的首要产出不是架构总结，而是一个结论：在当前现场，下一步能否安全开始编辑。

用 AI 快速熟悉陌生代码库介绍从架构概览到功能理解的完整 onboarding，编程 Agent 的仓库地图讨论可维护的长期地图。本文把范围收得更窄：第一次进入仓库时执行一轮只读协议，任何写操作都要等到规则、所有权、入口和验证方式有证据。

第一步只确认位置与所有权

先确认当前目录是否真的位于目标仓库、仓库顶层在哪里、是否存在嵌套仓库或 submodule。读取从根目录到目标路径沿途的 AGENTS.md、贡献指南和工具说明，记录适用范围。不要假设根规则覆盖所有子目录，也不要因为 README 年代较新就让它覆盖更具体的目录规则。

然后采集 HEAD、分支和短格式状态。Git status 能区分索引与工作树变化；git ls-files 默认列出 index 中的已跟踪路径，未跟踪项需用 --others --exclude-standard，ignored 项还需显式组合 --ignored 与排除规则。这里只读，不自动执行 checkout、reset、stash、clean、安装或格式化。发现修改后先标注路径和可能归属，无法判断就保留未知，而不是“顺手清干净”。AI 编程本地与云执行边界还提醒：仓库分类和执行位置也属于开工条件，不能把私有代码默认发送给任意外部工具。

第二步建立仓库形态证据

用受版本控制的文件清单了解真实形态，而不是遍历依赖缓存和构建产物。先看顶层目录、清单与锁文件、workspace 配置、构建配置、容器或部署描述、数据库 schema，再判断它是单应用、monorepo、生成代码仓库还是多语言组合。目录名只是线索；脚本、import 和构建图才是证据。

例如 package.json 的 scripts 能说明维护者给出的命令入口，但不能证明每条命令在本机都允许执行。继续检查 package manager 版本、锁文件、环境前置条件和 CI 调用方式。若脚本内部会访问网络、启动容器、写数据库或修改文件，先把副作用写入清单，不要为了“试一下”直接运行。

repository shape
- source roots: src/, packages/*/src
- generated: src/generated/ (owner: prisma generate)
- local checks: lint, unit tests
- restricted checks: Docker only on configured remote runner
- unknown: integration test database lifecycle

第三步从任务词找到候选入口

现在才搜索业务关键词。先找用户可见字符串、路由、命令名、事件名或公共类型，再追到实现和测试。搜索不到不代表功能不存在：字符串可能来自翻译文件，路由可能由配置生成，命令可能通过注册表加载。记录查询、命中和未覆盖形态，避免 AI 把第一次 grep 的结果当作完整影响面。

候选入口应至少有两个独立佐证，例如路由配置指向 handler，同时测试或调用方引用它。若只由目录名推断，标记为 hypothesis。冷启动阶段不必画全仓依赖图，只需找到足以继续调查的起点、相邻边界和高风险未知项。

第四步找出真正的验证入口

阅读 CI 工作流、项目脚本和测试配置，确定格式、类型、单元、集成、构建与端到端检查分别如何调用。优先运行明确只读或只写临时产物的廉价检查，并先记录基线结果。若基线已有失败，保存命令、错误和与任务的关系；不要修改测试来制造绿色。

验证环境无法满足时，写“未运行：缺少 X”比猜测更有价值。编程 Agent 的 Sandbox 与权限设计提供权限分层思路：探索权限和执行权限应分开，读懂命令不等于获得运行副作用的授权。

形成冷启动收据

只读勘察结束后输出一页收据，而不是生成大段仓库介绍：

• 当前基线和工作树是否干净，已有修改是否有明确所有者。
• 哪些规则适用于目标路径，哪些操作明确禁止。
• 任务候选入口、关键调用方、测试和生成边界。
• 可运行验证与受限验证，以及基线失败。
• 仍未知但可能改变方案的事实。
• 建议的第一处编辑和为何它是最小范围。

只要以下任一项存在，就不应开始写：目标路径规则未读；工作树改动归属未知且与任务重叠；候选文件由生成器拥有；唯一验证命令会产生未授权副作用；需求入口没有源码证据。停止并不是 Agent 失败，而是冷启动协议成功挡住了无依据修改。

第一次编辑获准后，冷启动收据成为编程 Agent 的改动验证门的输入。后续探索可以扩大地图，但任何新发现的限制都应更新收据。这样 Vibe Coding 的速度来自减少无效试错，而不是跳过理解仓库的成本。

延伸阅读

• 用 AI 快速熟悉陌生代码库
• 编程 Agent 的仓库地图
• 编程 Agent 的 Sandbox 与权限设计
• AI 编程本地与云执行边界