30 · 最佳实践

你的需求是什么？
│
├─ 读代码、问问题、修局部 bug ──────────→ Chat 模式
│
├─ 从零搭项目、快速出原型 ───────────────→ Builder 模式（半自动）
│
├─ 要 AI 独立完成一个完整功能 ──────────→ SOLO 模式（全自动）
│   │
│   ├─ 新项目/新模块 ──────────────────→ SOLO Builder
│   └─ 改已有项目/重构/修复杂 bug ────→ SOLO Coder
│
└─ 不清楚先探索 ─────────────────────→ 用 Chat 问路

Chat（探路）→ Builder（小改）→ SOLO（干大活）

角色 + 技术栈 + 功能清单 + 约束条件 + 输出格式

❌ 差：
"做一个博客网站"
 
✅ 好：
"你是一个资深前端架构师。
技术栈：Next.js 14 + Tailwind CSS + shadcn/ui。
功能：首页文章列表、文章详情页、About 页面。
数据：文章用 MDX 文件存储，放在 /content 目录。
约束：使用 App Router，支持深色模式切换。
输出：只返回关键文件代码，忽略 node_modules 和配置文件。"

## 任务目标
一句话说明要做什么
 
## 技术约束
- 框架版本、包管理器
- 已有代码风格（函数式 / OOP）
- API 命名规范
 
## 功能清单
1. 功能 A
2. 功能 B
3. 功能 C
 
## 边界条件
- 不改动哪些文件
- 不引入哪些依赖
- 不处理哪些边缘情况
 
## 验收标准
- 代码通过 eslint 检查
- 有单元测试覆盖
- 启动后无报错

任务目标：在订单管理页面增加批量导出功能。
 
技术约束：
- Vue 3 + Composition API + TypeScript
- 后端 API 返回格式统一为 { code, data, message }
- 使用 Pinia 管理状态
 
功能清单：
1. 表格左侧加复选框列
2. 顶部加「批量导出」按钮
3. 点击后调 POST /api/orders/export
4. 导出期间按钮显示 loading
5. 完成后下载文件 / 展示错误提示
 
边界条件：
- 不要修改 src/api 目录下的已有请求封装
- 不要新增 npm 依赖
- 默认全选时最多导出 5000 条
 
验收标准：
- 本地 yarn dev 无报错
- 用户只有选中行才能点击导出

前端页面 → 豆包 / Claude Sonnet
后端 API → GLM-5 / GPT-4o
脚本工具 → MiniMax / DeepSeek
遗留代码分析 → Kimi-K2.5 / Gemini 2.5

.trae/rules/
├── general-rules.md            # L0: 通用规则（始终生效）
├── frontend/
│   ├── react-best-practices.md # React 编码规范
│   ├── css-naming.md           # CSS 命名约定
│   └── testing/
│       └── unit-test-rules.md  # 单元测试规范
├── backend/
│   ├── api-design.md           # API 设计规范
│   └── error-handling.md       # 错误处理
└── devops/
    └── ci-rules.md             # CI/CD 规范

---
globs: "*.ts, *.tsx"
---
 
# TypeScript 编码规范
 
## 命名约定
- 组件文件使用 PascalCase：`UserCard.tsx`
- 工具函数文件使用 camelCase：`formatDate.ts`
- 常量使用 UPPER_SNAKE_CASE：`MAX_RETRY_COUNT`
 
## 类型规范
- 禁止使用 `any` 类型，必须定义明确类型
- 接口声明加 `I` 前缀是可选项，团队内保持一致
- 优先使用 `type` 而非 `interface`（联合类型场景）
 
## 代码风格
- 使用 2 空格缩进
- 使用单引号
- 尾部必须加分号
- 函数用 `function` 声明而非箭头函数赋值
 
## 导入顺序
1. 外部库（react, lodash 等）
2. 内部模块（@/components, @/utils）
3. 类型导入（import type）

---
scene: git_message
---
 
- 遵循 Conventional Commits 格式
- 标题不超过 72 字符
- 中文描述变更内容
- 引用 Issue 编号（如果适用）
- 禁止使用「修复bug」「更新代码」等无意义描述

# 改任何东西之前
git add . && git commit -m "chore: save before AI task"
 
# 让 AI 干活...
 
# 审查 AI 改动，满意则保留
git add . && git commit -m "feat: 用户模块 CRUD 实现"
 
# 不满意则一键回退
git checkout .

/commit

feat(order): 增加批量导出功能
- 添加复选框列和批量导出按钮
- 实现 POST /api/orders/export 调用
- 导出期间展示 loading 状态

