规范驱动开发（Spec-Driven）与 AI 生成式前端

• 单一事实源（single source of truth）对前后端一致性的作用
• 类型与 mock 的自动派生（openapi-typescript、orval、MSW）
• 契约变更的同步与门禁

spec-driven 的核心是"契约先行"：用 OpenAPI/spec.json 定义接口的请求/响应结构，前后端都从同一 schema 派生资产。工程价值：一致性——前端类型（openapi-typescript 生成 TS 类型）、客户端（orval 生成类型安全 API 层）、mock（MSW 按 spec 生成响应）全部由 spec 派生，消除"前端类型与后端实现漂移"这一经典问题；并行开发——后端未就绪时前端用 spec 驱动的 mock 先行开发；可验证——CI 中后端实现可用 schema 校验（响应符合 spec），前端用类型检查保证调用合法；变更治理——spec 变更产生 diff，前端编译失败即暴露破坏性变更，配合契约测试拦截不兼容发布。落地要点：spec 入库版本化、变更走评审、生成代码不入手工改动（改 spec 而非改生成物）、把 spec 校验/生成纳入 CI 门禁。AI 时代的价值：AI 生成前后端代码都以 spec 为锚，幻觉（错误字段名、错误类型）会被类型与契约校验直接暴露。

答出"单一事实源、自动派生、变更同步门禁"三个价值层次，并点出 AI 时代 spec 作为校验锚点的意义。

• 流程各阶段的产品（文档、计划、代码、证据）
• 可验证证据（编译/测试/Lint 通过）作为完成标准
• 与 AI Agent 工作流的结合

Spec-Driven 流程把"需求 → 代码"显式化为可审查的链路：RFC/Design Doc——用自然语言 + 接口草案描述要解决的问题与方案（决策记录：为什么这么做）；计划——把方案拆成可执行任务（按依赖排序、标注影响面）；实现——按计划编码（人写或 AI 写）；可验证证据——每个任务以"编译通过 + 测试通过 + Lint 通过"为完成标准（证据可审计：CI 产物、测试报告），"完成 = 有证据"而非"感觉写完"；Code Review——按计划与证据审查 diff（是否按计划实现、证据是否真实覆盖）。落地要点：文档轻量化（模板化避免文档负担）；任务粒度小（每任务可独立验证）；证据入库（CI 报告与 commit 关联）；AI Agent 化——Agent 按"spec → plan → task"拆解并自执行验证（跑测试作为完成证明），人审 spec 与计划、审证据与 diff；规范层（AGENTS.md）规定"Agent 必须在提交前运行完整验证命令并附结果"。价值：把 AI 产出纳入"有据可查"的工程流程，防止"看起来完成"。

答出五阶段的产物与"可验证证据作为完成标准"的核心，落到 AI Agent 的"自验证证据"工作流与人工审查分工。

• 四阶段的职责划分（目标、拆解、执行、验证）
• 阶段间产物传递与上下文隔离
• 人工介入点与失败回退

多阶段 Agent 协作把大任务拆成职责清晰的阶段：Spec——定义目标与验收标准（需求、接口、行为约束）；Plan——把 spec 拆成有序任务（依赖图、影响面、估计）；Task——执行具体任务（读写代码、跑命令），通常再委派 sub-agent 并行；Verify——验证任务产物（编译/测试/lint/截图），不达标回退重做。设计要点：阶段间只传递"产物 + 标准"（spec 是 Task 的输入，Verify 的标准来自 spec），上下文按阶段隔离（Task 阶段不需要完整 spec 细节）；任务粒度保证可验证（每 task 有明确 verify 命令）；人工介入点——spec 与 plan 必须人审（方向性决策），Task/Verify 可自动化，Verify 失败超限回退 Plan 调整；失败回退——Verify 失败 → 修复循环（限次）→ 仍失败回 Plan 重新拆解或回 Spec 澄清需求，形成"回退链"。工程价值：复杂任务可并行与规模化（多 sub-agent）、产出可追踪（每阶段留痕）、质量可控（验证门禁），把"AI 一口气干完"变成"分阶段可审计"。

