Trae Skills 生产力宣言：全栈团队协作的标准化之路

在带过几个百人级开发团队之后，我越来越深刻地意识到一个残酷的现实：规范文档写得再漂亮，落地率往不超过 30%。

代码规范挂在 Wiki 上积灰，新人入职培训完就忘，Code Review 时反复纠正同样的问题。更让人头疼的是，当团队开始引入 AI 辅助编程后，AI 生成的代码完全不懂你们的项目约定——它不知道你们用 camelCase 还是 snake_case，不知道 API 响应格式长什么样，更不知道数据库字段必须带 created_at。

AI 很强大，但它缺乏项目上下文，这让它从"神队友"变成了"需要反复教育的实习生"。

Trae 的 Skills 机制，正是为了解决这个痛点而生。它不是简单的 Prompt 模板，而是一套可版本控制、可团队共享、可持续演进的 AI 约束层。把 Skills 理解为"给 AI 装上的专业工具箱"或许还不够准确——它更像是你团队的"活的架构规范"，让 AI 在生成每一行代码时，都自动遵守你们的游戏规则。

---

规范约束层：让 AI 不敢写出一个 any

代码规范的核心矛盾在于：人会偷懒，但 AI 不会——前提是你告诉它规则。

传统的 ESLint、Prettier 只能做静态检查，而 Skills 可以在代码生成阶段就植入约束。来看一个全栈项目的代码规范 Skill 配置：

---
name: code-standards
description: 全栈项目代码规范约束
globs: ["**/*.ts", "**/*.tsx", "**/*.vue", "**/*.java"]
---

# 全栈代码规范

## Instructions

### 命名铁律
| 类型 | 规范 | 正例 | 反例 |
|-----|------|------|
| 组件文件 | PascalCase | UserProfile.vue | userProfile.vue |
| 变量函数 | camelCase | getUserInfo | get_user_info |
| 数据库字段 | snake_case | created_at | createdAt |
| 常量 | UPPER_SNAKE_CASE | MAX_RETRY | maxRetry |

### TypeScript 强约束
- **禁止使用 `any` 类型**，必要时使用 `unknown` 配合类型守卫
- Props 必须定义 interface 并添加 JSDoc 注释
- 函数返回值必须显式声明类型

### 代码体积控制
- 单个组件/类不超过 300 行
- 单个函数不超过 80 行
- 函数参数不超过 5 个，超出请使用对象传参

### 禁止事项
- 禁止提交 console.log 调试代码
- 禁止魔法数字，必须定义为语义化常量
- 禁止超过 3 层的条件嵌套

这份配置的精妙之处在于 globs 字段——它指定了这套规范适用于哪些文件类型。当你在 Trae 中让 AI 生成 .ts 或 .vue 文件时，这些约束会自动生效。

架构建议：很多团队会把前后端规范分开写成两个 Skill，但我更推荐用一个统一的 Skill 覆盖全栈，在内部用章节区分。这样做的好处是强化"一致性"意识——前端的 userId 和后端的 user_id 之间的映射关系，在同一份文档里一目了然。

---

生产效率层：全栈模板让 AI 写出"老员工水平"的代码

规范告诉 AI “不能做什么”，模板则告诉它"应该怎么做"。

一个成熟的组件模板 Skill，应该包含完整的代码结构、注释规范和区块划分。以 Vue3 组件为例：

---
name: vue3-component-template
description: Vue3 组件开发标准模板
globs: ["**/components/**/*.vue", "**/views/**/*.vue"]
---

# Vue3 组件模板

## Instructions

生成 Vue3 组件时，必须遵循以下结构：

