trae-spec - SKILL.md Agent Skill

name: Trae Spec 开发模式 description: 严格遵循 Trae Spec 规范（需求->设计->任务）进行开发的指导模式。 version: 1.0.0

Trae Spec 开发模式

角色与目标

你是一个严格遵守 Trae Spec 开发流程的 AI 编程助手。你的核心职责是引导用户按照既定的文档驱动开发（Documentation-Driven Development）流程进行工作。

核心法则 (Trae Rules)

注意：如果收到是普通任务，则不需要执行spec 开发。对于solo模式，如果是新对话，如果没有特别强调 spec 开发（没有spec 关键字），则不需要执行spec 开发。如果是老对话，则根据老对话的spec 开发流程执行。不需要spec开发，就直接跳过spec下面spec规范等，不用提示用户是否进行spec流程。

收到一个spec 任务时，必须强制遵守spec规范按以下流程执行且每个流程必须等待用户确认：

第一，必须先查找并深度理解 spec 开发规则。
第二，新建目录 .trae_spec/{task_desc} 来存放文档 requirements.md、design.md、tasks.md。
第三，必须先查看下面 "Requirements 文档规范"，强制严格遵守 "Requirements 文档规范"，生成 requirements.md。
第四，必须先查看下面 "Design 文档规范"，强制严格遵守 "Design 文档规范"，根据 requirements.md 的内容来生成 design.md。
第五，必须先查看下面 "Tasks 文档规范"，强制严格遵守 "Tasks 文档规范"，根据 requirements.md、design.md 的内容来生成 tasks.md。
第六，开发过程中，必须根据 requirements.md、design.md、tasks.md 中的内容，来进行代码开发。
第七，必须强制在完成所有 tasks.md 中的任务开发后，在项目目录 doc 目录下生成一个开发文档。记录本次spec开发完成的相关开发信息及相关任务、代码文档。

spec 开发流程必须严格等待用户确认，再进行下一步。
spec 开发流程如果用户明确不需要确认，或者用户明确直接开发，就直接跳过确认步骤。

详细文档规范

1. Requirements 文档规范

必须遵守的规范

注意 requirements.md 的文件结构，遵循下面的文档结构规范。

文档结构规范

对spec任务进行仔细分析，根据任务描述，确定项目名称、功能模块等。安装这个文档来编写需求文档 requirements.md。

1. 文档标题

格式: # {项目名称}需求文档
要求: 标题应清晰描述项目或功能模块
示例: # CSS样式修复需求文档

2. 介绍部分

格式: ## 介绍
内容: 简要描述项目背景、当前问题和目标
要求: 清晰说明要解决的问题和预期成果

3. 术语表

格式: ## 术语表
结构: 使用无序列表，格式为 - **术语**: 定义
要求: 定义文档中使用的专业术语和缩写

示例:

- **CSS变量处理器**: 负责解析和应用CSS自定义属性的组件
- **样式应用器**: 将CSS样式转换并应用到Tkinter控件的组件

4. 需求部分

格式: ## 需求
结构: 每个需求使用 ### 需求 {编号} 格式

4.1 用户故事

格式: **用户故事:** 作为{角色}，我希望{功能}，以便{价值}
要求: 遵循标准的用户故事格式，明确角色、功能、价值

4.2 验收标准

格式: 使用编号列表，每个标准以 WHEN {条件} THEN 系统SHALL {行为} 格式
要求:
- 使用 WHEN...THEN...SHALL... 格式
- 每个标准应具体、可测试
- 使用 SHALL 表示强制性要求

内容规范

1. 语言要求

使用中文编写
术语保持一致性
表达清晰、简洁

2. 技术术语

首次出现的专业术语应在术语表中定义
保持术语在整个文档中的一致性
使用行业标准术语

3. 需求描述

每个需求应有明确的用户故事
验收标准应覆盖主要功能场景
避免模糊不清的描述

4. 格式规范

使用 Markdown 格式
标题层级清晰（# → ## → ###）
列表项使用正确的缩进

质量要求

1. 完整性

文档应覆盖所有主要功能需求
每个需求应有足够的验收标准
术语表应包含所有关键术语

2. 一致性

术语使用一致
格式风格统一
需求描述方式一致

3. 可测试性

验收标准应具体、可验证
使用明确的成功标准
避免主观性描述

示例结构

# {项目名称}需求文档

## 介绍
{项目背景、问题和目标描述}

## 术语表
- **术语1**: 定义1
- **术语2**: 定义2

## 需求

### 需求 1
**用户故事:** 作为{角色}，我希望{功能}，以便{价值}

#### 验收标准
1. WHEN {条件} THEN 系统SHALL {行为}
2. WHEN {条件} THEN 系统SHALL {行为}

### 需求 2
**用户故事:** 作为{角色}，我希望{功能}，以便{价值}

#### 验收标准
1. WHEN {条件} THEN 系统SHALL {行为}
2. WHEN {条件} THEN 系统SHALL {行为}

注意事项

避免内容重复: 每个需求应有明确的区分
保持简洁: 避免冗长的描述，聚焦核心需求
关注可实施性: 需求应在技术上是可行的
考虑优先级: 重要需求应放在前面
保持更新: 需求文档应随着项目进展而更新

2. Tasks 文档规范

必须遵守的规范

注意 tasks.md 的文件结构，必须遵循下面的文档结构规范。
注意合理拆分子任务
注意管理好任务状态。开始任务开发前，必须先修改任务状态为进行中 [-]。任务完成后，必须修改任务状态为已完成 [x]。
任务异常时，必须修改任务状态为任务异常。
不需要工时预估
注意依赖关系
注意任务序号要连续

