Vibe Coding 治理与质量门禁

• Vibe Coding 定义：以自然语言描述意图，AI 生成代码
• 与传统编程的对比：意图驱动 vs 直接编码
• 工程边界与质量风险（失控、不可验证、责任模糊）

Vibe Coding 是 Andrej Karpathy 提出的概念，指开发者用自然语言描述意图与体验，让 AI（LLM）生成代码，人更关注"想要的体验"而非"具体的实现细节"。它与传统编程的核心差异在于"控制方式"：传统编程是人直接书写逻辑并完全掌控细节；Vibe Coding 是人表达意图、AI 负责生成。其工程边界是：Vibe Coding 适合原型、探索、快速验证想法，而非对正确性、安全、性能要求极高的生产系统。质量风险包括：AI 生成的代码可能逻辑自洽但业务错误、缺乏测试与边界处理、引入隐藏的依赖或安全漏洞、代码库结构性退化（大文件、重复、死代码）、以及"人无法解释与维护"的责任模糊。因此 Vibe Coding 需要强化的工程护栏（评审、测试、门禁）来约束。

Vibe Coding 的本质是"把编码从精确活动变成意图驱动的近似活动"，代价是"确定性"的下降。它放大了个体的产出速度，也放大了"不可控"的风险。工程边界应划在"探索 vs 生产"之间，质量风险则通过门禁与评审来对冲，而不是禁止。

• 传统逐行审 vs 意图符合性审
• 以 Spec 为基准验证 AI 输出
• 测试与验收作为意图符合性的证据

传统代码审查是"逐行审"——人一行行核对代码逻辑、风格、边界，判断实现是否正确。Vibe Coding 时代，AI 生成的代码量大、且逻辑常由 AI 产出，人逐行审成本高且低效，转向"意图符合性审"——审查的重点从"每一行对不对"变成"AI 输出是否符合原始 Spec 的意图"。意图符合性审的证据包括：验收标准是否被测试覆盖、实现是否满足 Spec 的约束、业务行为是否与需求一致。实践中，审查者先对照 Spec 检查"验收是否全部达成"，再抽查关键逻辑与边界，而非逐行通读。为让"符合性"可验证，应把 Spec 的验收标准具体化为可执行测试，让审查者以"测试通过 + 抽查关键点"作为符合性判据。

人是"意图权威"，AI 是"实现主力"。逐行审把人的注意力放在"AI 已擅长"的编码细节上，浪费了人的价值；意图符合性审把人的注意力放在"AI 最可能出错"的需求符合性上。审查范式转变的关键是"让 Spec 与测试成为可验证的符合性基准"。

• 高风险模式识别：无测试、无评审、大 PR
• 门禁机制：CI 强制测试、评审 gate、PR 大小限制
• 用门禁把风险"挡在合并前"

Vibe Coding 的高风险模式包括：无测试就提交、无评审直接合并、以及超大 PR（一次改动过多难以审查）。约束这些风险的工程门禁包括：在 CI 中强制测试覆盖与测试通过（无测试或测试失败则无法合并）、强制至少一名人类评审通过（Approval gate）、限制 PR 的 diff 行数与文件数（超出自动拦截并要求拆分）、以及禁止 AI 直接合到主干（必须走分支 + PR + 门禁）。门禁的作用是把"高风险模式"从"靠自觉"变成"硬性不可绕过"，让 AI 生成的代码在进入主干前必须经过测试与人类审查。门禁还可扩展为"AI 代码必须通过静态检查、安全扫描、Spec 一致性校验"。

AI 生成速度快，若没有门禁，无测试、无评审、大 PR 会以极低成本堆积，把质量风险全部后置到生产。门禁的本质是"把风险拦截在合并前"，用自动化强制最小质量底线的同时，保留人类评审的兜底。PR 大小限制尤为关键，因为大 PR 无法被有效评审，等于绕过评审。

• 需求颗粒度：从模糊意图到可验收描述
• 验收标准先行：先定义验收再让 AI 实现
• 用验收约束约束模糊输入

Vibe Coding 中，需求描述越模糊，AI 输出的可用性越低、越容易偏离。足以让 AI 产出可验收代码的需求描述级别，应包含：明确的功能行为、输入/输出边界、约束条件、以及可判定的验收标准——即"我能怎么验证它做对了"。模糊的 vibe 输入（如"做一个登录页"）不足以直接产出可验收代码，因为缺少验收基准。用"验收标准先行"约束模糊输入的做法是：在让 AI 生成代码前，先明确写出验收标准（Given/When/Then 或可断言的清单），让 AI 以验收标准为目标进行实现；验收标准缺失时，拒绝进入实现，先补齐。这样将"模糊意图"收敛为"可验收契约"，AI 的输出有了明确的对错判据。

