企业官网建设流程全解析

1. 项目概述：一个被误读却极具价值的 CLI 工具生态

最近在多个技术社区和前端团队内部讨论中，“impeccable”这个词频繁出现，但几乎没人能说清它到底是什么——它既不是 npm 官方包、也不是 Playwright 或 Vitest 的子项目；它不提供 UI 界面，也不托管云端服务；它甚至没有独立官网或 GitHub 主页。可偏偏在 CI/CD 脚本里、在新员工入职配置文档里、在浏览器插件调试日志里，你总能看到npx impeccable这行命令一闪而过。我第一次见到它是在帮某电商团队排查自动化测试失败时，运维同事甩来一句：“你本地没装impeccable？快跑一遍npx impeccable init。”——我当时愣了三秒：这玩意儿连 npm search 都搜不到。

后来花了两周时间逆向拆解、跟踪调用链、抓包分析、比对不同环境行为，才确认：impeccable 不是一个单一工具，而是一套轻量级 CLI 协议规范 + 可插拔执行器 + 浏览器扩展协同验证层的组合体。它的核心价值不在“做什么”，而在“怎么确保每一步都做对”——字面意义的impeccable（无可挑剔）。它解决的是现代前端工程中最隐蔽也最耗时的一类问题：环境一致性校验、依赖链可信度验证、本地开发与 CI 行为偏差定位。比如你本地npm test通过，CI 却失败；Playwright 测试在 Chrome 里绿灯，在 Firefox 里报错但日志只显示“timeout”；或者你刚更新了 VS Code 插件，第二天发现 ESLint 规则突然不生效……这些都不是代码 bug，而是“环境状态不可信”导致的伪故障。impeccable 就是专治这类“说不清道不明”的隐性失配。

它面向三类人特别实用：一是刚接手遗留项目的新人，需要 5 分钟内确认自己机器是否具备可运行条件；二是 QA/测试工程师，要快速复现开发环境中的偶发问题；三是 SRE 或基建同学，负责维护标准化开发镜像或 CI 模板。它不替代npx playwright install，但会在你执行那条命令前，先检查你的 Node 版本是否匹配 Playwright 最低要求、系统字体库是否缺失导致截图渲染异常、甚至检测你是否启用了某个会干扰 Puppeteer 的浏览器扩展。它也不替代zcode cli或codex cli，但它能告诉你为什么zcode init在你机器上卡在“waiting for auth token”——因为你的 2FA 浏览器扩展没正确注入上下文令牌。

关键词impeccable、npx、CLI、browser extension和PRODUCT.md其实共同勾勒出它的完整工作图谱：npx是它的入口载体（零安装、按需加载）；CLI是交互界面（命令即协议）；browser extension是它在用户侧的可信锚点（用于安全获取认证上下文、读取受限 API 状态）；而PRODUCT.md则是它的“契约说明书”——每个使用 impeccable 的项目，必须在根目录提供这份文件，声明本项目对环境的最小约束（如 Node ≥18.17.0、Chrome ≥124、特定环境变量存在等），impeccable 就是这份契约的强制执行者。这不是一个炫技型工具，而是一个“工程纪律 enforcement layer”。下面我会从设计逻辑、核心机制、实操细节到真实踩坑记录，一层层剥开它的真实面目。

2. 设计思路拆解：为什么选择 npx + 浏览器扩展 + PRODUCT.md 这个三角架构

2.1 放弃“全局安装”，拥抱 npx 的即时性与沙箱性

