对 AI 友好的代码
所谓“对 AI 友好”,不是在代码里写更多提示,而是减少猜测。一个协作者能不能快速找到入口、看懂职责、只改必要范围,决定了这次修改稳不稳。
AI 进入项目时,和新人接手代码一样,要先读结构、找入口、判断边界。代码高内聚、低耦合、职责单一,它就更容易做出小而准的修改;逻辑全混在一起,一处改动就可能拖出一串无关问题。
三个核心原则
高内聚
高内聚指的是:相关的逻辑放在一起,一个模块内部围绕同一个目标工作。
例如,一个报名表单组件可以集中处理字段展示、输入状态和前端校验;报名接口服务可以集中处理提交、错误提示和返回结果。这样 AI 修改报名逻辑时,就能快速定位到相关文件。
低内聚的常见表现:
- 一个文件里同时处理页面展示、数据库、支付、权限和日志。
- 同一个业务规则散落在多个目录里。
- 修改一个字段要同时改很多没有明显关系的地方。
更好的做法:
- 按业务场景聚合相关代码。
- 把同一类规则放到同一层。
- 让文件名、函数名、目录名能说明它负责什么。
低耦合
低耦合指的是:模块之间依赖少,改一个模块时不需要大面积修改其他模块。
例如,页面组件不应该直接拼数据库查询,后端接口也不应该直接依赖某个按钮的文案。页面只关心展示和交互,接口只关心输入输出,数据层只关心读写。
高耦合的常见表现:
- 一个组件直接访问数据库。
- 一个工具函数偷偷依赖全局状态。
- 多个模块互相引用,改一处就引发连锁报错。
- 业务规则写死在 UI 文案或样式判断里。
更好的做法:
- 用清楚的函数参数和返回值连接模块。
- 把外部服务、数据库、平台能力包在独立适配层里。
- 避免跨层调用,页面找接口,接口找服务,服务找数据层。
单一职责
单一职责指的是:一个函数、组件或模块只负责一类清晰的事情。
这不是要求每个函数都很短,而是要求它的变化理由单一。一个函数如果既校验参数、又写数据库、又发短信、又生成报表,那么任何需求变化都可能影响它。
职责不清的常见表现:
- 函数名很宽泛,比如
handleData、doSubmit、processAll。 - 一个组件既负责展示,又负责权限判断、接口请求、数据格式转换和错误日志。
- 一个文件越来越长,但没有明确边界。
更好的做法:
- 校验、转换、请求、展示、持久化分别放在合适位置。
- 给函数和模块起能表达职责的名字。
- 当一个函数出现多个“顺便做一下”时,就考虑拆分。
为什么这对 AI 很重要
AI 修改代码时,最怕两件事:
- 找不到应该改哪里。
- 改了一处,不知道会影响哪里。
高内聚可以帮助 AI 找到相关上下文。低耦合可以降低误伤范围。单一职责可以让修改点更小,验证更明确。
这会直接影响任务质量:
| 代码状态 | AI 的表现 |
|---|---|
| 结构清楚、职责明确 | 能快速定位文件,小步修改,给出清楚 diff |
| 逻辑散落、依赖混乱 | 需要读大量文件,容易漏改或过度修改 |
| 有测试和构建脚本 | 能修改后验证结果 |
| 没有验证方式 | 只能根据静态阅读判断,风险更高 |
适合 AI 协作的目录习惯
不同技术栈目录不一样,但思路类似:
src/
pages/ 页面入口
components/ 可复用组件
services/ 接口请求和业务服务
utils/ 通用工具函数
types/ 类型定义
tests/ 测试用例后端项目也可以按职责分层:
src/
routes/ 路由和接口入口
controllers/ 请求参数和响应处理
services/ 业务规则
repositories/ 数据读写
models/ 数据模型
tests/ 测试用例这些目录不是固定标准。真正重要的是:入口清楚、职责稳定、命名可读、验证可运行。
给 AI 的任务应该怎么写
当你希望 AI 按这些原则改代码时,可以这样描述:
请先阅读当前模块结构,判断报名流程的页面、接口请求和业务校验分别在哪里。
修改时遵守三个原则:
- 高内聚:报名相关逻辑尽量放在报名模块附近。
- 低耦合:不要让页面直接依赖数据库或平台实现细节。
- 单一职责:表单校验、接口请求、数据转换分别拆清楚。
完成后运行现有测试或构建命令,并说明改动影响范围。如果是在重构,可以更明确:
请只重构代码组织,不改变用户可见行为。
目标是降低耦合、拆分过长函数、让每个模块职责更清楚。
每一步保持可构建,并在最后总结哪些职责被移动到了哪里。接手一个模块时,先试着从名字和目录找到修改入口,再确认改完后有没有测试或构建可以证明没有误伤。两步都做不到,问题通常不在 AI,而在代码还没有给协作者留下清楚的路。