AI 辅助编程实践

• 理解 Vibe Coding 与 SDD 各自的适用场景与风险
• 能根据业务复杂度与风险等级判断"放手"与"主导"的边界
• 对"AI 可替代性"与"人工责任"的工程判断

边界核心由"风险等级"与"可验证性"决定。Vibe Coding 适合创新原型、一次性脚本、低风险工具代码，这类代码错误代价低且可快速迭代，可以放手给 AI 并配合快速验证。而 SDD（Spec-Driven Development）适用于生产级、涉及业务核心、有监管或合规要求、需要长期维护的代码，此时必须人工主导——先由人编写明确的 spec（需求契约），再由 AI 生成实现，最后人工评审。判断标准包括：出错是否影响资金/安全/用户数据、是否进入长期维护、是否需要可追溯性、是否涉及复杂业务语义。凡是"错了代价高、坏了难发现、需要责任追溯"的场景，都必须人工主导并引入 spec 约束。

关键不是"AI 能不能生成"，而是"谁对结果负责、错误如何被及时发现"。Vibe Coding 的问题在于"看起来能跑"但缺少验收契约，容易积累隐性缺陷；SDD 通过把需求先固化为可执行契约，让 AI 的产出有客观验收标准，从而把"放手"限制在风险可控的范围内。

• 完整质量门禁体系（编译、测试、静态扫描、覆盖率、规范）
• 对 AI 代码"能跑但不可靠"特性的针对性约束
• 门禁的自动化落地方式

编译通过只是最低门槛。完整的验收标准应包含：单元测试 + 集成测试通过且断言有效（非假绿）；测试覆盖率达标（如行覆盖率、关键分支覆盖率）；静态扫描门禁（SAST/SonarQube 的复杂度、重复度、坏味道、安全漏洞）；代码规范与 lint 检查；Spec/需求符合度验证（SDD 下比对 spec 与实现）；无安全漏洞（依赖扫描、密钥扫描）；性能与复杂度合理（无 O(n²) 级误用）；以及人工 code review 复核。对 AI 生成代码尤其要强调"测试与断言是否真实覆盖业务逻辑"，因为 AI 常生成"看起来通过但没测到点子上"的测试。

单一检查无法覆盖 AI 代码风险。编译通过只保证语法正确，不保证逻辑正确、安全、可维护。把质量门禁做成 CI 流水线中的自动门（blocking），使 AI 产出在并入主干前必须逐层通过，才能把"AI 提效"转化为"质量可控"。

• 理解上下文注入对 AI 生成质量与安全的影响
• 能设置"给 AI 看什么"与"不让 AI 碰什么"
• 权限与安全边界的具体做法

上下文边界分三层：仓库范围指只向 AI 提供相关模块的代码、文档与规范，避免无关文件造成幻觉或风格漂移，通常通过 .cursorrules、.aiignore、AGENTS.md 或工具的白名单/黑名单控制；依赖范围指明确 AI 可用的依赖与版本、禁止引入不必要或过新的第三方库，防止供应链风险；安全范围指通过 permission 模式、只读模式、沙箱环境限制 AI 对代码的写权限、对敏感信息（密钥、生产数据）的访问权限，并禁止 AI 执行高危命令。落地时把边界写进配置文件并纳入版本控制，让 AI 只在其授权范围内生成与修改。

上下文边界是"AI 提效"与"安全可控"的平衡点。给太多上下文浪费 token 且引入噪声，给太少则生成质量差；不给安全边界则 AI 可能读取密钥、越权修改敏感文件。明确边界后用工具强制（如权限模型、ignore 文件），才能防止 AI 越界。

• 理解"AI 是工具、人是责任人"的责任模型
• 复核记录与来源标记的具体做法
• 团队问责规则的合理设计

AI 本身不承担法律责任，责任归于"引入并确认该代码的人"。责任链通常按"提示者（谁让 AI 生成）→ 编码者（谁采纳并提交）→ 审查者（谁 review 通过）→ 发布者"分层，每一层都有确认义务。明确责任链的手段包括：在提交中标记 AI 生成来源（如 commit message 或 AI 贡献标记）、保留 prompt 与生成记录、人工 review 记录留痕、发布前质量门禁的通过记录。团队问责规则应"追责任链条而非追 AI"，即审查者因未尽审查义务而担责，但前提是审查者有足够上下文与工具支撑。关键是把"AI 生成"与"人工确认"两个环节都留痕，使出现事故时能还原谁在哪个环节确认了什么。

责任归属的核心是"可控性"——只有人能为 AI 的行为负最终责任。通过来源标记与复核记录，把抽象的"AI 出错"转化为可追溯的"某环节人工确认失误"，既保护了使用 AI 的积极性，又保留了追责抓手。