答出四阶段职责、产物与上下文隔离、人工介入点与"验证失败逐级回退"的机制，体现 Agent 协作的工程编排。

• 任务分解（按包/按模块划分 sub-agent）
• 上下文隔离与共享接口（依赖边界）
• 冲突处理（共享文件、依赖顺序）与结果合并

monorepo 跨包任务的 sub-agent 化：分解——按包/模块边界划分（依赖图中无环的子树分给不同 sub-agent），每 agent 只读自己负责目录 + 必要的共享类型/接口定义，上下文聚焦；执行——各 sub-agent 独立跑验证（该包编译/测试），依赖顺序编排（下游包等上游契约变更合并后再动，或契约先行：先让上游包提交契约变更，下游再适配）；冲突处理——共享文件（根配置、公共类型）由主 agent 统一改或串行化，sub-agent 只允许写自有目录（工具层限制写入范围），避免互相覆盖；结果合并——各 sub-agent 提交小批次 diff，主 agent 汇总验证（全仓编译/测试），冲突提交在 git 层解决（先后合并 + 重跑）。工程要点：affected graph 驱动任务编排（知道改哪个包影响哪些包）；sub-agent 数量与任务粒度匹配（过多 overhead、过少失去并行）；每 sub-agent 的产物独立可回滚；共享契约文件用"变更锁"（谁先提交谁定义）。价值：把大仓库重构从"单 Agent 长跑"变成"并行 + 门禁"的可控流水线。

答出按依赖边界分解、上下文隔离与契约先行、写入范围限制与合并验证三个核心，体现 monorepo Agent 编排。

• 两类输出模式（组件级、全栈应用级）
• 生成技术的栈与工程化程度
• 边界（接入既有代码库、质量、维护）

输出模式分两级：组件级（v0.dev、Builder.io）——从设计稿/文字描述生成 UI 组件（React/TS + Tailwind/shadcn 风格），输出可粘贴进项目，价值是"快速出界面草稿与组件原型"；全栈级（bolt.new、Lovable、Replit Agent）——从 PRD 生成完整应用（前端 + 后端 + 数据库 schema + 部署配置），在浏览器内可预览迭代，价值是"从 0 到 1 的完整脚手架与 MVP"。工程边界：接入性——生成物是"独立项目"形态，接入既有代码库需人工迁移（组件规范、路由、状态管理、鉴权要重接）；质量——生成的架构决策（数据模型、错误处理、安全）是通用模式，复杂业务与性能边界（大列表、实时性）需人工重构；可维护性——生成代码的注释、命名、测试覆盖参差，长期维护成本要评估；数据与安全——全栈生成默认配置的鉴权/密钥管理需人工加固；合规——生成代码的 license 与依赖审查。工程实践：把生成工具用于"原型与骨架"阶段，产出作为需求表达（比文字 PRD 直观），进入正式开发时按团队规范重写或迁移，配合"生成 → 人工架构评审 → 测试补强"的流程。

答出两类输出模式的能力边界、以及"原型化定位、迁移成本、架构与安全加固、合规审查"的工程边界。

• 对齐的三个抓手（约定、token、白名单）
• shadcn/ui 的"复制进项目"模型与 AI 兼容性
• 防漂移（生成代码绕过设计系统）的治理

对齐策略三抓手：组件白名单——在规则文件（AGENTS.md）中声明"AI 只能使用项目已注册的组件（如 Button、Card、Dialog），禁止自创样式类与临时组件"，配合 lint 规则（禁止未知组件 import、禁止裸 class 堆砌）强制；design token 注入——把设计系统的 token（颜色、间距、圆角、字体）作为规范注入 AI 上下文（"背景用 bg-background，不要硬编码 #fff"），生成代码只引用 token 而非魔数，样式一致性由 token 层保证；shadcn/ui 约定——shadcn/ui 的模型是"组件源码复制进项目（components.json 管理）"，AI 生成时让其"基于项目内 shadcn 组件组合"，而非重新发明；shadcn add 可把新组件规范化接入，AI 引用即获一致基础样式。防漂移治理：审查 diff 中"非 token 颜色、内联样式、非白名单组件"自动告警；设计系统变更（token 改值）时全项目（含 AI 生成部分）自动生效——这正是 token 对齐的收益；AI 生成的演示样式与正式样式区分（原型可自由、合入需对齐）。落点：把"用设计系统"变成 AI 可执行、机器可检查的规则。