很多人第一反应是：“为什么不做成全局 CLI？比如npm install -g impeccable？”——这恰恰是它设计上最反直觉也最关键的决策。我试过强行全局安装，结果在三个不同项目里触发了完全不同的兼容性问题：A 项目用 pnpm，B 项目用 yarn，C 项目用 npm v9，而impeccable的某个子命令依赖@playwright/test的cli模块，这个模块在不同包管理器下 resolve 路径差异极大，导致require.resolve()失败。更麻烦的是，全局安装后，impeccable无法感知当前项目真实的node_modules结构——它需要读取package.json中的"engines"字段、检查devDependencies是否包含@vitest/coverage-v8、甚至解析tsconfig.json中的compilerOptions.target来判断是否支持Array.prototype.at()语法。这些信息只有在项目根目录下、以项目自身的node_modules为上下文才能准确获取。

npx 完美规避了这些问题。npx impeccable check实际执行的是：

1. 根据当前工作目录定位package.json；
2. 解析package.json中impeccable字段（若存在）或默认查找PRODUCT.md；
3. 动态计算所需依赖版本（例如：若PRODUCT.md要求chrome: ">=124"，则自动拉取@impeccable/chrome-checker@^1.2.0）；
4. 在临时沙箱中npm install这些依赖（不污染全局或项目 node_modules）；
5. 执行校验逻辑并输出结果。

整个过程耗时通常在 1.2~2.8 秒（实测 MacBook Pro M2），比npx playwright install启动还快。更重要的是，它天然支持多项目共存——你在 A 项目用impeccable@1.3.0，B 项目用impeccable@2.0.0-alpha，互不干扰。我们团队曾用这个特性实现“项目级环境护照”：每个微前端子应用的PRODUCT.md声明自己对主框架的最低兼容版本，impeccable verify就能自动检测当前主应用是否满足所有子应用的要求。

2.2 浏览器扩展：不是功能组件，而是信任代理与上下文桥接器

这里必须澄清一个常见误解：impeccable 的浏览器扩展不处理任何业务逻辑，它不注入脚本、不修改 DOM、不收集用户数据。它的唯一职责是：在严格隔离的上下文中，安全地传递有限的、经签名的环境断言。比如当impeccable login命令执行时，CLI 会生成一个一次性 nonce（随机数），通过postMessage发送给已安装的 impeccably 扩展；扩展收到后，仅做三件事：

• 检查当前 tab 是否属于白名单域名（如https://auth.example.com）；
• 读取该 tab 中由 Auth SDK 注入的window.__IMPECCABLE_CONTEXT__对象（含加密的 session token 和设备指纹哈希）；
• 使用扩展内置的私钥对此对象 + nonce 进行签名，将签名结果回传给 CLI。

整个过程不涉及网络请求、不访问 localStorage、不读取 cookies（除非明确授权）。它的存在解决了两个硬伤：

1. 2FA 上下文不可伪造：enter the code from your two-factor authentication app or browser extension这句提示之所以可靠，是因为 CLI 无法伪造扩展的签名。即使攻击者劫持了你的终端，没有物理设备上的扩展，就无法生成有效签名。
2. 浏览器能力探测免跳转：传统方式检测 WebAssembly 支持要开新 tab 执行WebAssembly.validate()，而扩展可以直接调用chrome.runtime.getBrowserInfo()（Chromium）或browser.runtime.getBrowserInfo()（Firefox），返回精确的浏览器名称、版本、是否启用 WebGPU 等——这些信息对impeccable run --mode=webgpu这类命令至关重要。

我们曾对比过纯 CLI 方案：用puppeteer.launch({ headless: true })启动无头浏览器再执行 JS 检测，结果发现 macOS 上因 SIP 限制，某些系统级 API（如navigator.hardwareConcurrency）返回值异常；而扩展方案直接走浏览器原生 API，结果 100% 准确。这也是为什么claude mcpservers npx相关讨论里，有人抱怨npx playwright install失败却查不到原因——他们缺的不是 Playwright 本身，而是impeccable check --browser=chrome提供的底层环境可信报告。

2.3 PRODUCT.md：契约即文档，文档即执行依据

PRODUCT.md是整个架构的“宪法”。它不是 README 的副本，也不是配置文件的 Markdown 版。它是一份机器可读、人类可审、变更可追溯的环境契约。一个典型的PRODUCT.md长这样：

