name: track-management description: 轨迹管理方法 - 通过规范、规划和实施阶段创建和管理逻辑工作单元（功能、错误、重构）。 version: 1.0 model: sonnet invoked_by: 两者 tools:

Read
Write
Edit
Bash
Glob
Grep verified: false lastVerifiedAt: 2026-02-19T05:29:09.098Z

轨迹管理

指南用于创建、管理和完成轨迹 - 通过规范、规划和实施阶段组织功能、错误和重构的逻辑工作单元。

何时使用此技能

创建新的功能、错误或重构轨迹
编写或审查 spec.md 文件
创建或更新 plan.md 文件
管理从创建到完成的轨迹生命周期
理解轨迹状态标记和约定
处理 tracks.md 注册表
解释或更新轨迹元数据

轨迹概念

轨迹是一个逻辑工作单元，封装了完整的工作块。每个轨迹有：

一个唯一标识符
一个定义要求的规范
一个将工作分解为任务的阶段计划
跟踪状态和进度的元数据

轨迹为工作提供了语义组织，使得：

清晰的范畴边界
进度跟踪
Git感知操作（按轨迹回滚）
团队协调

轨迹类型

feature

新功能或能力。用于：

新用户面向的功能
新API端点
新集成
重大增强

bug

缺陷修复。用于：

错误行为
错误条件
性能回归
安全漏洞

chore

维护和内务。用于：

依赖更新
配置更改
文档更新
清理任务

refactor

代码改进而无行为改变。用于：

代码重构
模式采用
技术债务减少
性能优化（相同行为，更好性能）

轨迹ID格式

轨迹ID遵循模式：{shortname}_{YYYYMMDD}

shortname: 2-4词 kebab-case 描述（例如：user-auth, api-rate-limit）
YYYYMMDD: 创建日期，ISO格式

示例：

user-auth_20250115
fix-login-error_20250115
upgrade-deps_20250115
refactor-api-client_20250115

轨迹生命周期

1. 创建 (newTrack)

定义要求

通过交互式问答收集要求
识别接受标准
确定范畴边界
识别依赖

生成规范

创建 spec.md 带有结构化要求
文档化功能性和非功能性要求
定义接受标准
列出依赖和约束

生成计划

创建 plan.md 带有阶段任务分解
将任务组织到逻辑阶段
添加阶段后的验证任务
估计努力和复杂度

注册轨迹

添加条目到 tracks.md 注册表
创建轨迹目录结构
生成 metadata.json
创建轨迹 index.md

2. 实施

执行任务

从计划中选择下一个待处理任务
标记任务为进行中
实施遵循工作流（TDD）
标记任务完成，包括提交 SHA

更新状态

更新 plan.md 中的任务标记
记录提交 SHA 用于可追溯性
更新阶段进度
更新 tracks.md 中的轨迹状态

验证进度

完成验证任务
等待检查点批准
记录检查点提交

3. 完成

同步文档

如果添加了功能，更新 product.md
如果依赖改变，更新 tech-stack.md
验证所有接受标准已满足

归档或删除

在 tracks.md 中标记轨迹为已完成
记录完成日期
归档或保留轨迹目录

规范 (spec.md) 结构

# {轨迹标题}

## 概述

简要描述此轨迹实现什么及原因。

## 功能性要求

### FR-1: {要求名称}

功能性要求的描述。

- 接受: 如何验证此要求已满足

### FR-2: {要求名称}

...

## 非功能性要求

### NFR-1: {要求名称}

非功能性要求的描述（性能、安全等）

- 目标: 具体可衡量目标
- 验证: 如何测试

## 接受标准

- [ ] 标准1: 具体、可测试条件
- [ ] 标准2: 具体、可测试条件
- [ ] 标准3: 具体、可测试条件

## 范畴

### 范畴内

- 明确包含的项目
- 要实施的功能
- 要修改的组件

### 范畴外

- 明确排除的项目
- 未来考虑
- 相关但分离的工作

## 依赖

### 内部

- 此轨迹依赖的其他轨迹或组件
- 需要的上下文工件

### 外部

- 第三方服务或API
- 外部依赖

## 风险和缓解

| 风险             | 影响          | 缓解策略          |
| ---------------- | --------------- | ------------------- |
| 风险描述 | 高/中/低 | 缓解策略 |

## 开放问题

- [ ] 需要解决的问题
- [x] 已解决问题 - 答案

计划 (plan.md) 结构

# 实施计划: {轨迹标题}

轨迹ID: `{轨迹-id}`
创建: YYYY-MM-DD
状态: 待处理 | 进行中 | 已完成

## 概述

简要描述实施方法。

## 阶段1: {阶段名称}

### 任务

- [ ] **任务1.1**: 任务描述
  - 子任务或细节
  - 子任务或细节
- [ ] **任务1.2**: 任务描述
- [ ] **任务1.3**: 任务描述

### 验证

- [ ] **验证1.1**: 阶段的验证步骤

## 阶段2: {阶段名称}

### 任务

- [ ] **任务2.1**: 任务描述
- [ ] **任务2.2**: 任务描述

### 验证

- [ ] **验证2.1**: 阶段的验证步骤

## 阶段3: 最终化

### 任务