答出"白名单约束、token 注入、shadcn 约定"三抓手与防漂移的自动检查，体现设计系统治理的 AI 时代方案。

• Schema-first（SDL 定义契约）与 code-first 的差异
• 前端类型与查询的自动生成（graphql-codegen）
• 契约变更的治理（schema 校验、breaking change 检测）

Contract-first GraphQL 指先以 SDL（Schema Definition Language）定义类型与操作契约，再实现 resolvers（服务端）与消费（客户端），而非从代码反推 schema。工程价值：契约先行——前后端从同一 schema 工作，前端可先于后端按 schema 开发（mock）；类型安全——graphql-codegen 从 schema + 查询文档生成 TS 类型与 hooks（typed queries），查询错误（字段不存在、类型不匹配）编译期暴露；可演进——schema 评审与 breaking change 检测（如删除字段）在 CI 门禁拦截，避免破坏既有客户端；自文档——schema 即文档，配合 GraphiQL 探索。前端实践：查询以 .graphql 文档或 gql 标签编写，codegen 生成类型化结果；用 Apollo/urql 执行；schema 变更后重跑 codegen，类型错误即时暴露影响面。边界：code-first 适合快速迭代与类型复用（如 TypeScript 后端），但契约可见性与跨端一致性弱；混合模式（运行时 code-first + 导出 SDL 发布）也是常见折中。AI 时代：契约文件让 AI 生成的前端查询被类型校验直接约束，减少字段幻觉。

答出 Schema-first 的契约价值、codegen 类型安全、breaking change 门禁，并对比 code-first 边界与混合模式。

• Hooks 的触发点（pre-commit、pre-push、CI job）
• 脚本职责（格式、lint、扫描、验证）
• 边界（不阻塞合法流程、可跳过策略、维护）

Hooks 在自动化边界的应用：pre-commit——本地提交前执行轻量检查（格式化、lint、密钥扫描、单元测试快跑），把"最便宜的错误"拦在本地，减少 CI 浪费；pre-push——稍重检查（完整测试、类型检查）；CI——合并门禁（全量测试、安全扫描、构建、spec 校验）。AI 协作时代的扩展：Hooks 校验 AI 产物——AI 生成的代码先过同一批检查（格式、lint、扫描、测试），不合格自动回退或标记；Claude Code 等工具的 Hooks 机制（PreToolUse/PostToolUse）可在 AI 工具调用前后执行脚本（拦截危险命令、校验写入内容、记录审计），把 AI 纳入既有流水线。设计边界：速度——pre-commit 必须快（>10s 就没人愿意等，慢的放 CI）；可绕过——本地 hooks 可被 --no-verify 绕过（设计上允许，靠 CI 兜底）；确定性——CI 的检查必须与本地一致（版本固定）；维护——hooks 脚本要版本管理与测试（坏的 hook 阻塞全团队）；职责分层——本地查格式与浅层，CI 查全量与安全，避免重复劳动。价值：把"质量门禁"下移到最便宜的环节，AI 时代把 AI 动作也纳入同一门禁体系。

答出触发点分层（pre-commit 轻、CI 全量）、对 AI 产物的校验扩展、以及速度/绕过/维护的边界设计。

• 四类验证的层次（静态 → 逻辑 → 视觉）
• 每步验证作为 AI 任务完成标准
• 失败回退与证据留痕