• 真实的 AI 生成质量问题场景
• 能识别"看似合理实则错误"的 AI 代码
• 人工 review 对 AI 代码的兜底价值

例如用 Copilot 生成一个处理时间区间的工具方法，AI 生成了一段看似完整的逻辑，但 review 时发现对"跨年/跨月边界"和"空/非法输入"没有处理，且用了一个已废弃的 API。具体做法是：在 review 中逐分支核对边界条件、追查 API 文档确认废弃、补充单元测试覆盖边界后修正。这暴露了 AI 生成代码的典型问题——"在常见路径上看起来正确，但在边界与异常路径上偷懒"。人工 review 的价值在于用业务上下文和测试思维去验证 AI 的"直觉"，而不是简单信任其输出。

AI 善于生成"统计上常见"的代码，却容易在边界、异常、语义上出问题。Code Review 是发现这类问题的关键环节，重点应放在边界条件、异常处理、安全性、性能与业务语义上，而非格式与风格。

• 将审查经验固化为可复用规范的能力
• Prompt 模板与审查标准的设计思路
• 规范的落地与迭代

过程大致为：先收集团队历史 PR 中反复出现的缺陷（如 NPE、越权、未释放资源、SQL 注入），分类归纳为审查重点；再基于这些重点设计标准化的 AI 审查 Prompt，包含项目背景、规范链接、审查清单（安全、边界、性能、可读性）、输出格式（问题+严重级别+建议+代码定位）；随后把 Code Review 标准（如阻塞项定义、do/don't）写入团队文档并作为 CI 门禁的参考；最后根据 review 效果与误报率持续迭代 Prompt 与清单。关键是把"经验"转成"可执行指令"，让 AI 与新人 review 时遵循同一套标准。

建立规范的价值在于把一次性经验沉淀为可复用的资产。Prompt 模板统一了 AI 审查的输入与输出，审查标准统一了团队的评审口径，二者配套才能让 AI 审查与人工审查的结果一致、可度量、可改进。

• 用 TDD 验证 AI 生成代码的流程
• 理解"红-绿-重构"三阶段
• 测试对 AI 代码的拦截作用

例子：用 AI 生成一个排序/解析函数后，不直接信任，而是先按验收标准写测试（红：未实现或失败），再跑 AI 生成的实现（绿：通过），最后重构使其更清晰。具体做法是：先定义输入输出与边界用例，用 AI 生成测试骨架与实现，运行测试发现失败用例，据此修正 AI 代码直到全绿，再进行去重、命名、拆分等重构。关键收益是让"AI 生成正确"从"感觉上对"变成"测试证明对"，避免直接把 AI 输出当结论。

TDD 提供客观验收标准，弥补 AI 生成代码"缺乏验证"的短板。红绿重构让 AI 先产出、测试后验收、人在最后优化，形成"AI 生成 + 测试验证 + 人工重构"的闭环，显著降低 AI 代码的隐性风险。

• 代码现代化迁移的流程与风险
• AI 在迁移中的辅助价值与局限
• 迁移后的验证与门禁

以 Java 8 → 21 为例：先用 AI 辅助识别仍在使用旧 API（如 Date/Calendar、旧循环、var 缺失）的位置，生成迁移建议（如用 java.time、record、switch 表达式、Stream API）；随后人工评估每处迁移的语义等价性，逐批小步提交；每批用测试与静态分析验证行为不变，最后整体回归。AI 的价值在于快速枚举迁移点与生成候选代码，但迁移必须由人把关"语义等价"，因为 AI 可能把有细微语义差异的代码当成等价替换，尤其在并发、序列化、时区等敏感场景。

代码现代化是高风险重写，AI 能提升效率但无法替代语义验证。正确做法是"AI 提建议 + 人工确认等价 + 测试兜底 + 小步提交"，把大规模迁移拆成可验证的小变更，避免一次性大改引入隐蔽回归。

• 设计人机协作的 review 流程
• 明确 AI 与人工的分工
• 流程的可落地性与效果

设计思路是"AI 首审、人工精审、反馈闭环"。具体流程：PR 提交后，AI 先做首轮审查，产出风格、明显 bug、安全模式、测试建议等意见并标注置信度；人工 reviewer 聚焦 AI 不擅长的架构、业务语义、跨文件影响，对 AI 意见进行采纳/拒绝/忽略；PR 通过后，将高价值意见沉淀为审查规则或 Prompt 反馈，迭代 AI 审查质量。同时设置"AI 意见不自动合并、人工 review 为最终决策"的底线，防止 AI 代审使流程形式化。效果是 AI 承担机械性检查、人工聚焦高价值判断，评审效率提升且质量可控。