需求颗粒度决定 AI 输出的确定性。"验收标准先行"的本质是把"对"的定义前置——先定义怎么算对，再让 AI 去实现，从而把模糊的 vibe 输入转化为可验证的契约。没有验收标准，AI 的输出无法判定"对或错"，只能靠运气的迭代。

• 探索代码 vs 生产代码的边界划分
• AI 占比的分层接受度
• 人类介入的 SOP（何时必须人工）

团队应对 Vibe Coding 采取分层接受度：探索代码（原型、实验、一次性脚本）允许高 AI 占比与低人工介入，接受快速迭代与不完美；生产代码（线上服务、核心业务、安全敏感）要求低 AI 占比、高人工介入与完整质量门禁。边界划分可通过目录、仓库或标记物理隔离（如 exploration/ 目录或 prototype 仓库），确保实验代码不会未经治理流入生产。人类的介入 SOP 依据风险分层：探索阶段可最小人工介入；生产代码必须人工评审、测试、把关，且 AI 占比越高，人工介入越强。SOP 应写明"什么代码允许 AI 主导、什么必须人工主导、AI 产出达到什么门槛才可进入生产"。

分层接受度承认"AI 的价值在不同场景不同"——探索追求速度，生产追求可靠。边界与 SOP 是"分层"的落地：物理隔离防污染，介入 SOP 防失控。核心是"不同风险等级对应不同 AI 使用等级"，避免一刀切。

• 上下文卫生：AI 生成导致的代码库污染
• 大文件、重复代码、死代码的累积机制
• 静态检查与门禁预防

"上下文卫生"指 AI 生成代码时，若上下文不干净，容易产出大文件、重复代码、死代码等"污染"，日积月累降低代码库的可维护性。AI 倾向于"在现有文件里追加"而不主动拆分，导致文件失控变大；对相似逻辑可能重复生成而非复用；还会留下未使用的函数、导入与分支。防范措施包括：用静态检查工具（复杂度、文件长度、重复率、未使用代码检测）在 CI 中设置阈值门禁，超限即拦截；在 prompt/规范中明确要求"优先复用现有函数、拆分大型模块、删除无用代码"；把"上下文卫生"纳入评审与重构任务；定期用工具清理死代码。核心是让"卫生"成为门禁的一部分，而不是靠 AI 自觉。

AI 生成的高效也带来"低质量累积"的加速。上下文卫生问题源于 AI 倾向"最小改动、就地追加"，缺乏人的"全局整洁"意识。用静态门禁与规范约束，把"卫生"从"感觉"变成"可检查的指标"，防止 Vibe Coding 快速把代码库做成"大泥球"。

• AI 初稿与人工重构的分工
• 重构介入点：在功能正确后再重构
• 评审介入点：与重构配合

"AI 初稿 + 人工重构"工作流中，AI 先产出可运行的初稿，人随后重构与完善。介入点设定原则：先验证功能正确性，再重构质量——AI 初稿先通过测试与验收（功能对），之后才进入人工重构（结构调整、命名、边界完善）。重构介入点应放在"功能验证通过之后"，避免在功能未验证时重构被反复推翻；评审介入点应与重构配合，通常在重构完成后、合并前进行，评审关注"重构是否改善可维护性、是否符合规范"。为避免 AI 初稿质量过差导致返工，可在 prompt 中预设质量要求；重构介入的频率与深度取决于风险等级，生产代码重构更彻底。

介入点设定的核心是"先对后好"——先保证功能正确，再优化结构。若在功能未验证时重构，会造成"改错方向"的浪费；若只评审不重构，AI 初稿的结构问题会累积。把"功能验证"设为重构前提、"合并前"设为评审关口，是高效且可控的介入方式。

• Vibe Coding 的定义
• AI 驱动开发的质量风险
• 风险对冲的工程手段

Vibe Coding 指开发者用自然语言描述意图、让 AI 生成代码的开发方式，开发者更关注"想要的体验"而非"如何实现"。作为 AI 驱动开发，其质量风险包括：AI 生成的代码可能出现业务语义错误、缺乏边界与异常处理、测试覆盖不足、安全漏洞、重复与死代码、以及"看起来能跑但难以维护"的结构性退化。更隐蔽的风险是"确定性下降"——AI 输出不稳定，语义理解可能偏离意图，且人难以解释 AI 生成的逻辑。对冲手段包括：把需求写成可验收的规格、强制测试与评审、用静态与安全扫描门禁、保留人工对关键逻辑的把关、以及用 AI 质量度量（如变异得分、回滚率）持续监控。

Vibe Coding 的价值在速度，风险在质量与可控性。定义上它强调"意图驱动"，风险上则集中体现为"AI 的不可靠"。质量风险不是靠"禁止 AI"解决，而是靠"把 AI 放进可控的工程框架"（规格、测试、门禁、度量）来对冲。