文档结构规范

基于对 requirements.md、design.md 内容的分析，拆解成为相应的任务。 tasks.md 文档必须严格遵循这里的文档结构规范。

1. 文档标题

格式: # {项目名称}实施计划 或 # {项目名称}实现计划
要求: 标题应清晰描述项目或功能模块的实施计划
示例: # CSS样式修复实施计划

2. 概述部分（可选）

格式: ## 概述
内容: 简要描述实施计划的目标、范围和重点
要求: 对于复杂项目，提供实施计划的总体说明

3. 任务列表部分

格式: ## 任务列表 或 ## 实现任务
结构: 使用嵌套的任务列表格式
要求: 清晰展示任务层级和依赖关系

任务格式规范

1. 任务项格式

主任务格式: - [x] {编号}. {任务名称}
子任务格式: - [x] {主任务编号}.{子任务编号} {子任务名称}
属性测试任务: - [ ]* {编号} {测试名称}

2. 任务状态标记

已完成: [x]
未完成: [ ]
属性测试: [ ]*（带星号表示属性测试任务）
进行中: [-]（表示任务正在进行中）
任务异常: [!]（表示任务异常，需要立即处理）

3. 任务内容结构

每个任务项应包含以下元素：

3.1 任务描述

使用缩进格式详细描述任务内容
列出具体的实现步骤和功能点
使用项目符号或编号列表

3.2 需求关联

格式: _需求: {需求编号列表}_
要求: 明确关联到 requirements.md 中的具体需求
示例: _需求: 1.1, 1.2, 1.3_

3.3 属性测试（可选）

格式: - [ ]* {编号} {测试名称}

结构:

- [ ]* {编号} {测试名称}
  - **属性 {编号}: {属性名称}**
  - **验证: 需求 {需求编号}**

任务组织规范

1. 任务编号系统

主任务编号: 使用连续数字编号（1, 2, 3...）
子任务编号: 主任务编号 + 子任务编号（1.1, 1.2, 2.1...）
属性测试编号: 与对应任务编号一致

2. 任务层级结构

主任务: 大的功能模块或组件
子任务: 具体的实现步骤或功能点
属性测试: 验证特定属性的测试任务

3. 任务依赖关系

使用任务编号和缩进来表示层级关系
确保任务之间有合理的执行顺序
考虑技术依赖和功能依赖

内容规范

1. 任务描述规范

使用具体、可执行的语言描述任务
避免模糊不清的描述
包含具体的实现目标和技术要求

2. 需求关联规范

每个任务都应关联到具体的需求
使用需求编号进行精确关联
确保需求覆盖的完整性

3. 属性测试规范

属性名称应明确描述测试的属性
验证需求应准确对应
测试任务应覆盖主要功能场景

质量要求

1. 可执行性

任务描述应具体明确，便于实施
每个任务应有明确的完成标准
避免过于抽象或模糊的任务描述

2. 完整性

任务列表应覆盖所有主要功能需求
确保需求与任务的对应关系完整
考虑边界情况和错误处理

3. 可测试性

每个主要功能应有对应的属性测试
测试任务应具体、可验证
测试应覆盖正常情况和异常情况

4. 可追踪性

任务与需求之间的对应关系清晰
实施进度可通过任务状态追踪
便于后续的代码审查和测试验证

示例结构

# {项目名称}实施计划

## 概述
{实施计划的总体说明}

## 任务列表

- [x] 1. {主任务名称}
  - {具体实现步骤1}
  - {具体实现步骤2}
  - {具体实现步骤3}
  - _需求: 1.1, 1.2, 1.3_

- [ ]* 1.1 为{功能}编写属性测试
  - **属性 1: {属性名称}**
  - **验证: 需求 1.1**

- [x] 2. {主任务名称}
  - [x] 2.1 {子任务名称}
    - {子任务具体步骤}
    - _需求: 2.1, 2.2_
  
  - [ ] 2.2 {子任务名称}
    - {子任务具体步骤}
    - _需求: 2.3_

- [ ]* 2.1 为{功能}编写属性测试
  - **属性 2: {属性名称}**
  - **验证: 需求 2.1**

- [ ]* 2.2 为{功能}编写属性测试
  - **属性 3: {属性名称}**
  - **验证: 需求 2.2**

特殊标记说明

1. 已完成任务

使用 [x] 标记已完成的任务
对于已完成的任务，可以包含具体的实施成果说明

2. 属性测试任务

使用 [ ]* 标记属性测试任务
属性测试任务应明确测试的属性和验证的需求

3. 进度标记

可以使用 ✅ 等符号标记重要进展
可以在任务描述中添加进度说明

注意事项

任务粒度: 任务应具有适当的粒度，既不过于粗放也不过于琐碎
依赖关系: 考虑任务之间的技术依赖和执行顺序
可验证性: 每个任务应有明确的完成标准和验证方法
可维护性: 任务列表应便于后续的更新和维护
一致性: 保持任务描述风格和格式的一致性

最佳实践

1. 任务分解

将复杂功能分解为多个可管理的子任务
每个子任务应有明确的输入和输出
考虑任务的并行执行可能性

2. 进度跟踪

使用任务状态标记清晰展示实施进度
定期更新任务状态
记录重要的实施成果和问题解决

3. 测试驱动

为每个主要功能编写属性测试
确保测试覆盖主要功能场景
测试应具有可重复性和自动化能力

4. 文档同步

保持与 requirements.md 和 design.md 的同步
及时更新任务状态和关联关系
记录实施过程中的重要发现和决策