31 · 多文件协作实战

┌─────────────┐
│  User Story  │  ← 你告诉 Agent 要做什么
└──────┬──────┘
       ↓
┌──────────────────┐
│  Route Handler   │  ← Agent 先找到入口文件
└──────┬───────────┘
       ↓
┌──────────────────┐     ┌──────────────────┐
│  Controller/Service│ ← → │  Types/Interfaces │
└──────┬───────────┘     └──────────────────┘
       ↓
┌──────────────────┐     ┌──────────────────┐
│  Data Access Layer│ ← → │   DTO / Schema   │
└──────┬───────────┘     └──────────────────┘
       ↓
┌──────────────────┐
│  Utils / Helpers  │
└──────────────────┘

❌ "帮我给 User 模型加上 scoreHistory 字段"
❌ "帮我创建 getScoreHistory 的 tRPC router"
❌ "帮我写一个显示积分历史的 React 组件"

✅ "给用户添加积分历史功能：用户完成挑战后增加积分，
   积分变动需要记录时间、类型、变动值，前端用户页
   显示最近 20 条记录。使用项目现有技术栈。"

// app/api/posts/route.ts
const token = req.headers.get('authorization')?.replace('Bearer ', '');
if (!token) return NextResponse.json({ error: '未授权' }, { status: 401 });
const user = await verifyToken(token);
if (!user) return NextResponse.json({ error: '令牌无效' }, { status: 401 });
 
// app/api/comments/route.ts
const token = req.headers.get('authorization')?.replace('Bearer ', '');
if (!token) return NextResponse.json({ error: '未授权' }, { status: 401 });
const user = await verifyToken(token);
if (!user) return NextResponse.json({ error: '令牌无效' }, { status: 401 });

"检查项目中 API route 文件，找出重复的认证逻辑，
并给出提取为公共中间件的方案。"

"在 lib/auth.ts 中创建 withAuth 高阶函数，
封装认证逻辑，返回 user 对象给 handler 使用。
然后自动更新所有 API route 文件。"

"分析项目中对 /api/v1/old-posts 的所有引用，
包括后端路由定义、前端 API 调用、类型定义、
Mock 数据和测试文件。输出完整的文件列表。"

"执行以下变更：
1. 将 routes/oldPosts.ts 重命名并修改为 routes/articles.ts，路由路径改为 /api/v1/articles
2. 字段重命名：title → name，content → body
3. 更新前端 app/api.ts 中对应的 API 调用
4. 更新 types/post.ts 中的类型定义
5. 更新所有测试文件
6. 更新 Mock 数据文件
不要遗漏任何引用。"

□ 后端路由文件（重命名 + 路径修改）
□ 后端控制器/服务层（字段映射）
□ 前端 API 调用层（URL 更新）
□ 前端类型定义（接口字段更新）
□ 前端组件（props 引用更新）
□ API 文档 / OpenAPI spec
□ Mock 数据文件
□ 集成测试 / E2E 测试
□ 数据库查询（如果字段映射到底层数据）

旧结构（按类型）              新结构（按功能）
src/                         src/
├── components/              ├── auth/
│   ├── LoginForm.tsx        │   ├── components/LoginForm.tsx
│   └── UserProfile.tsx      │   ├── api/login.ts
├── pages/                   │   └── hooks/useAuth.ts
│   ├── login.tsx            ├── articles/
│   └── profile.tsx          │   ├── components/ArticleList.tsx
├── hooks/                   │   ├── api/articles.ts
│   ├── useAuth.ts           │   └── types.ts
│   └── useArticles.ts       └── common/
└── api/                         ├── components/Button.tsx
    ├── login.ts               └── utils/format.ts
    └── articles.ts

"分析当前 src 目录下的文件依赖关系，
输出一份依赖图，识别耦合度高的模块组，
为按功能重组提供建议。"

"按照以下映射进行目录重组：
- 将 components/LoginForm.tsx → auth/components/
- 将 pages/login.tsx → auth/pages/
- 将 hooks/useAuth.ts → auth/hooks/
- 将 api/login.ts → auth/api/
- 将 components/ArticleList.tsx → articles/components/
- 将 api/articles.ts → articles/api/
- 将 hooks/useArticles.ts → articles/hooks/
- 将 components/Button.tsx → common/components/
- 将 utils/format.ts → common/utils/

移动后更新所有文件的 import 路径。移动完成后
检查是否有断开的引用。"

npm run typecheck
npm run test