• 输入治理：控制 AI 的输入质量
• 需求与规格的明确化
• 验收标准作为输入的一部分

Vibe Coding 的输入治理指"控制进入 AI 的需求与规格质量"，因为输入的质量直接决定输出的质量。治理要点包括：把模糊需求明确化为结构化规格（行为、边界、约束、验收）；在输入中写清技术栈、代码风格、禁止事项等工程约束；明确验收标准，让 AI 有可判定的目标。输入治理的核心是"消灭歧义"——用可验证的描述替代模糊的愿望，用验收标准锁定"对"的定义。团队可建立统一的输入模板（如 spec 模板、prompt 模板），让 AI 输入有固定结构，减少"即兴发挥"导致的偏差。输入治理还要求"人先想清楚，再交给 AI"，避免把未想清楚的需求直接抛给 AI。

"垃圾进、垃圾出"在 AI 时代尤为突出——AI 无法理解未想清楚的需求。输入治理把质量关口前移到"需求表达"环节，用结构化规格与验收标准减少歧义。它与"验收标准先行"一脉相承：明确输入，才能得到可验收的输出。

• 探索/原型与生产代码的物理隔离方式
• 目录、仓库、标记（命名/配置）隔离
• 防止实验代码污染生产

防止实验代码流入生产，需对探索与生产代码做物理隔离。方式包括：目录层隔离（如 src/exploration/ 与 src/main/ 分开，或 experiments/ 顶级目录）、仓库层隔离（探索代码放独立仓库或分支，生产代码在受保护主干）、标记层隔离（用命名前缀、配置文件、构建标签区分，如 exploration 禁用生产部署）。最严格的是仓库级隔离——探索代码根本无法出现在生产构建路径中。此外，生产代码应设"受保护合并"（需评审 + 门禁通过），探索代码则不能进入生产部署名。物理隔离的配套是"路径与门禁"——CI 只对生产路径执行完整质量门禁，探索路径不触发生产部署。

物理隔离是"探索不受控"与"生产需治理"矛盾的制度解。目录/仓库/标记把"高风险实验"与"高要求生产"从结构上分开，使实验代码无法"顺手"并入生产。关键不是"封禁探索"，而是"让探索不产生生产风险"。

• 各类 AI 配置文件的用途
• 配置的治理（版本管理、评审）
• 多工具间的同步

.cursorrules、CLAUDE.md、AGENTS.md 是不同 AI 工具（Cursor、Claude Code、通用 Agent）读取的团队规范文件，用于定义代码风格、构建命令、约束与工作流。治理要点包括：将配置文件纳入版本管理与评审（像代码一样做 PR 评审），避免随意改动；统一维护并同步多份配置，避免各工具规范不一致；明确配置的优先级与生效范围；定期审查配置是否与团队实际规范一致（如构建命令变化要及时更新）。同步可由脚本或模板生成，保证多工具共享同一份"规范源"。治理的目的是让 AI 工具的行为与团队规范对齐，而不是每个 AI 各搞一套。

这些配置文件是"AI 的文档"，治理它们等于治理"AI 行为"。纳管 + 评审 + 同步，让规范文件成为受控资产，避免 AI 读取过时或冲突的配置。同步是难点，多工具多文件易漂移，因此用"单一规范源 + 生成"来保证一致。

• 可运行之外的验收维度
• 测试、评审、安全、性能等质量证据
• 文档与可追溯性

Vibe Coding 的产物验收，仅"可运行"远远不够，还需多种质量证据：测试证据（新功能有测试且通过、覆盖率达标）、评审证据（人工智能评审通过、符合 Spec 与规范）、安全证据（通过安全扫描、无已知漏洞）、性能证据（满足性能要求、无性能回归）、可维护性证据（复杂度/重复率达标、无死代码）、以及可追溯性（代码对应 Spec 条款、变更可追溯）。这些证据构成"可运行之外的合格判据"，回答"它不仅跑得起来，而且是对的、安全的、可维护的"。验收时把证据清单化，能跑 + 有证据才视为完成。

"可运行"只证明"能跑"，不证明"正确、安全、可维护"。Vibe Coding 尤其容易产生"能跑但有问题"的代码，因此验收必须超出"可运行"，用测试、评审、安全、性能、可维护性等多维证据来判定。证据化验收让"完成"从主观判断变成可核验。

• AI 代码必检项清单
• 静态、测试、安全、规范检查
• 门禁作为强制前置条件