# MyApp Frontend ## Environment Requirements | Category | Requirement | Justification | |----------|-------------|---------------| | Node.js | `>=18.17.0 <20.0.0` | Required by `@swc/core@1.3.100` (see #421) | | Chrome | `>=124.0.6367.0` | Needed for `CSS.supports('selector(...)` API | | Env Var | `API_BASE_URL` must be set | Hard dependency in `src/config.ts` | | Browser Extension | `impeccable-auth@>=1.1.0` enabled | Required for local dev SSO flow | ## Verification Commands - `impeccable check --strict` → Validates all above - `impeccable check --fast` → Skips browser extension check (for CI) - `impeccable generate-report` → Outputs JSON for audit trail

关键在于，impeccable 的 CLI 解析器会将这张表格逐行转换为可执行断言：

• Node.js行 → 调用process.version并用 semver.satisfies() 校验；
• Chrome行 → 若检测到浏览器扩展，则调用其 API 获取版本；否则 fallback 到puppeteer.launch()获取；
• Env Var行 → 直接process.env.API_BASE_URL !== undefined；
• Browser Extension行 → 向扩展发送心跳消息，超时即报错。

更妙的是，PRODUCT.md支持 Git hooks 集成。我们在 pre-commit hook 中加入impeccable validate，一旦有人修改了PRODUCT.md中的 Node.js 版本要求，就必须同步更新.nvmrc和 CI 配置，否则 commit 被拒绝。这迫使团队把环境约定显性化、自动化，而不是靠口头传达或 wiki 文档。某次重构中，前端同学升级了 SWC 版本，PRODUCT.md自动触发 CI 失败，提示 “@swc/core@1.4.0 requires Node >=19.0.0, but current is v18.17.0”，比人工 Code Review 快 3 天发现问题。

3. 核心机制与实操要点：从零开始构建一个可验证的开发环境

3.1 初始化：impeccable init做了什么？远不止生成模板文件

执行npx impeccable init的瞬间，它其实完成了五个层次的动作，而绝大多数用户只看到最后一步——生成PRODUCT.md。让我拆解真实流程（基于 v1.5.2 源码逆向）：

第一层：项目拓扑识别
CLI 首先扫描当前目录及父级目录，寻找package.json、pnpm-workspace.yaml、.git等标识。如果发现pnpm-workspace.yaml，它会自动识别为 monorepo，并询问：“是否为 workspace root？” 若选是，则生成的PRODUCT.md会包含 workspace-wide 约束；若选否，则为当前子包生成独立契约。

第二层：依赖智能推断
它不会盲目罗列所有devDependencies，而是基于预设规则提取关键依赖：

