项目结构优化

为 AI 优化的项目组织方式，让 AI 读取更少、理解更快

核心理念

文件往小拆

AI 读取代码时有一个重要限制：上下文窗口有限。文件越大，包含的无关信息越多，AI 理解核心逻辑的效率就越低。

方式	AI 读取体验
📄 大文件 (1000+ 行)	AI 需要读取大量无关代码，上下文污染
📁 小文件 (100-300 行)	AI 可以精准读取所需模块，修改精准

原则：一个文件只做一件事，保持在 100-300 行以内。

模块化设计

模块化是 AI 友好架构的基石：

原则	说明	对 AI 的益处
职责单一	只做一件事，做好它	AI 更容易理解和实现
边界清晰	明确的输入输出	减少歧义和副作用
依赖明确	清晰的依赖关系图	AI 能准确处理导入导出

推荐目录结构

前端项目 (React/Next.js)


src/
├── app/                    # 页面路由
├── components/
│   ├── ui/                 # 基础组件
│   └── features/           # 业务组件（按功能拆分子目录）
├── hooks/                  # 自定义 Hooks
├── lib/                    # 工具函数
├── types/                  # 全局类型定义
├── docs/                   # 📚 项目文档
└── prompts/                # 🤖 AI Prompts 管理

后端项目 (Node.js/NestJS)


src/
├── modules/                # 业务模块（每个模块含 controller/service/dto/entity）
├── common/                 # 公共模块（decorators/filters/guards）
├── config/                 # 配置管理
├── docs/                   # 📚 项目文档
└── prompts/                # 🤖 AI Prompts 管理

文件拆分实践

拆分组件


// ❌ 不好：所有逻辑在一个大文件中
// components/UserDashboard.tsx (500+ 行)
 
// ✅ 好：拆分为多个小文件
// components/UserDashboard/
//   ├── index.tsx           # 导出入口
//   ├── UserDashboard.tsx   # 主组件 (~100 行)
//   ├── UserStats.tsx       # 子组件 (~80 行)
//   ├── hooks.ts            # 组件专用 hooks
//   └── types.ts            # 类型定义

拆分服务


// ❌ 不好：一个巨大的 service (800+ 行)
 
// ✅ 好：按职责拆分
// services/user/
//   ├── index.ts                 # 导出入口
//   ├── user-auth.service.ts     # 认证相关
//   ├── user-profile.service.ts  # 档案管理
//   └── user-settings.service.ts # 设置管理

📚 项目文档管理

在项目中维护清晰的文档，能帮助 AI 快速理解项目背景：


docs/
├── README.md             # 项目概述（AI 首先读取）
├── architecture.md       # 系统架构说明
├── api-contracts/        # API 契约文档
├── database/             # ERD 和数据库说明
└── decisions/            # 架构决策记录 (ADR)

文档编写原则

原则	说明
简洁明了	AI 只需知道”是什么”和”为什么”
结构化	使用表格、列表、代码块，便于 AI 解析
保持更新	过时的文档比没有文档更糟糕

🤖 Prompts 管理

将常用的 AI Prompts 作为项目资产管理：


prompts/
├── README.md              # Prompts 使用说明
├── features/              # 功能开发（new-api-endpoint.md 等）
├── refactoring/           # 重构相关
└── templates/             # 通用模板

📖 关于 Prompts 管理的详细内容，将在第四章工作流中深入讲解。

关键原则总结

原则	做法
单一职责	每个文件只负责一个功能模块
文件大小	控制在 100-300 行以内
清晰命名	文件名直接反映其内容
就近原则	相关文件放在同一目录下
文档同行	项目文档和代码一起版本控制

下一步

接下来，我们将探讨数据库 Schema 管理，了解如何让 AI 高效理解你的数据模型。