人机协作的关键是分工明确：AI 擅长确定性的、可枚举的检查，人类擅长判断性的、需要上下文的决策。工作流把两者串成闭环，并让 AI 从人工反馈中迭代，形成持续改进的能力。

• 理解 AI 时代代码可读性的新要求
• 可维护性标准如何演进
• 对"面向 AI 与新人"双可读性的判断

标准不应降低，反而更强调"人为中心"的可读性。因为 AI 生成代码常有过量注释、命名模糊、逻辑堆砌等问题，需要以"人能否快速理解"为准绳。可读性标准应强化：清晰的命名与单一职责、必要的注释而非解释性废话、一致的风格、可被测试与重构的结构。可维护性上，由于 AI 易产生重复代码与架构漂移，标准需增加"重复度、架构一致性、可测试性"的显性约束。同时，代码还要"对 AI 可读"——干净、规范、上下文清晰的代码能让 AI 后续生成更准确，因此可读性标准实际是"人机双友好"。

AI 时代可读性标准应"升级而非降级"。代码不仅要给人读，还要给 AI 读（作为上下文）；可维护性则要在 AI 放大重复与漂移的背景下，强化结构约束与一致性治理。

• 设计针对 AI 代码的质量门禁体系
• 测试覆盖、静态扫描、人工复核的组合
• 门禁的可执行性与比例权衡

设计原则是"自动化门禁兜底 + 人工复核把关"。测试覆盖：对 AI 生成代码要求新增/变更代码的行覆盖率与分支覆盖率达标（如行覆盖 ≥80%、关键分支达 100%），且断言必须有效（配合变异测试防假绿）；静态扫描：接入 SonarQube/SAST/lint，对复杂度、重复度、坏味道、安全漏洞设阈值并把阻断项设为 CI 门禁；人工复核比例：高风险代码（安全、资金、核心逻辑）100% 人工复核，低风险工具代码可抽样复核（如 50%），并强制 AI 意见不自动合并。同时按代码来源标记，让门禁能区分 AI 生成与人工编写，对 AI 部分施加更严覆盖要求。

门禁要"分层组合"而非单一指标。测试覆盖防逻辑错误、静态扫描防风格与安全、人工复核防语义与架构问题，三者互补，且对 AI 代码施加高于人工的覆盖门槛，才能约束 AI 的"偷懒式"生成。

• 度量重复率与架构一致性的指标
• 治理手段（门禁、规范、重构）
• 原因分析（AI 缺乏全局上下文）

度量：用 SonarQube 等工具统计重复代码率（duplicated lines/violations）、圈复杂度、代码坏味道密度；架构一致性可通过架构守护工具（如 ArchUnit、Depends、Import-madness）检查分层依赖是否违规、模块边界是否被破坏。治理：把重复率与复杂度阈值设为 CI 门禁；建立统一基类/工具类/规范模板，让 AI 生成时优先复用；通过 .cursorrules 或规范文档约束 AI 遵循既有架构模式；周期性用 AI 或人工扫描重复片段并触发重构（提取公共方法、抽公共模块）。根因是 AI 每次只看到局部上下文，容易"另起炉灶"而非复用已有实现，因此要持续把"复用"写入规范与审查重点。

AI 放大重复与漂移的根因是缺少全局上下文。治理需"度量 + 门禁 + 规范 + 重构"四管齐下，把 AI 的局部思维约束在团队既有的架构与复用体系内。

• 理解 AI 生成代码的版权与许可证风险
• 审查手段（依赖扫描、来源记录）
• 合规策略

AI 生成代码可能"复刻"训练数据中受版权保护或特定许可证（如 GPL）的代码，产生合规风险。审查手段包括：对 AI 生成的依赖与算法做许可证扫描（如 FOSSA、Licensee、Sonatype）识别 GPL/AGPL 等传染性许可证；在代码中保留来源标记与生成记录，便于追溯；对高风险代码（算法、知名库实现）比对其"是否高度相似于已知开源实现"；在团队规范中明确禁区（如不得生成与专有代码逐字相似的内容）。策略上，结合企业法律顾问评估，对不清楚来源的代码采用"保守引用 + 独立实现"原则，并避免引入传染性许可。

AI 的"记忆"可能复刻受版权内容，使其输出带许可证风险。合规审查要"扫描 + 追溯 + 政策"结合，把 AI 引入的第三方代码纳入依赖治理，并对高风险场景人工确认来源。

• 设计采纳率与质量影响指标
• 数据采集与可信对比
• 识别因果与干扰因素

