Vibe Coding 官方文档锚定：让 AI 按仓库实际版本写代码

让 AI “按框架最佳实践实现”有一个隐蔽前提：它和仓库说的是同一版本。真实项目可能固定旧主版本、提前采用候选版、维护私有补丁，或在一个 monorepo 中同时支持多代 API。模型记忆、搜索引擎首条结果和官网默认页面都可能指向另一套约定。代码看起来标准，编译时却不存在该导出；更糟时它能编译，却绕过当前版本要求的缓存、权限或生命周期规则。

版本锚定不是在提示词里写一句“使用最新版”。它是一条可核查链路：仓库声明什么，解析器实际安装什么，官方资料对应什么版本，目标 API 在本地制品中是否存在，现有测试如何定义行为。依赖升级与锁文件兼容门处理升级本身；本文聚焦不升级的前提下，怎样阻止 AI 跨版本写代码。

先确认解析结果，不从记忆猜版本

包清单中的范围只是请求，锁文件才记录某次解析结果；workspace override、peer 条件和传递依赖还可能让不同包得到不同实例。先读取仓库的 package manager 声明和锁文件，再使用项目已有命令查看实际依赖树。不要临时更新 lockfile，也不要运行会安装 latest 的命令来“确认文档”。

版本证据至少包含：运行时版本、包管理器版本、目标包直接声明、锁定版本、workspace 或 patch 规则、读取证据的工作树 revision。若 node_modules 与锁文件不一致，应先标为环境漂移，不能任选一个作为真相。

dependency: framework-x
requestedBy: apps/web/package.json
resolvedBy: pnpm-lock.yaml
resolvedVersion: 4.7.2
runtimeConstraint: node >=20
localPackagePresent: true
worktreeRevision: 71aa9e4+dirty

Semantic Versioning 说明版本号如何表达兼容意图，但版本范围不是行为证明。即使只变化补丁号，也应以实际导出、类型和发布说明为准；反过来，主版本变化也不代表每个 API 都已改变。

文档来源按距离仓库事实排序

第一优先级是仓库自身规则和目标依赖随安装包附带的文档、类型声明、schema 与测试。它们最接近正在执行的代码。第二优先级是官方站点中明确标出版本的页面、该版本 tag 的 README、API 参考和迁移指南。第三优先级才是未标版本的官方概念页。博客、问答和模型记忆只能帮助发现关键词，不能独立决定实现。

若仓库要求先阅读 node_modules/<package>/.../docs，那不是形式要求：它往往说明这个安装版本拥有和公开站点不同的文件约定。先建立“文档路径 -> 包版本 -> 相关 API -> 适用任务”的记录，再让 AI 规划。对于没有版本切换器的官网页面，保存页面标题、访问日期和对应 release/tag；不要把今天看到的内容声称为旧版本事实。

开发者文档代码样例漂移门禁关注文档发布者如何持续验证示例；作为使用者，则要反向证明所选示例能在本仓库的运行时和锁文件组合中成立。

把 API 建议落回本地制品

官方页面仍可能描述可选模块、实验功能或不同部署形态。AI 提议一个 API 后，至少做三步核对：在本地类型或导出表中定位符号；检查现有仓库是否已经使用同一模式；用最小编译或测试验证调用签名。动态语言还要检查运行时条件，不能只靠文本搜索。

若找不到符号，不要立刻加依赖或升级版本。先判断是文档版本不匹配、导入路径错误、功能需要显式启用，还是项目刻意使用兼容层。生成代码所有权与再生成边界同样提醒：类型和客户端若由生成器拥有，应修改源契约或生成配置，而不是手改产物来迎合示例。

同时记录废弃项与破坏性差异

版本资料不只用来证明“可以这样写”，还要查明“不再应该这样写”。阅读当前版本的弃用提示、迁移说明和 release note，搜索仓库是否仍有旧调用方。对 AI 计划标注 supported、deprecated、experimental 或 unknown；实验 API 若未经任务授权，不应因为代码更短就采用。

当需求确实要求新版本能力时，把升级拆成独立决策：解析差分、运行时支持、生成产物、消费者和回滚都需要验证。不要在功能补丁中顺手升级，再用新文档为扩大范围辩护。

给上下文包加入版本收据

在任务上下文包中加入一份短收据即可，无需粘贴整套文档：

Fact: route handler receives Request directly
Applies to: [email protected], apps/web
Evidence: node_modules/framework-x/types/router.d.ts:118
Official reference: v4 API reference, accessed 2026-07-30
Negative check: legacy ctx signature absent from installed types

收据必须指向事实，不要写“官方推荐所以更好”这类无法复核的判断。补丁完成后，构建和针对性测试仍是最终证据；文档能约束实现选择，不能替代运行验证。Prompt 版本控制与 CI所强调的版本化思路同样适用：输入依据发生变化时，旧结论要重新评估。

版本锚定的完成标准很朴素：reviewer 能从仓库声明走到解析版本，从解析版本走到对应官方资料，再回到本地符号和测试。任何一跳只能靠“AI 记得”连接，就还不应该让它写入关键路径。

延伸阅读

• 依赖升级与锁文件兼容门
• 开发者文档代码样例漂移门禁
• 生成代码所有权与再生成边界
• Prompt 版本控制与 CI