AI Agent / 系统课时

建立编码规范与输出约定

建立编码规范与输出约定

在 Vibe Coding 中,模型生成代码的质量高度依赖明确规则。本节将建立统一的命名、格式、错误处理、注释和测试约定,让 AI 输出更稳定,也让团队协作时的代码更容易维护。

学习目标

  • 理解项目编码规范对 AI 生成结果的影响。
  • 学会设计可执行的代码输出约定。
  • 建立适合人机协作开发的检查规则。

为什么需要编码规范

AI 可以快速生成实现方案,但如果缺少项目约束,同一个需求可能产生不同风格的代码。编码规范的作用不是限制生成能力,而是提前定义什么样的结果可以接受。

规范通常覆盖命名方式、目录结构、异常处理、日志格式、注释要求和测试标准。规则越明确,后续人工审核和自动检查的成本越低。

设计项目输出约定

一个有效的输出约定应该描述结果,而不是只描述过程。例如,不要只要求“写清楚代码”,而应该说明函数命名方式、返回结构、错误处理策略以及必须包含的测试内容。

下面是一个规则片段示例,用于描述 AI 生成代码时的约束:

yaml
coding_rules:
  naming: 使用小驼峰命名变量,使用大驼峰命名类型
  error_handling: 返回统一错误结构,不直接吞掉异常
  comments: 解释设计原因,不解释显而易见的语句
  tests: 核心逻辑必须包含边界测试

这些规则不是程序配置,而是团队与 AI 沟通时使用的约定文本。

在开发流程中应用规则

编码规范最好进入每次生成、修改和审查流程。提出需求时提供规则,生成代码后根据规则检查,发现偏差后继续反馈修正。常见检查项包括:

  • 是否符合项目命名习惯。
  • 是否保持已有接口返回格式。
  • 是否处理异常和边界情况。
  • 是否提供必要测试。

常见错误与改进方式

只描述业务目标而不给技术约束,容易导致 AI 自行选择实现方式。另一个常见问题是规则过于宽泛,例如“代码要优雅”,这种描述无法被准确执行。

更好的方式是把抽象要求转换为检查条件,例如“公共函数必须包含参数说明和异常说明”。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

建立编码规范与输出约定

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通