采纳率：统计 AI 生成代码占比（AI 贡献行数/总变更行数）、AI 建议接受率、使用 AI 的开发者占比。质量影响：缺陷密度（每千行缺陷数）、返工率（PR 被要求修改或回滚的比例）、审查通过率、测试失败率。评估要点在于"对比基线与控制变量"——对比引入 AI 前后、或使用组与对照组，控制项目复杂度、团队构成等干扰因素，并给出足够观测周期以平滑波动。同时要防止口径注水，如"AI 贡献行数"需人工确认或客观标记，避免把 AI 建议但人工重写的代码也算作 AI 贡献。

评估要"多指标 + 可信对比"。采纳率反映提效，质量指标反映风险，单看采纳率会掩盖 AI 引入的缺陷；只有同时观察变更行数、缺陷密度与返工率，才能判断 AI 到底带来"提效"还是"增量负担"。

• 上下文选择与任务拆解的原则
• prompt 版本管理
• 可复现性的价值

上下文选择：只注入与任务相关的规范、接口、样例，避免无关代码稀释注意力，并明确限制（如"仅使用现有依赖"）。任务拆解：把大需求拆成小任务，每个 prompt 聚焦单一职责，降低 AI 一次生成过多内容导致出错的风险。版本管理：把 prompt 及其引用的规范版本纳入版本控制（如存为 .md/.prompt 文件与 seeds），记录 prompt 的变更，便于复现实验结果与回滚。可复现性来自"固定输入（prompt + 上下文）+ 固定版本（模型 + 规范）"，使同样输入能产出稳定结果，便于团队共享与效果评估。

Prompt 工程化把"随手写 prompt"变成"受控的工程资产"。选择好的上下文提升相关性，拆解控制复杂度，版本管理保证可复现与可迭代，三者共同把 AI 生成从"随机性"推向"可控性"。

• 用 AI 生成测试用例的流程
• 覆盖率的验证方式
• 测试质量（不只是数量）的判断

例子：用 AI 为某业务方法生成测试用例，覆盖正常、边界、异常分支。做法是先让 AI 基于方法签名与业务说明生成用例，再用工具（如 JaCoCo/istanbul）运行并统计覆盖率，发现未覆盖的分支后让 AI 补充对应用例。同时人工审查用例的断言是否有效（防止"断言恒真"的假绿），必要时用变异测试验证断言杀伤力。经验是覆盖率只代表"跑到了"，不代表"测对了"，AI 生成的用例要重点检查断言质量与业务意图。

AI 能快速铺开用例数量，但覆盖率与断言质量需工具验证与人工把关。实践要点是"生成 + 覆盖率统计 + 分支补充 + 断言审查"的闭环，避免 AI 生成大量"刷覆盖率"的无效用例。

• 沉淀 Prompt/Skills 的方法
• 从个人经验到团队规范
• 资产的维护与复用

做法：把团队中验证有效的 Prompt 与 Skill 固化为文件（如 .cursorrules、AGENTS.md、skills 目录、prompt 模板库），纳入版本控制与评审；按场景分类（生成、审查、测试、迁移、重构），并记录适用条件与效果；定期收集"有效/无效"案例迭代模板；把最佳实践继续沉淀为规范文档（如"AI 编码规范""AI 审查清单"）。关键是让个人经验经过验证、评审、固化后成为团队资产，并让新成员能直接复用，避免重复探索。

沉淀形成"个人经验 → 团队资产 → 工程规范"的转化路径。Prompt/Skills 是 AI 时代的"工具与方法论"，版本化与评审使其可复用、可演进，让 AI 使用从个人作坊走向团队标准化。

• 来源标记的实现方式
• 标记的意义（审计、度量、责任）
• 标记的可靠性与治理

实现方式：在 commit message 中注明 AI 辅助（如标题前缀 [AI] 或 Co-authored-by: AI 工具）、在 PR 描述中说明 AI 使用范围、用 CI 检测 AI 生成文件并打标记（如某些工具会为 AI 生成代码加注释或 metadata）、或在代码中保留 AI 来源注释。对 Git 署名，可结合提交元数据与代码快照区分"AI 生成"与"人工修改"。标记的意义是支撑审计（哪些代码是 AI 写的）、度量（AI 贡献率、缺陷密度）、责任追溯（AI 代码缺陷归属）。标记需有统一规范，避免开发者随意标注导致口径失真。

来源标记是把"AI 生成"从不可观测变为可观测的机制。它服务于审计、度量与责任链条，但实现时要统一口径并依赖工具/人工配合，否则标记本身会失真，导致后续度量不可信。