大型项目架构¶

在 10 万行以上的代码库中应用 Vibe Coding，需要系统性的架构策略。

核心挑战¶

大型项目的 Vibe Coding 面临三个核心挑战：

上下文爆炸：相关代码分散在数十个文件中
一致性维护：AI 生成的代码需要与现有架构保持一致
影响面评估：一个改动可能影响多个模块

架构分层策略¶

建立清晰的模块边界¶

src/
├── core/          # 核心业务逻辑（最稳定，最少改动）
├── features/      # 功能模块（按业务域划分）
│   ├── auth/
│   ├── orders/
│   └── products/
├── shared/        # 跨模块共享（工具函数、类型定义）
├── infrastructure/ # 基础设施（数据库、缓存、消息队列）
└── api/           # API 层（路由、中间件）

Vibe Coding 原则：每次任务只在一个模块内工作，跨模块改动需要拆分为多个任务。

接口优先设计¶

在让 AI 实现之前，先定义模块接口：

// 先定义接口（人工设计）
interface OrderRepository {
  findById(id: string): Promise<Order | null>
  findByUserId(userId: string, page: Page): Promise<PageResult<Order>>
  create(data: CreateOrderData): Promise<Order>
  updateStatus(id: string, status: OrderStatus): Promise<Order>
}

// 再让 AI 实现（基于接口）
// 任务：实现 PostgresOrderRepository，满足 OrderRepository 接口
// 约束：使用 Prisma ORM，不改动接口定义

代码库知识管理¶

架构决策记录（ADR）¶

为每个重要的架构决策创建 ADR 文件，让 AI 理解"为什么这样设计"：

# ADR-001: 使用 Repository 模式隔离数据访问

## 状态：已采纳

## 背景
直接在 Service 层调用 ORM 导致测试困难，且数据库实现细节泄漏到业务层。

## 决策
所有数据访问通过 Repository 接口进行，Service 层只依赖接口。

## 影响
- 新增数据访问功能必须通过 Repository 接口
- 不允许在 Service 层直接使用 Prisma Client

项目规则文件¶

把架构约定（模块依赖规则、禁止事项）写入项目规则文件，让 AI 每次自动遵守。规则文件的格式和团队维护规范详见团队协作规范。

重构策略¶

渐进式重构¶

不要一次性重构整个模块，采用"绞杀者模式"：

graph LR
    A[旧实现] --> B[新接口包装层]
    B --> C[新实现（逐步迁移）]
    B --> A

创建新接口，让旧实现满足该接口
逐步把调用方迁移到新接口
当所有调用方迁移完成，删除旧实现

AI 辅助重构的安全边界¶

安全的 AI 重构任务：
- 提取重复代码到工具函数
- 把大函数拆分为小函数
- 添加类型注解
- 统一错误处理模式

需要人工主导的重构：
- 改变模块边界
- 修改核心数据模型
- 改变认证授权逻辑
- 修改公共 API 接口

测试策略¶

大型项目的测试分层：

层次	覆盖目标	AI 辅助程度
单元测试	纯函数、工具函数	高（AI 可以批量生成）
集成测试	Repository、Service	中（需要人工设计场景）
E2E 测试	关键业务路径	低（需要人工定义验收标准）
性能测试	核心接口	中（AI 生成脚本，人工设定指标）