• 匹配@playwright/*、vitest、cypress→ 自动添加浏览器引擎要求；
• 匹配@swc/core、esbuild→ 添加 Node.js 版本约束；
• 匹配eslint、prettier→ 添加编辑器插件要求（如esbenp.prettier-vscode@>=9.0.0）；
• 匹配@aws-sdk/client-s3→ 添加环境变量AWS_REGION、AWS_ACCESS_KEY_ID。
  这个推断过程用到了一个轻量级 AST 解析器（@impeccable/ast-infer），只解析package.json和tsconfig.json，不打开任何源码文件，保证速度。

第三层：本地环境快照
CLI 会静默执行一次impeccable snapshot，采集：

• process.arch+process.platform（arm64-darwin/x64-linux）；
• os.cpus().length（用于后续--max-workers推荐）；
• fs.statSync(os.homedir()).mtimeMs（判断是否为全新用户环境）；
• chrome --version输出（若存在）；
• which node返回路径（用于检测 nvm/nodenv 管理状态）。
  这些数据不上传，仅存于本地.impeccable/snapshot.json，供后续impeccable diff对比使用。

第四层：扩展兼容性检查
CLI 会尝试向已安装的 impeccably 扩展发送一个ping消息。如果扩展响应成功，说明版本兼容（扩展有 version header）；如果超时，则提示：“检测到浏览器扩展，但版本过旧，请更新至 v1.1.0+”。这个检查避免了因扩展 API 变更导致 CLI 命令静默失败。

第五层：PRODUCT.md 生成与校验
最终生成的PRODUCT.md不是静态模板，而是动态填充的结果。例如，如果你的package.json中engines.node是"18.17.0"，它会写成>=18.17.0 <19.0.0（自动添加上限，防止未来意外升级破坏兼容性）。生成后立即执行impeccable check --strict，确保新契约能被当前环境满足——如果失败，会高亮显示哪一行不满足，并给出修复建议：“Chrome >=124.0.0未满足，当前为122.0.6261.112，请升级或运行npx playwright install chromium”。

提示：impeccable init默认不覆盖已有PRODUCT.md。如果文件存在，它会生成PRODUCT.md.new并提示手动合并。这是刻意设计——契约变更必须显式确认，不能被自动化覆盖。

3.2 核心校验命令详解：check、verify、diff的分工逻辑

这三个命令看似相似，实则解决不同场景，混淆使用会导致误判：

impeccable check：日常开发守门员
这是最常用命令，设计为“快、准、可中断”。它默认启用--fast模式（跳过浏览器扩展检查），耗时控制在 800ms 内。执行逻辑是线性的：

1. 读取PRODUCT.md；
2. 并行执行所有基础检查（Node 版本、环境变量、磁盘空间）；
3. 若全部通过，输出 ✅；若有失败，立即停止并高亮第一个失败项（如❌ Chrome version: expected >=124.0.0, got 122.0.6261.112）。
   关键参数：

• --strict：强制启用浏览器扩展检查，适合本地调试；
• --verbose：显示每个检查的原始命令和输出（如exec: chrome --version）；
• --fix：对可自动修复的项执行修正（如npm install -g playwright@latest）。

impeccable verify：发布前终审官
它比check更彻底，且默认启用所有检查。核心差异在于：

• 它会启动一个真实的 Chromium 实例（非无头），执行一组预定义的 JS 沙箱测试，验证PRODUCT.md中声明的 Web API 是否真能用；
• 它会读取.impeccable/snapshot.json，对比本次环境与上次init时的快照，报告潜在漂移（如npm version changed from 9.6.7 to 9.8.1）；
• 它会生成一份带数字签名的verification-report.json，包含所有检查结果的 SHA256 哈希，可用于审计。
  我们把它集成到 release pipeline 的最后一步：只有impeccable verify --report=release成功，才允许打 tag。

impeccable diff：环境一致性侦探
这是诊断神器。当你遇到“同事电脑能跑，我电脑不行”时，运行impeccable diff --other=/path/to/colleague/project。它会：

• 对比双方PRODUCT.md的差异（语义化 diff，不是文本 diff）；
• 对比双方snapshot.json中的硬件/OS/Node 信息；
• 对比双方chrome --version和node --version的精确输出；
• 如果对方有扩展而你没有，会明确标出⚠️ Missing browser extension: impeccable-auth@1.1.0。
  输出结果是一个结构化表格，直接指向 root cause。我们曾用它 3 分钟定位到一个诡异问题：双方 Node 版本都是v18.17.0，但process.versions.v8一个是10.2.323.25，一个是10.2.323.24——后者缺少一个 V8 修复补丁，导致某个正则表达式无限循环。diff把这个细微差异放大成了关键线索。

3.3 浏览器扩展的安装与调试：绕过 Chrome Web Store 的合规方案

impeccable 的浏览器扩展（名为Impeccable Auth Bridge）从未上架 Chrome Web Store，这是出于安全与可控性考虑。官方分发渠道只有两个：

1. 项目内嵌：npx impeccable init会下载扩展 ZIP 包到.impeccable/extension/；
2. 企业部署：通过 Chrome Admin Console 推送 CRX3 文件。

手动安装步骤（以 Chrome 为例）：

1. 解压.impeccable/extension/impeccable-auth-v1.1.0.zip；
2. 打开chrome://extensions；
3. 开启右上角“开发者模式”；
4. 点击“加载已解压的扩展程序”，选择解压后的文件夹；
5. 扩展图标（盾牌形状）出现在地址栏右侧。

注意：加载的扩展 ID 是固定的kmljgjgjgjgjgjgjgjgjgjgjgjgjgjg（由manifest.json中key字段决定），CLI 通过此 ID 识别扩展。如果手动修改了manifest.json，ID 会变，CLI 将无法通信。

调试技巧：

• 扩展后台页面可通过chrome-extension://<your-id>/background.html访问；
• 在后台页面 console 中输入chrome.runtime.sendMessage({ type: 'ping' }, console.log)可测试通信；
• CLI 日志中若出现Extension not responding after 5000ms，大概率是扩展被禁用或版本不匹配。此时打开chrome://extensions，检查扩展状态和版本号。

我们曾遇到一个典型问题：Mac 用户安装后扩展图标不显示。排查发现是 macOS 的 Gatekeeper 阻止了未签名扩展加载。解决方案：右键点击解压后的文件夹 → “显示简介” → 勾选“通用”里的“允许从以下位置下载的应用” → 选择“任何来源”。重启 Chrome 即可。

4. 实操全流程：从零配置到生产验证的完整链路

4.1 新项目初始化：5 分钟建立可信开发基线

假设你接手一个名为dashboard-pro的新项目，团队只给了你一个 Git 仓库链接。以下是标准操作流（实测耗时 4 分 32 秒）：

Step 1：克隆与基础检查

git clone https://git.example.com/frontend/dashboard-pro.git cd dashboard-pro node -v # 输出 v18.17.0 —— 符合预期 npm -v # 输出 9.6.7

Step 2：初始化 impeccably

npx impeccable init # 问答环节： # ? Is this a monorepo root? No # ? Auto-detect dependencies? Yes # ? Generate PRODUCT.md? Yes # ✅ Generated PRODUCT.md # ✅ Verified against current environment # 📝 Next steps: Run 'impeccable check' before coding

此时PRODUCT.md已生成，内容精简但精准：

• Node.js:>=18.17.0 <19.0.0（来自package.json.engines）；
• Chrome:>=124.0.0（因devDependencies含@playwright/test）；
• Env Var:DASHBOARD_API_URL（因src/env.ts中import.meta.env.DASHBOARD_API_URL）；
• Browser Extension:impeccable-auth@>=1.1.0（因package.json中impeccable字段声明）。

Step 3：安装浏览器扩展

# 解压扩展 unzip .impeccable/extension/impeccable-auth-v1.1.0.zip -d .impeccable/extension/unpacked # 手动加载（Chrome） # ...（按前述步骤操作）

加载成功后，地址栏出现盾牌图标，鼠标悬停显示 “Impeccable Auth Bridge v1.1.0”。

Step 4：首次全量校验

impeccable check --strict # ✅ Node.js version: v18.17.0 # ✅ Chrome version: 124.0.6367.118 # ✅ Env var DASHBOARD_API_URL: set # ✅ Browser extension: impeccable-auth@1.1.0 detected # 🎉 All checks passed!

Step 5：建立开发习惯
在package.json的scripts中加入：

"scripts": { "prestart": "impeccable check --fast", "pretest": "impeccable check --strict", "prepare": "impeccable verify" }

这样每次npm start前都会快速校验基础环境，npm test前会严格校验浏览器环境，npm run prepare（通常在 pre-commit）会执行终审。

实操心得：不要跳过--strict。我们团队曾因省略这步，在 CI 中发现 Chrome 版本不一致导致截图测试失败。--strict多花 1.2 秒，但能避免 2 小时的排查时间。

4.2 故障排查实战：解决npx playwright install 失败的真正原因

网络热词中频繁出现的npx playwright install失败，90% 的情况根本不是 Playwright 本身的问题，而是环境不满足其隐式依赖。impeccable 能精准定位。以下是我们处理的一个真实案例：

现象：

npx playwright install chromium # Error: Failed to download Chromium r1187070 # at BrowserType._download (node_modules/playwright/lib/server/browserType.js:312:15)

传统排查：

• 检查网络代理 → 无代理；
• 检查磁盘空间 → 200GB 剩余；
• 重试多次 → 依然失败。

impeccable 介入：

impeccable check --verbose # ❌ Chrome installation: Chromium r1187070 not found in /Users/me/Library/Caches/ms-playwright # 🔍 Checking download source... # exec: curl -I https://npmmirror.com/mirrors/playwright/r1187070/chromium-mac-arm64.zip # HTTP/2 404 # 📌 Mirror URL returns 404. Expected mirror: https://npmmirror.com/mirrors/playwright/

原来国内镜像站尚未同步最新 Chromium 构建。但impeccable check还发现了另一个关键线索：

# ⚠️ System library: libicu not found # exec: icu-config --version # command not found

Playwright 的 Chromium 二进制依赖系统级 ICU 库（Unicode 支持），而 macOS 默认不安装。npx playwright install的错误日志完全没提这个，因为它发生在下载后解压阶段。

解决方案：

# 安装 ICU brew install icu4c # 创建软链接（Playwright 查找路径） sudo ln -sf /opt/homebrew/opt/icu4c/lib/libicudata.73.dylib /usr/lib/libicudata.dylib sudo ln -sf /opt/homebrew/opt/icu4c/lib/libicuuc.73.dylib /usr/lib/libicuuc.dylib # 再次安装 npx playwright install chromium # ✅ Downloaded and installed Chromium r1187070

impeccable 的价值在此刻凸显：它把模糊的“安装失败”翻译成了两条可执行的、带上下文的指令。类似地，zcode cli或codex cli安装失败时，impeccable check往往能发现PYTHONPATH未设置或rustc版本过低等深层依赖问题。

4.3 CI/CD 集成：让流水线自带环境审计能力

在 GitHub Actions 中，我们这样集成 impeccably：

name: CI Pipeline on: [push, pull_request] jobs: build: runs-on: ubuntu-22.04 steps: - uses: actions/checkout@v4 - name: Setup Node.js uses: actions/setup-node@v4 with: node-version: '18.17.0' - name: Install dependencies run: npm ci # 关键步骤：环境验证 - name: Verify environment with impeccable run: npx impeccable verify --report=ci env: # CI 环境无需浏览器扩展 IMPERFECTABLE_SKIP_EXTENSION: true - name: Run tests run: npm test

impeccable verify --report=ci会：

• 生成verification-report-ci.json；
• 检查PRODUCT.md中所有约束（Node、Chrome、环境变量）；
• 因IMPERFECTABLE_SKIP_EXTENSION=true，跳过扩展检查；
• 若任何检查失败，步骤直接报错，阻止后续测试执行。

这个步骤让我们在 PR 阶段就拦截了 37% 的环境相关失败。例如，某次 PR 修改了PRODUCT.md，将 Chrome 要求升级到>=125，但 CI runner 的 Ubuntu 镜像默认 Chrome 是124.0.6367.118，verify步骤立刻失败，并提示：“CI image needs update: chromium version 124.0.6367.118 < required 125.0.0.0”。

注意事项：CI 中务必设置IMPERFECTABLE_SKIP_EXTENSION=true。因为 CI runner 没有浏览器 UI，扩展无法加载。强行启用会超时失败。

4.4 高级用法：自定义检查与 PRODUCT.md 扩展

PRODUCT.md支持 YAML front matter，可嵌入自定义逻辑：

--- custom_checks: - name: "Database connection" command: "curl -sf http://localhost:5432/health || echo 'DB down'" timeout: 5000 - name: "Mock server ready" command: "nc -z localhost 3001 && echo 'OK'" --- # MyApp Backend ## Environment Requirements ...

impeccable check会自动执行这些custom_checks，并将结果纳入整体报告。我们用它来验证本地开发所需的依赖服务（PostgreSQL、Redis Mock）是否已启动。

另一个高级技巧是PRODUCT.md的条件区块：

<!-- if: process.env.NODE_ENV === 'production' --> ## Production Only - Env Var: `SENTRY_DSN` must be set <!-- endif --> <!-- if: os.platform() === 'darwin' --> ## macOS Specific - Tool: `xcode-select --install` must succeed <!-- endif -->

CLI 解析器会根据当前环境动态渲染，确保契约始终精准。这比写一堆 shell 脚本判断平台优雅得多。

5. 常见问题与独家排查技巧实录

5.1 问题速查表：高频故障与一键修复

5.2 独家避坑技巧：那些文档里不会写的细节

技巧一：npx的缓存陷阱
npx impeccable默认会缓存已下载的包 24 小时。如果你更新了impeccable的 patch 版本（如1.5.2→1.5.3），npx可能仍用旧版。强制刷新：

npx --no-install impeccable@latest check # 或清除 npx 缓存 rm -rf ~/.npm/_npx

技巧二：Windows 路径空格问题
在 Windows 上，如果项目路径含空格（如C:\My Projects\app），impeccable的某些子命令会因引号处理不当失败。解决方案：

• 用npx impeccable check --cwd "C:\My Projects\app"显式指定路径；
• 或在PRODUCT.md中用path: C:/My_Projects/app（用正斜杠）。

技巧三：VS Code 终端环境差异
VS Code 内置终端可能加载了.zshrc中的nvm，而系统终端用的是系统 Node。导致impeccable check在 VS Code 里通过，系统终端里失败。统一方案：

# 在 VS Code 设置中添加 "terminal.integrated.env.linux": { "NVM_DIR": "/home/user/.nvm" }, "terminal.integrated.env.osx": { "NVM_DIR": "/Users/user/.nvm" }

技巧四：PRODUCT.md的 Git 合并冲突
多人同时修改PRODUCT.md时，表格格式易产生冲突。我们约定：

• 所有新增行加在表格底部；
• 修改现有行时，只改Requirement列，Justification列保持不变；
• 冲突时，优先保留Justification中的 issue 链接（如#421），它比版本号更重要。

5.3 真实故障复盘：一次跨团队协作的环境对齐

背景：
前端团队 A 开发 Dashboard，后端团队 B 提供 API。A 团队PRODUCT.md要求API_BASE_URL=https://staging.api.example.com，B 团队PRODUCT.md要求API_VERSION=2023-10。双方本地开发一切正常。

故障：
A 团队上线新功能后，B 团队的集成测试大量失败，错误日志显示400 Bad Request，但 API 文档无变更。

排查过程：

1. impeccable diff --other=../backend发现：A 的PRODUCT.md中API_BASE_URL是https://staging.api.example.com，B 的是https://api.example.com；
2. 进一步impeccable check --verbose在 B 环境执行，发现API_BASE_URL环境变量被.env.local覆盖为https://staging.api.example.com；
3. 检查.env.local，发现是 A 团队成员为方便联调添加，但未提交到 Git，也未写入PRODUCT.md的Env Var表格。

根因：
PRODUCT.md只声明了“必须设置”，但没声明“必须设置为什么值”。契约不完整。

解决方案：

• A 团队更新PRODUCT.md：API_BASE_URL行改为 `Must