AI 代码的质量门禁必检项应覆盖多个维度：编译/构建通过；单元与集成测试通过且覆盖达标；静态分析（复杂度、重复率、死代码、命名规范）通过；安全扫描（依赖漏洞、注入风险、密钥泄露）通过；lint 与格式规范通过；Spec/需求一致性校验（AI 输出是否符合验收标准）通过；以及必需的代码评审通过。这些必检项作为"合并前置条件"，在 CI 中硬性执行，任何一项不通过则无法合并。门禁的"必检项"应随风险等级调整——生产代码执行全量必检，探索代码可放宽。核心是让 AI 代码在进入主干前必须满足明确的最低质量底线。

必检项是把"AI 代码质量"从"靠人盯"变成"靠系统卡"。列全维度（构建、测试、静态、安全、规范、一致性、评审）是防止 AI 代码"只过一关"就放行。门禁的强制性能遏制 AI 的"快速产出低质量"倾向。

• 输入规范：需求与规格的明确
• 验证规范：测试与门禁
• 审查规范：评审与责任

Vibe Coding 的团队规范应覆盖输入、验证与审查三方面。输入规范：明确需求必须以结构化规格/验收标准输入，禁止把模糊需求直接抛给 AI；规定技术栈、风格与禁止事项。验证规范：规定 AI 产出的测试要求、静态检查、安全扫描与门禁标准，未经验证不得进入主干。审查规范：规定 AI 代码必须经过人工评审、明确责任归属（AI 产出 + 人类 owner 审查）、以及高风险的代码需更严格审查。规范的制定要"可执行、可检查"——写成门禁与 checklist，而不是口号。规范还应随 AI 工具演进迭代。

规范的目的是把 Vibe Coding 纳入可控流程。输入、验证、审查三方面分别对应"源头上可控、过程中可验证、结果上可追责"。规范要可执行（门禁化）才能真正落地，否则只是文档。

• Vibe Coding 与专业开发的适用边界
• 按风险、正确性要求划分
• 边界判断标准

Vibe Coding 与专业开发的边界，本质是"风险与确定性要求"的划分。Vibe Coding 适合风险低、确定性要求低、追求速度的场景：原型、探索、一次性脚本、内部工具、快速验证想法。专业开发适合风险高、确定性要求高的场景：核心业务逻辑、安全敏感、性能关键、数据一致性敏感、长期维护的生产系统。判断标准包括：出错后果是否严重（安全/金钱/数据）、是否需要长期维护与可解释性、是否正确性要求极高（算法、金融、医疗）。边界上，Vibe Coding 可用于"产生初稿"，但最终交付生产仍需专业开发的质量治理（测试、评审、架构）。两者互补而非对立。

边界划分依据"错误的代价"——Vibe Coding 适合"错得起"的探索，专业开发用于"错不起"的生产。边界不是绝对的，同一功能可由 Vibe Coding 起步、专业治理收尾。判断标准让团队在"速度"与"可靠性"之间做清醒选择。

• 产出度量：AI 生成量、效率
• 缺陷度量：缺陷率、回滚率、逃逸
• 度量驱动改进

Vibe Coding 的度量应从产出与缺陷两个层面进行。产出度量：AI 生成代码量、AI 采纳率、生成速度、功能交付速度等，反映"AI 提升效率"，但需注意其易被刷。缺陷度量：AI 代码缺陷率、返工率、回滚率、缺陷逃逸到生产率、AI 生成代码与人工代码的缺陷对比等，反映"AI 输出的质量"。度量应把"产出"与"缺陷"结合看——高产出+低缺陷是理想，高产出+高缺陷说明需要门禁与规范干预。对比设计上，可对 AI 生成代码与人工代码分别统计缺陷率，定位 AI 的薄弱环节。度量结果用于改进 prompt、规范与门禁，形成闭环。

只测产出会鼓励"盲目刷量"，只测缺陷会打击 AI 使用。把产出与缺陷联合度量，才能客观评估 AI 的价值与风险。对比设计（AI vs 人工）能定位 AI 系统性弱点，驱动针对性改进。

• 安全必检：漏洞扫描、注入、密钥
• 性能必检：性能测试、回归
• 可维护性必检：复杂度、重复、命名

AI 代码在安全、性能与可维护性三方面应有明确必检项。安全：运行依赖漏洞扫描与 secret 扫描、检查注入风险（SQL 注入、XSS、命令注入）、校验敏感信息处理；性能：对关键路径做性能测试与基准，检查是否存在明显性能回归（如 N+1 查询、无界循环、内存泄漏）；可维护性：用静态检查评估复杂度、重复率、死代码、命名规范性、内聚度，超阈值即拦截。这些必检项应纳入 CI 门禁，与功能测试并列，作为 AI 代码合并的前置条件。安全与性能决定"能否上线"，可维护性决定"能否长期维护"。

AI 代码最易在"非功能"维度出问题——能跑但安全有漏洞、性能差、结构烂。安全、性能、可维护性三根支柱分别对应"上线安全、运行高效、长期可维护"。把三者纳入 CI 必检，弥补 AI 对非功能质量的忽视。