小步验证指把"验证"拆成可逐层执行的检查，作为 AI 任务（尤其 UI 生成）的完成标准：编译/类型检查——第一道（类型错误、字段幻觉立即暴露）；单元测试——逻辑正确性（组件行为、业务函数）；Lint——规范与潜在 bug（未用变量、危险模式）；运行时截图——视觉验证（AI 生成 UI 后截图，人/视觉模型确认布局、样式、响应式是否符合预期），是 UI 类任务特有的"证据"。应用方式：AI 每个任务完成后必须执行对应验证并附证据（构建日志、测试报告、截图）；验证按成本排序（快的前置，慢的按需）；截图验证——多尺寸（移动/桌面）截图供人审，或用视觉回归（对比基线图）捕获意外变化。失败处理：任一步失败 → AI 读错误修复（限次）→ 仍失败标记该任务失败（不带着错误进入下一步）。价值：把"看起来完成"变成"验证过才完成"，小步验证让失败定位小、回滚粒度小、证据链完整（每个 commit 关联验证产物）。

答出四类验证的层次与"完成=有证据"标准、截图验证的 UI 特有价值、以及失败回退与证据留痕。

• 结构约定（目录、命名、文件大小）对 AI 上下文的影响
• 显式化（类型、导出、注释）降低 AI 猜测
• 检索友好（符号索引、可发现性）

AI 友好的代码结构优化的是"AI 读取与生成的准确率"：目录与命名约定——按职责清晰划分（components/features/lib），命名直白一致（AI 从名字推断用途），避免"谜之目录"；文件粒度——文件不要过大（AI 上下文有限，大文件读不全导致"只见局部"），组件/函数单一职责；显式化——类型定义前置（类型即文档）、导出集中（index 文件）、显式依赖（少魔法全局变量），AI 生成时不易臆造；检索友好——符号命名可被代码检索命中（相关文件可被 AI 找到）、README/规则文件说明模块职责与用法；规则文件——AGENTS.md 写明"新组件放哪、命名规则、可用组件清单"，AI 生成即符合结构；一致性——已有代码是什么风格，生成代码就按什么风格（AI 模仿上下文）。落地：把"AI 可读性"纳入代码评审维度（新结构考虑 AI 是否能快速理解）；定期用 AI 工具试跑（从 README 出发能否找到并修改目标模块）作为结构体检。价值：结构友好 → AI 上下文质量高 → 生成代码质量高，是"低摩擦 AI 协作"的工程投资。

答出命名/粒度/显式化/检索友好四类结构约定与规则文件的作用，强调"结构决定 AI 上下文质量"。

• shadcn add 的"复制源码入项目"模型与可控性
• AI 生成组件的输出形态（独立组件 vs 项目集成）
• 接入边界（依赖、样式系统、版本演进）

两条组件获得路径的边界：shadcn add——从 registry 拉取组件源码复制进项目（components.json 管理），特点是"源码可见、完全可控、可改写"，依赖最小（基于 radix + tailwind + class-variance-authority），样式与项目 token 直接融合；v0.dev/Builder.io——AI 根据描述/设计稿生成组件（可导出为 shadcn 风格代码），特点是"按需定制、生成快"，但输出需审查（依赖引入、样式实现、可访问性）。工程边界：集成度——shadcn add 的组件天然符合项目约定（可配置别名、主题），AI 生成组件需人工接入（移入组件目录、适配 token、改导出）；依赖与质量——AI 组件可能引入未注册依赖或自定义 CSS，需 diff 审查与依赖评审；演进——shadcn 组件随 registry 更新（可手动跟进），AI 组件是快照（无官方更新通道，维护自担）；可访问性——shadcn 组件默认带 radix 的可访问性实现，AI 生成组件需逐项检查（键盘、aria）。实践：基础组件用 shadcn add（稳定基线），业务特色组件用 AI 生成后规范化（过 lint、token 对齐、a11y 检查）再入库，两者都遵循"组件入库评审"流程。

答出"复制源码可控"与"AI 按需生成"两条路径的差异与接入/依赖/演进/a11y 边界，落到组件入库评审。

• 两者能力（浏览器内运行、全栈、AI 生成）
• 取舍维度（环境真实性、性能、部署）
• 适用场景（原型 vs 正式开发）