- [ ] **任务3.1**: 更新文档
- [ ] **任务3.2**: 最终集成测试

### 验证

- [ ] **验证3.1**: 所有接受标准已满足

## 检查点

| 阶段   | 检查点 SHA | 日期 | 状态  |
| ------- | -------------- | ---- | ------- |
| 阶段1 |                |      | 待处理 |
| 阶段2 |                |      | 待处理 |
| 阶段3 |                |      | 待处理 |

状态标记约定

在 plan.md 中使用一致标记：

标记	含义	使用
`[ ]`	待处理	任务未开始
`[~]`	进行中	当前正在工作
`[x]`	完成	任务完成（包括SHA）
`[-]`	跳过	故意不做
`[!]`	阻塞	等待依赖

示例：

- [x] **任务1.1**: 设置数据库架构 `abc1234`
- [~] **任务1.2**: 实施用户模型
- [ ] **任务1.3**: 添加验证逻辑
- [!] **任务1.4**: 集成认证服务（阻塞: 等待API密钥）
- [-] **任务1.5**: 遗留迁移（跳过: 不需要）

轨迹注册表 (tracks.md) 格式

# 轨迹注册表

## 活动轨迹

| 轨迹ID                                                         | 类型    | 状态      | 阶段 | 开始    | 分配者   |
| ---------------------------------------------------------------- | ------- | ----------- | ----- | ---------- | ---------- |
| [user-auth_20250115](.claude/context/tracks/user-auth_20250115/) | feature | 进行中 | 2/3   | 2025-01-15 | @developer |
| [fix-login_20250114](.claude/context/tracks/fix-login_20250114/) | bug     | 待处理     | 0/2   | 2025-01-14 | -          |

## 完成轨迹

| 轨迹ID                                                       | 类型  | 完成  | 持续时间 |
| -------------------------------------------------------------- | ----- | ---------- | -------- |
| [setup-ci_20250110](.claude/context/tracks/setup-ci_20250110/) | chore | 2025-01-12 | 2天   |

## 归档轨迹

| 轨迹ID                                                             | 原因     | 归档   |
| -------------------------------------------------------------------- | ---------- | ---------- |
| [old-feature_20241201](.claude/context/tracks/old-feature_20241201/) | 被取代 | 2025-01-05 |

元数据 (metadata.json) 字段

{
  "id": "user-auth_20250115",
  "title": "用户认证系统",
  "type": "feature",
  "status": "in-progress",
  "priority": "high",
  "created": "2025-01-15T10:30:00Z",
  "updated": "2025-01-15T14:45:00Z",
  "started": "2025-01-15T11:00:00Z",
  "completed": null,
  "assignee": "@developer",
  "phases": {
    "total": 3,
    "current": 2,
    "completed": 1
  },
  "tasks": {
    "total": 12,
    "completed": 5,
    "in_progress": 1,
    "pending": 6
  },
  "checkpoints": [
    {
      "phase": 1,
      "sha": "abc1234",
      "date": "2025-01-15T13:00:00Z"
    }
  ],
  "dependencies": [],
  "tags": ["auth", "security"]
}

轨迹大小指南

适当大小轨迹

目标为轨迹：

在1-5天工作中完成
有2-4个阶段
包含8-20个任务总计
交付连贯、可测试单元

太大

轨迹太大的迹象：

超过5个阶段
超过25个任务
多个无关功能
估计持续时间 > 1周

解决方案: 拆分为多个轨迹，有清晰边界。

太小

轨迹太小的迹象：

单阶段，1-2个任务
不需要有意义验证
可能是另一轨迹的子任务
工作少于几小时

解决方案: 与相关工作合并或作为现有轨迹部分处理。

常见轨迹模式

功能轨迹模式

阶段1: 基础
- 数据模型
- 数据库迁移
- 基础API结构

阶段2: 核心逻辑
- 业务逻辑实施
- 输入验证
- 错误处理

阶段3: 集成
- UI集成
- API文档
- 端到端测试

错误修复轨迹模式

阶段1: 重现
- 写捕获错误的失败测试
- 文档重现步骤

阶段2: 修复
- 实施修复
- 验证测试通过
- 检查回归

阶段3: 验证
- 手动验证
- 如果需要，更新文档

重构轨迹模式

阶段1: 准备
- 添加特征测试
- 文档当前行为

阶段2: 重构
- 增量应用更改
- 保持绿色测试

阶段3: 清理
- 移除死代码
- 更新文档

最佳实践

一轨迹，一关注: 保持轨迹专注于单一逻辑更改
小阶段: 将工作分解为最多3-5个任务的阶段
阶段后验证: 始终包括验证任务
立即更新标记: 工作时立即标记任务状态
记录SHAs: 始终记录完成任务的提交SHAs
规划前审查规范: 创建计划前确保规范完整
链接依赖: 明确注意轨迹依赖
归档，不删除: 保留完成轨迹以供参考
大小适当: 保持轨迹在1-5天工作中
清晰接受标准: 每个要求必须可测试

内存协议（强制）

开始前：

cat .claude/context/memory/learnings.md

完成后：

新模式 -> .claude/context/memory/learnings.md
发现问题 -> .claude/context/memory/issues.md
做出决定 -> .claude/context/memory/decisions.md

假设中断: 如果不在内存中，就没发生。