Agent 负责：                                  人工负责：
┌─────────────────────────┐   ┌─────────────────────────┐
│  语法正确的代码生成     │   │  业务逻辑正确性判断     │
│  类型一致性检查         │   │  架构合理性评估         │
│  import 路径自动更新    │   │  安全/权限审查          │
│  重复模式检测与提取     │   │  性能影响评估           │
│  批量文件修改           │   │  数据库迁移安全         │
│  测试文件同步更新       │   │  API 兼容性（版本）     │
└─────────────────────────┘   └─────────────────────────┘

Ctrl+Shift+Enter  →  Composer Review 模式
→ 上下箭头遍历每个文件
→ 关注：文件数量是否合理、修改范围是否过大

npm run typecheck 或 tsc --noEmit

npm run test -- --related     # 只运行相关文件的测试
npm run test:integration       # 如果影响集成逻辑

□ 所有需要修改的文件是否都已经被覆盖？（对照依赖链检查）
□ 新提取的公共函数/组件是否有合适的命名和位置？
□ 废弃的旧文件是否有清理？（避免遗留死代码）
□ 日志和错误信息是否与实际代码一致？
□ 数据库迁移是否向下兼容？（如果涉及 Schema 变更）
□ 前端组件是否处理了加载态、空态、错误态？

□ 本地运行项目，手动走一遍功能流程
□ 检查浏览器控制台有无报错
□ 检查网络请求的 payload 和 response 是否正确
□ 检查边界情况（空数据、异常数据、权限不足）

// 多文件变更 Review Checklist
const reviewChecklist = {
  completeness: {
    allFilesModified: true,   // 所有需要改的文件都改了？
    noDeadCode: true,         // 旧代码/文件清理了？
    importsUpdated: true,     // import 路径都对了？
  },
  consistency: {
    typesMatch: true,         // 前后端类型一致？
    namingConsistent: true,   // 命名风格统一？
    apiContractMatch: true,   // API 契约（请求/响应）一致？
  },
  quality: {
    errorHandling: true,      // 异常处理完整？
    loadingStates: true,      // 加载状态覆盖？
    testCoverage: true,       // 测试同步更新？
    migrationSafe: true,      // Schema 变更向下兼容？
  },
};

用户需求
   ↓
路由层（Route / API endpoint）
   ↓
服务层（Service / Use Case）
   ↓
数据层（Model / Repository）
   ↓
数据库（Schema / Migration）

散落在各处的重复代码
   ↓
识别公共模式（Agent 分析）
   ↓
创建共享模块
   ↓
更新所有引用方
   ↓
清理冗余代码

模型层变更           ← 出发点
   ↓
服务层适配           ← 自动传播
   ↓
API 层适配           ← 自动传播
   ↓
前端 API 调用层      ← 自动传播
   ↓
前端组件层           ← 可能需要人工调整展示逻辑

阶段 1: 扩展（Expand）
  旧字段和新字段同时存在，双写
阶段 2: 迁移（Migrate）
  所有消费方逐步迁移到新字段
阶段 3: 收缩（Contract）
  移除旧字段，完成变更

阶段 1: 基础设施（模型、类型、工具函数） → 提交
阶段 2: 核心逻辑（服务层、API）          → 提交
阶段 3: UI 层（组件、页面）              → 提交
阶段 4: 测试与清理                      → 提交

# 在让 Agent 做大规模变更前：
git add . && git commit -m "wip: before multi-file refactor"

# 每个阶段完成后：
git add . && git commit -m "阶段 1: 模型和类型定义"

# .cursorignore
node_modules/
dist/
.next/
*.log
generated/

"不要立即执行。先分析项目结构，输出完整的变更计划，
包含所有需要修改的文件列表、每个文件的改动要点、
以及变更顺序。等我确认后再执行。"

📋 变更计划

影响文件（共 8 个）：
1. lib/auth.ts            → 新建：withAuth 中间件
2. app/api/posts/route.ts → 修改：替换内联认证为 withAuth
3. app/api/comments/route.ts → 修改：替换内联认证为 withAuth
4. app/api/users/route.ts → 修改：替换内联认证为 withAuth
5. app/api/categories/route.ts → 修改：替换内联认证为 withAuth
6. types/auth.ts          → 修改：导出 AuthenticatedRequest 类型
7. tests/api/posts.test.ts → 修改：适配新的认证方式
8. tests/api/comments.test.ts → 修改：适配新的认证方式

变更顺序：
1 → 6 → 2-5（并行可安全执行）→ 7-8

无需修改的文件：...

Cmd+K → "将 handleCreate 函数中的 res.status(201) 改为 res.status(200)"