AI开发规范：实现人机高效协作的务实指南

当工程团队不断壮大，确保代码风格一致会越来越难。现在，随着AI编码助手成为日常开发的一部分，这个问题有了新维度：我们如何让这些不知疲倦、但缺乏“氛围感”的AI伙伴，写出像我们自己人一样的代码？

过去，新入职的工程师能在代码评审和日常协作中，潜移默化地吸收团队的编码习惯和那些不成文的“潜规则”。但AI不同。你不能只丢给它一份文档，就指望它理解为什么某个模块必须用这种特定方式处理错误，或者为什么我们在这里选择复制一小段逻辑，而不是抽象。

这迫使我们必须将那些“只可意会”的团队知识，变成明确、可执行的指南。这不仅仅是约束AI，更是对我们自身工程实践的一次有益审视。

目标：不止于规则，更是共享上下文

制定规范的核心目的，是建立AI与人类开发者之间的共享上下文。一份好的指南，应该能回答以下几个问题：

1.  技术栈与约定：明确项目使用的语言、框架版本、主要依赖库。如果代码库中历史原因存在多种命名风格（例如C++和SQL区分别对待），必须清晰指出。

2.  代码风格的具体抉择：这需要超越“用Prettier格式化”。要明确指出：

    ◦   命名偏好：是fetchUserData还是get_user_data？如何处理重复的名称？

    ◦   结构与格式：虽然格式化工具能处理空格，但对代码块的组织、函数长度的一般性期望、注释应放在方法前还是后，都需要给出倾向性示例。

    ◦   错误与日志处理：我们希望错误如何被抛出、捕获和记录？日志级别在什么场景下使用？这是AI极易忽略，但对可维护性至关重要的部分。

3.  模式与反模式：这是指南的灵魂。需要明确展示“我们这里怎么做”，而不仅仅是“不要做什么”。例如：

    ◦   提供1-2个“黄金标准”的完整代码文件，作为端到端的范例。

    ◦   针对常见场景，如API响应处理、数据库查询封装，给出正面和反面的代码片段对比。AI非常擅长从例子中学习模式。

关键原则：明确、一致、可演进

撰写这类指南时，要像为一位聪明但缺乏背景知识的新同事写作，需遵循几个原则：

•   极度明确，避免歧义：不要使用“通常”、“可能”这类模糊词汇。类似于“应进行合理的错误处理”这样的表述对AI是无效的。应改为“对于网络请求，必须使用try-catch包裹，并在catch块中使用logger.error记录错误上下文和原始异常。”

•   解释“为什么”：说明规则背后的原因，能帮助AI在未覆盖的场景做出更好推断。例如：“我们在此项目中对DTO使用PascalCase，以便与后端C#规范保持一致，减少序列化配置。”

•   将其视为活文档：第一批由AI生成的代码，必然会有不符合预期的地方。不要把这看作是失败，而是优化指南的绝佳反馈。当你在评审中发现AI反复犯同一类风格错误，这正是需要将一条隐含规则显式化的信号。应该建立一个机制，让团队能方便地更新这份指南。

实践：将规范融入工作流

制定文档只是第一步，关键是如何让它发挥作用：

1.  集中化与可访问：将最终指南（例如agents.md或code-context.md）存放在团队的核心文档仓库中，并对所有工程师开放编辑和评论权限。

2.  提供给AI：将指南的核心内容作为自定义指令或系统提示词，注入到你所使用的AI编码助手（如Cursor、Claude for IDE、Windmill等）的上下文中。一些高级工作流甚至可以将指南向量化，供AI实时检索。

3.  不放弃传统工具：指南应与现有的自动化工具（如ESLint、Prettier、Checkstyle、SonarQube）协同工作。这些工具能强制保证最基本的风格一致性，而指南则用于约束那些需要人类（或类人）判断的更高层级的模式。让AI生成的代码先通过自动化检查，能节省大量初级评审时间。

更深的思考：这也优化了我们自己的实践

这个过程带来的一个意外收获是，它倒逼我们反思自身的编码规范。有些规则是在“全手工”时代制定的，目的是降低编写时的心智负担。但在“AI生成+人工评审”成为主流的模式下，某些规则可能需要调整。例如，为了提升代码评审时的可读性，是否允许在单个Pull Request中存在少量重复，以使变更意图更清晰？

为AI制定编码规范，表面上是为了管理非确定性的代码生成，实质上是一次对团队工程共识的显性化、文档化和系统化升级。它最终带来的，是一个对人和机器都更清晰、更可持续的代码库。

在北京心玥软件的团队协作与研发效能提升实践中，我们发现，将这类隐性知识显性化，本身就是一项极具价值的基础设施建设。它不仅能让人机协作更顺畅，更能让新加入的工程师更快融入，让代码库的长期演进更有章可循。