---
scene: git_message
---
 
- 格式：类型(范围): 简短描述
- 类型：feat / fix / refactor / style / docs / chore / test
- 描述不超过 50 中文字符
- 如果有破坏性变更，在描述末尾加 BREAKING CHANGE

❌ "看看我的项目，帮我改一下"
✅ "参考 src/utils/format.ts 的 formatDate 函数，给 console.ts 的 logWithTime 函数增加时区参数"

把 @file(src/services/user.ts) 的 getUserInfo 改为异步调用，
同时更新 @folder(src/components/user/) 下的所有调用方

"请通读当前项目 src 目录下的所有文件，生成架构图并总结核心模块，包括：
1. 目录结构和模块划分
2. 数据流向
3. 关键技术选型
4. 潜在的坑"

第一次会话：工作一段时间 → 执行 SAVEAGG 保存进度到 UPDATE_PR.md
后续会话：执行 LOADAGG 恢复上下文 → 继续工作 → SAVEAGG

查看历史：LOADAGG LIST
对比差异：LOADAGG DIFF #1 #2

你的主要场景是什么？
│
├─ 学生/轻量使用/中文项目 ──────────→ 国内版（免费版就够）
│   └─ 高峰期排队严重？→ 错峰使用或切 Auto 模式
│
├─ 职业开发/中文为主但需要国际模型 ──→ 国内版 + 自备 API Key
│   └─ 或国际版 Pro（能科学上网则推荐）
│
├─ 必须用 Claude/GPT-4o ────────────→ 国际版 Pro（$10/月）
│   └─ 大量使用 → Ultra $100/月
│
└─ 做 UI 设计稿转代码 ─────────────→ 国际版（国内版不支持）

# docs/team-trae-rules.md（团队共享）
 
## 通用规范（全员导入为 Global Rules）
- TypeScript strict 模式，禁止 any
- 2 空格缩进，单引号，必须加分号
- 组件使用 function 声明而非箭头函数
- API 返回值统一为 { code, data, message }
 
## 安全红线（手动触发规则）
- 禁止 AI 修改 src/auth/ 和 src/payment/ 目录
- 禁止 AI 执行 db:migrate 命令
- 禁止 AI 写入 .env 文件

{
  "scope": "multi-file",
  "allowed_tools": ["file-creator", "api-contract-sync", "test-gen"],
  "blocked_files": ["src/config.ts", "docker-compose.yml"],
  "dependency_rules": [
    "models.py → routes.py → templates/",
    "store.ts → components/"
  ]
}

docs/prompts/
├── frontend-component.md   # 新建组件的标准 Prompt
├── api-crud.md             # CRUD API 标准 Prompt
├── fix-bug.md              # Bug 修复标准 Prompt
└── code-review.md          # Code Review Prompt

# 全局 Skill：对所有项目可用
- 通用的开发范式、工具链使用

# 项目 Skill：仅当前项目
- 项目专属业务知识、技术方案约束

Trae  ↔  MCP Server  ↔  外部工具（Figma、Jira、数据库等）

┌──────────────────────────────────────────────────────────────┐
│                     🎯 模式选型                              │
│   Chat（问答）← → Builder（半自动）← → SOLO（全自动）       │
│   三段式工作流：Chat 探路 → Builder 小改 → SOLO 干大活      │
├──────────────────────────────────────────────────────────────┤
│                     🧠 模型选型                              │
│   豆包→前端 | GLM-5→架构 | MiniMax→后端 | Kimi→读代码      │
│   简单任务用小模型，复杂任务用强模型                          │
├──────────────────────────────────────────────────────────────┤
│                     📐 规则系统                              │
│   .trae/rules/ 三级目录，四种生效模式                        │
│   单一职责、避免冲突、改完开新对话                            │
├──────────────────────────────────────────────────────────────┤
│                     📦 上下文管理                            │
│   精准引用、@file 绑定、新开对话、SAVEAGG 持久化             │
│   上下文质量 = AI 输出质量                                   │
├──────────────────────────────────────────────────────────────┤
│                     🔒 安全与协作                            │
│   先 commit 再 AI → 审查 diff → 人工 CR                     │
│   团队统一 Rules + Prompt 库 + 角色化智能体                  │
├──────────────────────────────────────────────────────────────┤
│                     💰 版本选择                              │
│   90% 的用户用国内免费版就够了                               │
│   需要 Claude/GPT → 国际版 Pro                              │
│   优速通是陷阱，不要买                                       │
└──────────────────────────────────────────────────────────────┘