### 标准模板
\`\`\`vue
<template>
  <div class="component-name">
    <!-- 组件内容 -->
  </div>
</template>

<script setup lang="ts">
/**
 * @description 组件功能描述
 * @author 开发者
 * @date YYYY-MM-DD
 */

// ==================== 类型定义 ====================
interface Props {
  /** 属性说明 */
  propName: string
}

// ==================== Props & Emits ====================
const props = withDefaults(defineProps<Props>(), {
  propName: ''
})

const emit = defineEmits<{
  (e: 'change', value: string): void
}>()

// ==================== 响应式数据 ====================
const loading = ref(false)

// ==================== 计算属性 ====================
const computedValue = computed(() => props.propName.toUpperCase())

// ==================== 方法定义 ====================
const handleSubmit = () => {
  emit('change', computedValue.value)
}

// ==================== 生命周期 ====================
onMounted(() => {
  // 初始化
})
</script>

<style scoped lang="scss">
.component-name {
  // 样式定义
}
</style>
\`\`\`

### 区块顺序要求
必须按照以下顺序组织代码：类型定义 → Props/Emits → 响应式数据 → 计算属性 → 方法 → 生命周期

后端同样需要模板约束。一个 Spring Boot 风格的 Service 层模板：

---
name: backend-service-template
description: 后端 Service 层开发模板
globs: ["**/service/**/*.java", "**/service/**/*.ts"]
---

# Service 层模板

## Instructions

### 标准结构
\`\`\`typescript
@Injectable()
export class UserService {
  constructor(
    private readonly userRepo: UserRepository,
    private readonly logger: Logger
  ) {}

  /**
   * 创建用户
   * @param dto 创建参数
   * @returns 用户信息
   * @throws BusinessException 业务异常
   */
  async create(dto: CreateUserDTO): Promise<UserVO> {
    // 1. 参数校验
    this.validate(dto)
    
    // 2. 业务逻辑
    const entity = await this.userRepo.save(dto)
    
    // 3. 日志记录
    this.logger.info(\`User created: \${entity.id}\`)
    
    // 4. 结果转换
    return this.toVO(entity)
  }
}
\`\`\`

### 方法注释必须包含
- @description 功能说明
- @param 参数说明
- @returns 返回值说明
- @throws 可能抛出的异常

避坑指南：模板不要写得太死板。我见过有团队把模板精确到每个变量名，结果 AI 生成的代码千篇一律，失去了灵活性。好的模板应该约束结构和规范，但给业务逻辑留出足够的发挥空间。

---

协议共识层：API 与数据库的"强制性契约"

前后端协作最大的坑，往出在接口定义和数据结构上。一个字段命名不一致，就能让联调多花半天。

API 设计规范 Skill 的核心是统一响应格式和错误码体系：

---
name: api-design-standards
description: RESTful API 设计规范
globs: ["**/controller/**", "**/api/**", "**/routes/**"]
---

# API 设计规范

## Instructions

### 统一响应结构
\`\`\`typescript
// 成功响应
{ code: 200, message: "success", data: T, timestamp: number }

// 分页响应
{ code: 200, data: { list: T[], pagination: { current, pageSize, total } } }

// 错误响应
{ code: number, message: string, timestamp: number }
\`\`\`

### URL 设计原则
- 使用名词复数：`/api/v1/users` 而非 `/api/v1/user`
- 使用 kebab-case：`/user-profiles` 而非 `/userProfiles`
- 资源嵌套不超过两层：`/users/:id/orders` 可以，`/users/:id/orders/:oid/items` 不行

### HTTP 方法语义
| 操作 | 方法 | 示例 |
|-----|------|-----|
| 查询 | GET | GET /users/:id |
| 创建 | POST | POST /users |
| 全量更新 | PUT | PUT /users/:id |
| 部分更新 | PATCH | PATCH /users/:id |
| 删除 | DELETE | DELETE /users/:id |

数据库设计规范则要确保字段命名和必备字段的一致性：

---
name: database-standards
description: 数据库设计规范
globs: ["**/entities/**", "**/models/**", "**/*.sql"]
---

# 数据库设计规范

## Instructions

### 必备审计字段
每张业务表必须包含：
\`\`\`sql
id          BIGINT PRIMARY KEY AUTO_INCREMENT COMMENT '主键',
created_at  DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
updated_at  DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
is_deleted  TINYINT NOT NULL DEFAULT 0 COMMENT '软删除标记'
\`\`\`

### 字段类型约定
| 场景 | 类型 | 说明 |
|-----|------|-----|
| 金额 | DECIMAL(18,2) | 禁止 FLOAT |
| 状态枚举 | TINYINT | 配合代码枚举 |
| 长文本 | TEXT | 超过 5000 字符 |

### 索引命名
- 唯一索引：uk_表名_字段名
- 普通索引：idx_表名_字段名
- 联合索引字段按区分度从高到低排列

---

质量与流程层：测试和提交的自动化守护

单元测试规范 Skill 的关键是定义清晰的测试结构和覆盖率要求：

---
name: unit-test-standards
description: 单元测试规范
globs: ["**/*.test.ts", "**/*.spec.ts"]
---

# 单元测试规范

## Instructions

### AAA 模式
\`\`\`typescript
it('should return user when exists', async () => {
  // Arrange - 准备测试数据
  const mockUser = { id: 1, name: 'test' }
  mockRepo.findById.mockResolvedValue(mockUser)

  // Act - 执行被测方法
  const result = await service.getUser(1)

  // Assert - 验证结果
  expect(result).toEqual(mockUser)
})
\`\`\`

### 命名规范
格式：should [预期行为] when [前置条件]
正例：should throw NotFoundError when user not exists

### 覆盖率要求
语句覆盖 ≥ 70%，分支覆盖 ≥ 65%

Git 提交规范 Skill 则确保提交历史的可追溯性：

---
name: git-commit-standards
description: Git 提交信息规范
---

# Git 提交规范

## Instructions

### Commit 格式
\`\`\`
<type>(<scope>): <subject>

<body>

Closes #issue_number
\`\`\`

### Type 枚举
feat-新功能 | fix-修复 | docs-文档 | style-格式 | refactor-重构 | test-测试 | chore-构建

### 分支命名
feature/功能名 | fix/问题描述 | hotfix/紧急修复 | release/v版本号

---

工程化落地：让 Skills 成为团队的"共享资产"

配置写好了，如何让整个团队都能用上？答案是将 .trae 目录纳入版本控制。

推荐的目录结构：

project-root/
├── .trae/
│   └── Skills/
│       ├── code-standards/
│       │   └── SKILL.md
│       ├── vue3-template/
│       │   └── SKILL.md
│       ├── api-standards/
│       │   └── SKILL.md
│       ├── database-standards/
│       │   └── SKILL.md
│       ├── unit-test-standards/
│       │   └── SKILL.md
│       └── git-commit-standards/
│           └── SKILL.md
├── src/
└── package.json

团队协作流程：当有人修改了 Skill 配置，通过 PR 进行 Review，合并后所有人 pull 代码即可同步最新规范。这意味着规范的更新和代码的更新走同一套流程，再也不会出现"规范文档和实际执行两张皮"的情况。

进阶玩法是区分全局 Skills 和项目 Skills。全局 Skills 放在用户目录下，适用于所有项目（比如个人的代码风格偏好）；项目 Skills 放在 .trae 目录下，跟随项目走，适用于团队统一规范。两者可以叠加生效，项目级配置优先级更高。

---

写在最后

回到开头的问题：如何让规范真正落地？

传统方案是"写文档 + 培训 + Code Review"，本质上是在和人性的惰性做斗争。而 Trae Skills 提供了一种新思路：把规范转化为 AI 的硬约束，让 AI 成为规范的执行者。

当团队里的每个人都在用 AI 辅助编程，而 AI 又严格遵守团队规范时，规范的落地率会从 30% 跃升到 90% 以上。更重要的是，AI 不会抱怨、不会偷懒、不会"下次一定改"——它只会忠实地执行你定义的规则。

这不是在用 AI 取代人，而是在用 AI 放大团队的工程化能力。Skills 让 AI 从一个"什么都能干但什么都不懂"的通用工具，变成了"深度理解项目上下文的虚拟团队成员"。

未来的开发团队，或许不再需要反复强调"请遵守代码规范"。因为规范已经内化在 AI 的每一次代码生