两者都是浏览器内开发环境：StackBlitz 是 WebContainer（浏览器内 Node.js 运行时，真实执行 npm/构建/Dev Server），支持导入仓库、即时预览、可与 IDE 联动；Bolt.new 在其基础上加 AI 生成——从提示词生成全栈应用（前端 + 后端 + 数据库），浏览器内运行与迭代，可导出/部署。取舍维度：环境真实性——浏览器内沙箱模拟完整工具链（能跑构建与测试），但与本地环境仍有差异（原生模块、特殊网络、性能上限），大型应用与原生依赖受限；性能——浏览器内编译与服务器在响应速度与资源上限（内存/时长）上有别；协作——浏览器内分享预览方便（评审、演示），但多人开发仍回 git；导出与部署——生成应用可导出到本地仓库或连接部署平台，但数据库/密钥等生产配置需另行处理。适用场景：原型与 MVP 迭代（快速从想法到可跑应用）、设计评审与教学（秒级分享）、探索性验证；正式工程开发仍以本地/CI 为主。取舍结论：把浏览器内全栈作为"快速原型与验证"的杠杆，正式开发回到标准工程流程，生成产物作为起点而非终点。

答出 WebContainer 机制与 AI 生成能力、环境真实性/性能/部署的三类取舍、以及"原型杠杆、正式开发回流"的定位。

• 多规则文件的继承与覆盖优先级规则
• 目录作用域与包所有权约束
• 自动检查（CI 校验 AI 变更范围）的落地

