原则塑造本技能每个行动的四个不可协商的规则。如果未来的更改与其中一条冲突那么这个更改就是错的。规则 1先可观测后调查技能绝不在没有可观测性信号指向的情况下读取源文件。第 1 步node scripts/collect-signals.mjs永远是第一步。在signals.json存在之前不读取任何源代码。为什么跳过它会导致失败没有指标技能会退化为grep 仓库找已知反模式并抱怨。那会产生与流量、成本或用户痛点无关的嘈杂、低影响的建议。指标优先的调查让技能聚焦于观测到的流量、成本和可靠性信号。四项检查的首次通过Enterprise当plan enterprise时门控运行必须在代码级建议之前呈现这四项检查。现场工程师确认这些是每次续约审计中最高杠杆的账户级杠杆是否启用了 Observability Plus来自signals.observabilityPlus。如果为 false整个审计都会降级作为报告顶部条目呈现。前面是否有反向代理来自响应头/CNAME 链的启发式当收集到时。Vercel ISR 前面的非 Vercel CDN 通常是哑管道——浪费的支出。是否启用了 WAF 规则来自signals.project.security。在有机器人证据的项目上缺少 BotID 托管规则是最常见的成本激增原因。ISR 读:写比率。来自metrics.isrReadsByRoutemetrics.isrWritesByRoute。在标记写入 读取之前计入 CDN 层读取参见>规则 2每次子代理调查之前必须有确定性门控node scripts/gate-investigations.mjs是一个纯 JS、无 LLM 的函数。它读取signals.json并输出{toLaunch, platform, gated}。相同的输入总是产生字节级相同的输出appliedAt除外。每种候选未缓存路由、慢路由、错误、冷启动、扫描器发现、平台级建议都有其阈值表达式编码为lib/gates/kind.mjs中的gate(signals) → Candidate[]函数。未通过的门控会出现在最终报告中位于本次运行未调查下并带有它们被扣下的确切原因。这是面向用户的信任机制您可以看到我们考虑过并选择跳过的内容以及原因。为什么这很重要代理绝不由 LLM 判断决定我应该查看这条路吗。阈值是机械的。这消除了代理调查不该调查的路由冷路径并为不需要修复的路由推荐修复方案的整个失败模式。规则 3候选约束的调查范围当门控发出带有files: [src/app/api/products/route.ts]的候选时代理只读取该文件以及链条展开时的导入。它不会在仓库中grep -r。如果您发现自己想要 grep 整个代码库停下来重新阅读当前候选的question字段。如果问题没有约束搜索那么候选就是畸形的——将其记录为gated并跳过。不要用更广泛的搜索来补偿。为什么这很重要代理的工作是验证和解释门控发现的指标异常而不是做一般代码审查。漫游的调查会产生漂移、幻觉和与成本及性能数据无关的建议。扫描器发现补充信号静态 AST-grep 扫描器与指标驱动的调查并行运行。它们的输出标注了逐文件可观测性信号如果文件映射到热路由则为function invocations: 1.2M; 95th percentile duration: 850ms; cache hit rate: 0%如果映射到没有流量的路由则为COLD-PATH如果文件不映射到任何路由则为NO-ROUTE-MAPPING。默认规则COLD-PATH或NO-ROUTE-MAPPING文件上的扫描器发现会被丢弃。只有模式是独立于流量的它们才会成为建议构建配置、中间件匹配器、生产环境中的 source maps、原始 script 标签、React Compiler 配置。这些不在乎流量——它们同样影响每个请求或影响构建本身。独立于流量的白名单位于每个扫描器的metadata.trafficIndependent: boolean字段中。只有当您能捍卫该声明时才将其设置为true。规则 4文档支撑、版本感知的建议——不虚构每条建议必须携带至少一条来自references/docs-library.json的引用。任何其它内容都会在清理器阶段被丢弃。库有两个部分URL— Vercel 文档、Next.js 文档、SvelteKit 文档等。每个声明applicableFrameworks例如[next15.0.0]。跨技能规则引用— 仅按名称vercel-react-best-practices:async-parallel。由代理的宿主解析。三个清理器强制执行这一点missing-citation— 丢弃citations[]为空的建议。unknown-citation— 剔除不在库中的 URL标记needsReviewtrue。version-mismatch— 剔除applicableFrameworks与项目 frameworkversion从package.json解析不匹配的 URL。两个验证器声明类型检查它citation_in_libraryURL ∈ 白名单和citation_applies_to_versionsemver 匹配。为什么这很重要LLM 引用看起来合理但 404 的 URL或向 Next.js 13 用户推荐 Next 15 功能。两者都是信任杀手。白名单关闭第一个失败模式applicableFrameworks字段关闭第二个。性能引用引用观测数据每个性能声明都引用signals.json中的实际可观测性数据——例如functionRoutes[/api/products].p95Ms850。估算的改进被框定为锚定在观测基线之上的范围将 /api/products 的 95 百分位持续时间从 850ms 降低到约 250-400ms基于类似的缓存路由。绝不是一个无锚定的声明。成本框架是量级绝非精确禁止像$340/mo这样的成本声明。预测的美元噪声下限太高无法证明精确性合理。impactMagnitude({currentCost, impactTier})辅助函数映射到类似按当前流量每月数百美元针对用户实际的vercel usage数据计算的措辞。$-strip清理器在输出时强制执行这一点——面向客户字段中的任何$N字面量都会被剔除。性能数字保持精确因为它们是观测的不是外推的。我们信任观测指标我们不信任美元预测。好的运行是什么样一次好的运行产生少量5-15 条建议。每条建议关联到特定路由或文件加上特定指标信号。每条建议带有前/后代码和 ≥1 条匹配用户框架版本的引用。成本框架使用量级措辞。性能框架使用精确的观测数字。本次运行未调查部分解释我们看到的所有其它信号以及为什么我们选择不深挖缓存命中率低于阈值、95 百分位持续时间已经健康等。没有$N/mo字符串、没有编造的 URL、没有向 Next.js 13 用户推荐 Next.js 15 功能。坏的样子我们不会发布的反模式通过 grep 仓库找已知反模式而不检查流量得出的建议。没有冷启动信号就启用 Fluid Compute。当路由有 cookies() 且受认证门控时给 /api/users 添加缓存。因为 Workflow 步骤是长时间运行的就减少/.well-known/workflow/v1/step的持续时间。Workflow 运行时端点是生成式编排路由除非单独的可靠性/错误信号指向别处否则那里的高墙钟持续时间是预期的。没有证明流在做可避免的首字节前工作、高活跃 CPU、重复调用或可移动的响应后工作就修复/api/chat/[id]/stream因为它的持续时间高。“通过做 X 每月节省 $340”——编造的精确性。引用不存在的 URL或描述用户版本没有的 Next.js 功能的 URL。用户无法执行的长建议列表每条建议都需要证据链。超出范围技能限于 Vercel 托管项目上的运行时成本和性能优化。以下是非目标如果信号或扫描器发现在这些领域出现请将其分流出去孤立的部署产物大小。包大小只有在表现为运行时成本冷启动、FDT或性能LCP、INP时才重要。如果唯一的影响是.next 目录很大那不在范围内。没有运行时影响的构建期问题。慢构建、构建缓存未命中、monorepo 构建分发——这些只在表现为构建分钟计费压力时进入范围然后通过build-minutes-fanout门控。一个 6 分钟构建成功完成并发布小产物不是目标。安全公告和凭据轮换。next-mdx-remote中的 RCE、泄露的环境变量、OIDC 与显式密钥认证卫生——请参考安全技能而不是这个。例外当安全设置同时也是记录在案的成本杠杆时BotID 机器人流量 边缘成本它通过platform_bot_protection门控进入。商业/计费流程琐事。折扣滑块、席位核对、合同续约机制。技能可以量化哪个 SKU 昂贵它不谈判。