如何设计一个适合 AI Agent 开发的大型项目目录结构

前言

AI Agent 正在改变软件开发方式。

过去项目目录主要是给人看的。

现在项目目录不仅要让开发者容易理解，还要让 AI 更容易理解。

一个结构混乱的项目，即使使用再强的 AI 工具，也容易出现：

• 修改错文件
• 重复创建模块
• 找不到业务入口
• 生成不符合规范的代码
• 无法理解模块边界

因此，在 AI 编程时代，项目目录结构的重要性正在上升。

本文将从真实开发角度，讨论如何设计一个更适合 AI Agent 协作的大型项目结构。

一、AI Agent 为什么需要清晰目录？

人类开发者可以通过经验理解项目。

但 AI Agent 更依赖：

• 文件名
• 目录名
• 注释
• 配置文件
• 规则文件

如果项目结构混乱，例如：

src/
├── aaa/
├── common/
├── test2/
├── new-page/
├── temp/

AI 很难判断哪个目录是真正的业务模块。

它可能会：

在错误目录新增文件
重复实现已有功能
忽略已有工具函数

因此，清晰结构是降低 AI 出错率的第一步。

二、目录设计的核心原则

一个适合 AI Agent 的项目结构，应该满足五个原则。

1. 命名明确

目录名应直接表达含义。

推荐：

components
features
services
utils
hooks
types
config

不推荐：

common
misc
new
test
abc

因为这些命名太模糊。

2. 边界清晰

每个目录应该有明确职责。

例如：

components：通用组件
features：业务模块
services：接口请求
utils：纯工具函数
types：类型定义

AI 在修改时才能判断应该写在哪里。

3. 规则可读

项目应该配合：

README
CONTRIBUTING
.cursor/rules
CLAUDE.md

让 AI 理解项目规则。

目录结构不应只存在于开发者脑中。

4. 避免重复入口

如果同时存在：

api/
services/
request/
http/

AI 很容易不知道该使用哪个。

建议保留一种统一方式。

5. 模块内聚

同一个业务模块相关代码应该尽量集中。

例如用户模块：

features/user/
├── pages
├── components
├── api
├── hooks
├── types

比散落在全局目录中更容易维护。

三、推荐前端项目结构

以 Vue 或 React 项目为例。

推荐结构：

src/
├── app/
├── assets/
├── components/
├── config/
├── features/
├── hooks/
├── layouts/
├── services/
├── stores/
├── styles/
├── types/
├── utils/
└── main.ts

app 目录

用于放置应用级配置。

例如：

router
providers
global setup

AI 看到 app，就能理解这里是应用启动相关逻辑。

components 目录

只放通用组件。

例如：

BaseButton
BaseModal
DataTable
EmptyState

不要把业务组件全部塞进 components。

否则后期会变成垃圾场。

features 目录

这是大型项目最重要的目录。

每个业务模块一个子目录：

features/
├── user/
├── order/
├── product/
├── payment/
└── dashboard/

每个 feature 内部再保持统一结构。

例如：

features/user/
├── api/
├── components/
├── hooks/
├── pages/
├── types/
└── index.ts

AI Agent 修改用户模块时，只需要重点关注 features/user。

services 目录

用于全局服务。

例如：

http client
auth service
storage service
logger

不要把每个业务 API 都放在 services。

业务 API 应该优先放在对应 feature 内部。

types 目录

存放全局类型。

例如：

User
Pagination
ApiResponse

如果是模块专属类型，应放在 feature 内部。

utils 目录

只放纯工具函数。

例如：

formatDate
formatPrice
debounce
deepClone

不要放业务逻辑。

如果函数依赖业务上下文，就不应该放进 utils。

四、后端项目结构建议

以 Node.js 后端为例。

推荐：

src/
├── config/
├── modules/
├── common/
├── database/
├── middlewares/
├── providers/
├── jobs/
├── scripts/
└── main.ts

核心是 modules。

modules 目录

每个业务模块独立：

modules/
├── user/
├── auth/
├── order/
├── payment/
└── notification/

每个模块内部：

user/
├── user.controller.ts
├── user.service.ts
├── user.repository.ts
├── user.dto.ts
├── user.types.ts
└── user.routes.ts

AI Agent 很容易理解：

controller 处理请求。

service 处理业务。

repository 处理数据库。

dto 处理输入输出。

common 目录

放通用能力：

errors
guards
decorators
helpers
constants

但不要把业务代码塞进去。

common 一旦变成垃圾桶，项目就会逐渐失控。

database 目录

建议包含：

migrations
schema
seed
client

这样 AI 生成数据库相关代码时，更容易找到对应位置。

五、给 AI看的项目说明文件

除了目录本身，还应该给 AI 准备说明文件。

推荐在项目根目录放：

AI_GUIDE.md

内容包括：

项目技术栈
目录说明
命名规范
禁止事项
常见任务流程

示例：

当新增业务模块时：
1. 在 src/features 下创建模块目录
2. API 放入模块 api 目录
3. 类型放入模块 types 目录
4. 页面放入 pages
5. 不允许修改全局组件，除非明确要求

这样的说明能显著减少 AI 误操作。

六、适合 AI Agent 的开发流程

推荐流程：

分析项目
↓
定位模块
↓
制定计划
↓
小步修改
↓
运行测试
↓
人工 Review

不要直接让 AI：

重构整个项目

更好的 Prompt：

请先阅读项目结构，并说明用户模块涉及哪些文件。
不要修改代码。

确认后再说：

现在只修改用户模块，不要影响其他模块。

七、目录结构反模式

以下结构不推荐。

1. common 过度膨胀

很多项目最终变成：

common/
├── user-helper
├── order-utils
├── payment-temp
├── product-common

这说明模块边界已经失控。

2. API 到处都是

如果项目同时有：

api/
request/
service/
http/
fetch/

AI 会很难判断应该用哪个。

3. 临时文件长期存在

例如：

test-new
backup
old
temp
copy

这些目录会误导 AI。

4. 页面和业务逻辑混在一起

页面文件过大，几千行代码。

AI 修改时更容易出错。

建议拆分：

page
components
hooks
api
types

八、AI 时代的项目维护习惯

每次重构后更新说明文档

目录变化后，应同步更新 AI_GUIDE 或 README。

删除废弃代码

不要长期保留不用的目录。

保持命名一致

不要同时出现：

user
users
member
account

除非它们确实代表不同业务。

用测试保护核心逻辑

AI 修改越多，测试越重要。

结语

适合 AI Agent 的项目结构，本质上也是适合人类团队协作的项目结构。

清晰命名、明确边界、模块内聚、文档完善，这些原则并不过时。

只是在 AI 编程时代，它们的重要性被进一步放大。

如果希望 AI 真正成为项目助手，而不是制造混乱的工具，首先要做的不是更换模型，而是让项目本身更容易被理解。