优先级规定（三层）：加载距离优先——AI 工作目录最近的规则文件优先（packages/a/AGENTS.md 覆盖根级 AGENTS.md）；工具特定文件优先——同一目录下 .cursorrules > CLAUDE.md > AGENTS.md（或按工具读取顺序，需在文档中显式声明，避免歧义）；方向约束——根级文件声明"全局禁止/必守"项，目录级只能细化不能推翻（全局安全约束不可被局部覆盖）。继承语义：目录级规则继承根级规则，同名条目按优先级覆盖，冲突条目（根级说 A、目录级说 B）以高优先级为准，并在规则文档中写明"优先级仲裁表"。包所有权：每个包声明 owner（OWNERS 文件），AI 跨包修改需主 agent 协调或受限工具（只允许写本包目录）；自动检查——CI 中跑"变更范围校验"：AI 提交的 PR 检查改动文件是否落在任务声明的允许目录（包边界、生成目录如 src/generated/**、安全敏感目录如 .env、密钥、CI 配置），越界即失败，防止 AI 跨包乱写或碰敏感文件；检查规则与规则文件同源（规则即配置，AI 与 CI 用同一份约束）。落地：规则文件版本化评审（本身过 PR）、CI 校验脚本入仓、违规样本归集优化规则。

答出"距离优先+工具特定优先+全局不可覆盖"的优先级模型、包所有权与敏感目录约束、以及 CI 变更范围校验的自动化闭环。

• 生成链（spec → 类型/客户端/mock）与生成器选择
• 同步机制（CI 再生成、diff 检测、pre-commit）
• 手动代码与生成代码的边界

生成链：OpenAPI spec（单一事实源）→ openapi-typescript 生成类型定义 → orval 生成类型安全 API 客户端（含 react-query hooks）→ MSW 按 spec 生成 mock handlers（开发/测试用）；生成物统一输出到约定目录（如 src/api/generated/**）并标记"勿手改"。同步机制：CI 门禁——spec 变更时强制重新生成并 diff 检查（生成物与 spec 不一致则失败），本地用 pre-commit/pre-push hook 重新生成；变更影响面——spec diff 后类型检查暴露所有受影响调用点（字段删除 → 编译错误），配合契约测试（请求/响应按 spec 校验）保证运行时一致；版本化——spec 变更走 PR 评审（breaking change 检测工具如 openapi-diff），前端依赖方预先适配。手动边界：生成代码不直接手改（改 spec，或通过"扩展文件"手写补充类型、继承生成类型）；业务逻辑（hook 组合、状态）在生成层之外手写；mock 按场景覆盖生成默认。AI 时代价值：AI 写前端调用时以生成客户端为锚（参数类型即契约），字段幻觉被类型检查拦截，与 spec 变更同步由 CI 强制而非人工记忆。

答出"spec→类型/客户端/mock"生成链、CI 再生成与类型暴露影响面的同步机制、以及生成代码与手写代码的边界。

• 各文件的受众（工具映射）与内容组织
• 重复与冲突管理（单一事实源 vs 工具特定）
• 治理（评审、版本化、同步）

仓库级规范文件是"给 AI 看的仓库文档"，按工具分布：AGENTS.md（Codex/通用 Agent 约定，社区通用标准）、.cursorrules（Cursor 专用）、.claude/CLAUDE.md（Claude Code 专用）、.continue/（Continue.dev 配置与提示词）。治理要点：单一事实源优先——把"通用规范"（架构、命令、约定、禁止项）放一份主文件（如根 AGENTS.md 或 docs/ai-conventions.md），各工具文件用"引用/指针"（如 .cursorrules 里写"见 AGENTS.md 并补充以下 Cursor 特定项"）而非整份复制，避免多份漂移；工具特定项——各文件只放自己工具的专属配置（Cursor 的 tab 行为、Claude 的 hooks、Continue 的模型路由），与通用规范分离；冲突仲裁——遵循既定优先级（工具特定 > 通用、目录级 > 根级），冲突条目在文档中显式记录裁决；版本化与评审——规则文件本身入仓、走 PR 评审（改规则 = 改团队约定，影响所有 AI 产出）、变更留痕；同步与测试——新增工具时评审其规则映射、用 CI 校验规则文件格式与引用有效性（链接不破、格式合法）。治理目标：一套事实，多处消费，工具换用不丢规范。

答出"工具映射、单一事实源 + 引用指针、冲突仲裁与版本化评审"的治理模型，体现规则资产的工程管理。

• tRPC 的机制（server 定义 → 客户端类型推导）
• 端到端类型安全的收益（零 schema 漂移、重构安全）
• 边界（全栈 TS 绑定、跨语言/性能场景）

tRPC 的机制：在服务端用 TS 定义 router（procedure 树，输入输出有类型），客户端通过类型推导直接获得完全匹配的调用 API——没有代码生成、没有运行时 schema 校验文件，类型是"推导"而非"生成"，从源头消除"前后端类型漂移"。工程价值：重构安全——改服务端类型，客户端编译错误即时列出所有受影响调用；零契约维护——不需要 OpenAPI 文档同步（类型即契约，IDE 内可见）；开发效率——客户端调用带完整类型提示与参数校验；单一 schema——服务端定义是唯一事实源。边界：绑定全栈 TypeScript（前后端必须同语言同仓库或共享包）；性能——默认 JSON over HTTP，高吞吐/流式场景需配合其他方案（tRPC 也支持与 tRPC-streaming 等扩展）；跨语言客户端（iOS/小程序原生）无法直接用；与 OpenAPI 的关系——需要对外暴露文档/跨端时仍要 OpenAPI 桥（tRPC-openapi 导出）。AI 时代价值：AI 生成的前端调用被类型直接约束（字段幻觉编译期失败），tRPC 是"AI 友好"的契约形态。

答出类型推导机制与零漂移价值、全栈 TS 与跨语言/性能的边界、以及 AI 时代的类型约束价值。

• Protobuf 的 schema 与代码生成（多语言）
• Connect-RPC 的协议演进（HTTP/1.1 兼容）
• 跨端（Web/移动/服务端）的一致契约

Protocol Buffers（protobuf）：以 .proto 定义消息与服务契约，编译生成多语言代码（TS/Java/Go/C++），二进制编码紧凑高效，是跨语言 RPC 的通用契约语言。Connect-RPC：在 protobuf 之上提供更 Web 友好的实现——支持 HTTP/1.1 与 JSON（浏览器环境不强制 HTTP/2 与二进制），生成 TS 客户端（connect-es），解决"gRPC 在浏览器不友好"的经典问题。工程价值：跨端一致——一份 .proto 生成 Web/移动/服务端代码，三端契约严格一致，杜绝手写接口漂移；效率——二进制编码 + 强类型（字段号稳定演进）；可演进——protobuf 的字段编号兼容规则（增删字段的兼容性管理）；流式——支持双向流（chat、实时数据）。边界：生成流程与工具链（buf 等）要纳入 CI（生成物校验）；学习成本高于 REST/JSON；浏览器端调试不如 JSON 直观；非全栈场景的工程化投入（代码生成、版本管理）要评估。AI 时代价值：契约先行让 AI 生成的各端代码都被 proto 类型约束，跨端字段幻觉减少。

答出 protobuf 契约与多语言生成、Connect-RPC 的浏览器友好性、跨端一致与可演进价值，以及工具链与学习成本边界。

• 质量评估维度（功能符合、代码质量、安全、性能）
• 生成过程的迭代验证（可运行性、演示）
• 人工接管点（何时从 AI 转人工重写）

质量评估维度：功能符合度——生成应用是否满足 PRD 核心场景（逐条对照验收）、可运行性（部署后是否可用）、代码质量（结构、可维护性、测试覆盖）、安全（鉴权、密钥管理、依赖漏洞）、性能（规模场景下的响应）；评估方法：分级验收清单 + 试运行（真实走核心流程）+ 代码审查 + 安全扫描。人工接管点设计（分层接管）：原型阶段 AI 全权（快速迭代验证想法）；接管触发条件——进入"真实用户/真实数据/真实部署"时接管（功能细节不可控、数据模型要符合业务、鉴权与合规要人工加固）；按模块接管——核心业务逻辑与数据层人工重写（AI 版本作为参考实现），外围 UI 可保留 AI 生成；质量不达标的回归点——AI 迭代多轮仍不满足验收项时转人工（限制无限提示词修补）。工程实践：生成全程留痕（PRD 版本、生成快照、验收记录）；接管后把 AI 生成物当"原型资产"（需求表达、组件参考）而非代码资产；明确的"AI 范围/人工范围"声明文档，避免责任模糊。价值：让生成工具在"高杠杆低风险"区间发挥，人工接管在"风险敏感"区间把关。

答出多维质量评估（功能/质量/安全/性能）与分级验收、以及"按阶段/模块/回归点"设计人工接管点的原则。

• 机械冲突 vs 语义冲突的区分
• 格式化工具作为最终裁决的合理性（确定性）
• 规范与工具的同步治理

先区分冲突类型：纯格式冲突（缩进、引号、换行）——应让代码服从工具（Prettier 强制 reformat）：格式是确定性的、工具统一后 diff 干净、AI 无需纠结风格（跑一次 format 即可）；语义冲突（lint 规则反映的正确性约束：未处理错误、危险模式、不允许的 API）——不能让规范服从工具或绕过，而应修正代码（lint 规则是护栏，绕过即失去保护）。实践原则：机械格式交给工具（AI 生成后统一 format，作为完成步骤之一），语义规则不妥协（修复代码或评估规则本身是否需要调整）；如果 lint 规则确实过时/误报（如规则与项目新约定冲突），走"规则变更评审"而不是"绕过规则"——规范与工具要同源治理：规则变更（.eslintrc/prettier 配置）入仓评审，AI 上下文（AGENTS.md）同步最新规则，AI 生成时主动符合；CI 中 format 检查（而非仅 format 后提交）确保"仓库永远处于格式化状态"。结论：格式听工具的（确定性裁决），语义听规范的（安全与正确性），两者变更都走评审。

答出"格式冲突服从工具、语义冲突修正代码"的区分原则，以及规范与工具同源变更的治理，避免"绕过规则"的误区。

• spec 版本化的语义（semver 化：兼容/不兼容变更）
• 变更日志的结构与自动生成（commit 约定、CI）
• 依赖 spec 的消费方联动（类型生成、契约测试）

spec 版本化设计：采用语义化版本（semver）——breaking change（删字段、改类型、改语义）升 major、兼容新增（加可选字段）升 minor、修复/文档升 patch；版本记录在 spec 文件元数据（openapi 的 info.version 或独立版本文件）；多包 monorepo 中每个 spec 独立版本（各包只依赖相关 spec），根级聚合。Changelog：结构与内容——按版本列出变更（Added/Changed/Deprecated/Removed/Fixed），每条注明影响（破坏性变更标注"迁移指南"）；生成——基于 commit 约定（conventional commits，feat!/fix 标记 breaking）+ CI 自动生成/校验（PR 必须带变更说明，未标注 breaking 的字段删除被 diff 工具拦截）；可读性——按包分组、链接到 PR 与迁移文档。消费方联动：spec 升级（尤其 major）触发下游——重新生成类型/客户端（CI 再生成 + 编译暴露影响面）、契约测试更新、mock 更新；发布节奏——major 变更给消费方迁移窗口（双版本共存期或功能开关）；审计——版本历史回答"这个字段什么时候、为什么变"（与 AI 生成代码的溯源需求契合）。落地：spec 变更 = PR + changelog 条目 + 影响面分析，三者一体评审。

答出 semver 化的版本语义、conventional commits 驱动的 changelog、以及消费方（生成/测试/mock）联动的迁移管理。

• 等价性验证的思路（随机输入对比新旧行为）
• 三类属性的含义与验证价值（幂等、交换、单调）
• 属性测试工具与断言设计（fast-check）

等价性验证的思路：把 spec 当作可执行契约（校验器/参考实现），用 property-based testing（如 fast-check）生成随机输入（合法与非法边界），同时用新旧 spec 的校验逻辑（或新 spec 实现 vs 旧 spec 快照实现）处理，对比输出是否一致——不一致即"行为不等价"需人工评估是有意变更还是回归。关注的属性：idempotency（幂等）——同一输入重复应用结果不变（spec 是转换函数时：apply(apply(x)) == apply(x)，如规范化、格式化类 spec）；commutativity（交换性）——操作顺序无关（字段合并、配置合并类 spec：merge(a,b) == merge(b,a)），AI 重构若改变处理顺序会破坏它；monotonicity（单调性）——输入增强输出不减弱（如过滤条件放宽后结果集合不缩小，可用于 diff 类/过滤类 spec）。验证设计：为每类 spec 声明"期望保持的属性"，属性测试随机输入下断言属性成立（而非穷举用例）；除属性外还要做"回归差分"（新旧 spec 对同一随机输入输出一致）——属性保证"结构性质不变"，差分保证"行为不变"，两者结合。边界：等价验证不能覆盖"语义意图"变化（AI 有意修改规格）——发现差异后需人工评审差异是有意还是回归，并把差异样本加入回归集。

答出"属性测试 + 新旧差分"的等价验证框架、三类属性的含义与适用 spec 类型、以及"差异需人工区分有意变更与回归"的边界。

• schema diff 工具与 breaking change 检测
• 契约测试的生成与运行（consumer-driven）
• 受影响模块识别的机制（依赖图、代码生成触发）

落地三件套：schema diff 门禁——CI 中用 diff 工具（openapi-diff、buf breaking、graphql-inspector 等）对比 spec 变更，检测 breaking change（字段删除/类型改变/必填新增），breaking 变更需人工评审批准（或强制 major 版本 + 迁移说明），防止"悄悄破坏调用方"；契约测试——用 consumer-driven 模式：消费方（前端/其他服务）声明"我依赖的契约用例"（请求/响应样本 + 校验规则），CI 中后端变更用消费方契约回归（Pact 等），任一消费方契约失败即阻断——捕获"schema 合法但语义不兼容"（如返回 null 破坏前端假设）；受影响模块识别——基于依赖图（monorepo 的 affected 计算：Nx/Turborepo 或自建脚本）：spec 变更时计算"消费该 spec 的所有包/模块"，触发其重新生成类型（如 openapi-typescript）与编译，类型错误直接暴露调用点清单；受影响模块列表进入 PR 描述与评审（审查者核对"列出的都适配了、没列到的确实不受影响"）。工程要点：diff 门禁在前（快速）、契约测试在中（语义）、受影响识别联动生成与编译（兜底），三者证据链都关联 PR；误报治理——白名单已知兼容变更（如文档字段）。

答出"schema diff 门禁、consumer 契约测试、affected 识别联动生成编译"的三层落地，形成 spec 变更的完整影响面防线。