Skip to content

对 AI 友好的代码 ​

所谓“对 AI 友好”,不是在代码里写更多提示,而是减少猜测。一个协作者能不能快速找到入口、看懂职责、只改必要范围,决定了这次修改稳不稳。

AI 进入项目时,和新人接手代码一样,要先读结构、找入口、判断边界。代码高内聚、低耦合、职责单一,它就更容易做出小而准的修改;逻辑全混在一起,一处改动就可能拖出一串无关问题。

三个核心原则 ​

高内聚 ​

高内聚指的是:相关的逻辑放在一起,一个模块内部围绕同一个目标工作。

例如,一个报名表单组件可以集中处理字段展示、输入状态和前端校验;报名接口服务可以集中处理提交、错误提示和返回结果。这样 AI 修改报名逻辑时,就能快速定位到相关文件。

低内聚的常见表现:

  • 一个文件里同时处理页面展示、数据库、支付、权限和日志。
  • 同一个业务规则散落在多个目录里。
  • 修改一个字段要同时改很多没有明显关系的地方。

更好的做法:

  • 按业务场景聚合相关代码。
  • 把同一类规则放到同一层。
  • 让文件名、函数名、目录名能说明它负责什么。

低耦合 ​

低耦合指的是:模块之间依赖少,改一个模块时不需要大面积修改其他模块。

例如,页面组件不应该直接拼数据库查询,后端接口也不应该直接依赖某个按钮的文案。页面只关心展示和交互,接口只关心输入输出,数据层只关心读写。

高耦合的常见表现:

  • 一个组件直接访问数据库。
  • 一个工具函数偷偷依赖全局状态。
  • 多个模块互相引用,改一处就引发连锁报错。
  • 业务规则写死在 UI 文案或样式判断里。

更好的做法:

  • 用清楚的函数参数和返回值连接模块。
  • 把外部服务、数据库、平台能力包在独立适配层里。
  • 避免跨层调用,页面找接口,接口找服务,服务找数据层。

单一职责 ​

单一职责指的是:一个函数、组件或模块只负责一类清晰的事情。

这不是要求每个函数都很短,而是要求它的变化理由单一。一个函数如果既校验参数、又写数据库、又发短信、又生成报表,那么任何需求变化都可能影响它。

职责不清的常见表现:

  • 函数名很宽泛,比如 handleData、doSubmit、processAll。
  • 一个组件既负责展示,又负责权限判断、接口请求、数据格式转换和错误日志。
  • 一个文件越来越长,但没有明确边界。

更好的做法:

  • 校验、转换、请求、展示、持久化分别放在合适位置。
  • 给函数和模块起能表达职责的名字。
  • 当一个函数出现多个“顺便做一下”时,就考虑拆分。

为什么这对 AI 很重要 ​

AI 修改代码时,最怕两件事:

  1. 找不到应该改哪里。
  2. 改了一处,不知道会影响哪里。

高内聚可以帮助 AI 找到相关上下文。低耦合可以降低误伤范围。单一职责可以让修改点更小,验证更明确。

这会直接影响任务质量:

代码状态AI 的表现
结构清楚、职责明确能快速定位文件,小步修改,给出清楚 diff
逻辑散落、依赖混乱需要读大量文件,容易漏改或过度修改
有测试和构建脚本能修改后验证结果
没有验证方式只能根据静态阅读判断,风险更高

适合 AI 协作的目录习惯 ​

不同技术栈目录不一样,但思路类似:

text
src/
  pages/        页面入口
  components/   可复用组件
  services/     接口请求和业务服务
  utils/        通用工具函数
  types/        类型定义
  tests/        测试用例

后端项目也可以按职责分层:

text
src/
  routes/       路由和接口入口
  controllers/  请求参数和响应处理
  services/     业务规则
  repositories/ 数据读写
  models/       数据模型
  tests/        测试用例

这些目录不是固定标准。真正重要的是:入口清楚、职责稳定、命名可读、验证可运行。

给 AI 的任务应该怎么写 ​

当你希望 AI 按这些原则改代码时,可以这样描述:

text
请先阅读当前模块结构,判断报名流程的页面、接口请求和业务校验分别在哪里。

修改时遵守三个原则:
- 高内聚:报名相关逻辑尽量放在报名模块附近。
- 低耦合:不要让页面直接依赖数据库或平台实现细节。
- 单一职责:表单校验、接口请求、数据转换分别拆清楚。

完成后运行现有测试或构建命令,并说明改动影响范围。

如果是在重构,可以更明确:

text
请只重构代码组织,不改变用户可见行为。
目标是降低耦合、拆分过长函数、让每个模块职责更清楚。
每一步保持可构建,并在最后总结哪些职责被移动到了哪里。

接手一个模块时,先试着从名字和目录找到修改入口,再确认改完后有没有测试或构建可以证明没有误伤。两步都做不到,问题通常不在 AI,而在代码还没有给协作者留下清楚的路。

从 Demo 到商用:用 AI 编程,把 Demo 做成能收钱、能长期运行的项目。