track-management

轨道管理

创建、管理和完成轨道的指南。轨道是逻辑工作单元，用于在规范、规划和实施阶段组织功能、缺陷和重构工作。

何时使用此技能

• 创建新的功能、缺陷或重构轨道
• 编写或审查 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）

定义需求

1. 通过交互式问答收集需求
2. 确定验收标准
3. 确定范围边界
4. 确定依赖项

生成规范

1. 创建包含结构化需求的 spec.md
2. 记录功能性和非功能性需求
3. 定义验收标准
4. 列出依赖项和约束

生成计划

1. 创建包含分阶段任务拆分的 plan.md
2. 将任务组织成逻辑阶段
3. 在各阶段后添加验证任务
4. 估算工作量和复杂度

注册轨道

1. 在 tracks.md 注册表中添加条目
2. 创建轨道目录结构
3. 生成 metadata.json
4. 创建轨道 index.md

2. 实施

执行任务

1. 从计划中选择下一个待处理任务
2. 将任务标记为进行中
3. 按照工作流（TDD）实施
4. 完成任务并记录提交 SHA

更新状态

1. 更新 plan.md 中的任务标记
2. 记录提交 SHA，以便追溯
3. 更新阶段进度
4. 更新 tracks.md 中的轨道状态

验证进度

1. 完成验证任务
2. 等待检查点审批
3. 记录检查点提交

3. 完成

同步文档

1. 如果添加了功能，则更新 product.md
2. 如果更改了依赖项，则更新 tech-stack.md
3. 验证是否满足所有验收标准

归档或删除

1. 在 tracks.md 中将轨道标记为已完成
2. 记录完成日期
3. 归档或保留轨道目录

规范（spec.md）结构

# {Track Title}

## Overview

Brief description of what this track accomplishes and why.

## Functional Requirements

### FR-1: {Requirement Name}

Description of the functional requirement.

- Acceptance: How to verify this requirement is met

### FR-2: {Requirement Name}

...

## Non-Functional Requirements

### NFR-1: {Requirement Name}

Description of the non-functional requirement (performance, security, etc.)

- Target: Specific measurable target
- Verification: How to test

## Acceptance Criteria

- [ ] Criterion 1: Specific, testable condition
- [ ] Criterion 2: Specific, testable condition
- [ ] Criterion 3: Specific, testable condition

## Scope

### In Scope

- Explicitly included items
- Features to implement
- Components to modify

### Out of Scope

- Explicitly excluded items
- Future considerations
- Related but separate work

## Dependencies

### Internal

- Other tracks or components this depends on
- Required context artifacts

### External

- Third-party services or APIs
- External dependencies

## Risks and Mitigations

| Risk             | Impact          | Mitigation          |
| ---------------- | --------------- | ------------------- |
| Risk description | High/Medium/Low | Mitigation strategy |

## Open Questions

- [ ] Question that needs resolution
- [x] Resolved question - Answer

计划（plan.md）结构

# Implementation Plan: {Track Title}

Track ID: `{track-id}`
Created: YYYY-MM-DD
Status: pending | in-progress | completed

## Overview

Brief description of implementation approach.

## Phase 1: {Phase Name}

### Tasks

- [ ] **Task 1.1**: Task description
  - Sub-task or detail
  - Sub-task or detail
- [ ] **Task 1.2**: Task description
- [ ] **Task 1.3**: Task description

### Verification

- [ ] **Verify 1.1**: Verification step for phase

## Phase 2: {Phase Name}

### Tasks

- [ ] **Task 2.1**: Task description
- [ ] **Task 2.2**: Task description

### Verification

- [ ] **Verify 2.1**: Verification step for phase

## Phase 3: Finalization

### Tasks

- [ ] **Task 3.1**: Update documentation
- [ ] **Task 3.2**: Final integration test

### Verification

- [ ] **Verify 3.1**: All acceptance criteria met

## Checkpoints

| Phase   | Checkpoint SHA | Date | Status  |
| ------- | -------------- | ---- | ------- |
| Phase 1 |                |      | pending |
| Phase 2 |                |      | pending |
| Phase 3 |                |      | pending |

状态标记约定

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

标记	含义	用途
[ ]	待处理	任务尚未开始
[~]	进行中	当前正在处理
[x]	已完成	任务已完成（包含 SHA）
[-]	已跳过	有意不执行
[!]	已阻塞	等待依赖项

示例：

- [x] **Task 1.1**: Set up database schema `abc1234`
- [~] **Task 1.2**: Implement user model
- [ ] **Task 1.3**: Add validation logic
- [!] **Task 1.4**: Integrate auth service (blocked: waiting for API key)
- [-] **Task 1.5**: Legacy migration (skipped: not needed)

Track Registry (tracks.md) 格式

# Track Registry

## Active Tracks

| Track ID                                                         | Type    | Status      | Phase | Started    | Assignee   |
| ---------------------------------------------------------------- | ------- | ----------- | ----- | ---------- | ---------- |
| [user-auth_20250115](.claude/context/tracks/user-auth_20250115/) | feature | in-progress | 2/3   | 2025-01-15 | @developer |
| [fix-login_20250114](.claude/context/tracks/fix-login_20250114/) | bug     | pending     | 0/2   | 2025-01-14 | -          |

## Completed Tracks

| Track ID                                                       | Type  | Completed  | Duration |
| -------------------------------------------------------------- | ----- | ---------- | -------- |
| [setup-ci_20250110](.claude/context/tracks/setup-ci_20250110/) | chore | 2025-01-12 | 2 days   |

## Archived Tracks

| Track ID                                                             | Reason     | Archived   |
| -------------------------------------------------------------------- | ---------- | ---------- |
| [old-feature_20241201](.claude/context/tracks/old-feature_20241201/) | Superseded | 2025-01-05 |

Metadata (metadata.json) 字段

{
  "id": "user-auth_20250115",
  "title": "User Authentication System",
  "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"]
}

Track 规模指南

规模合适的 Track

目标是让 Track：

• 在 1-5 天的工作时间内完成
• 包含 2-4 个阶段
• 总计包含 8-20 个任务
• 交付一个连贯且可测试的单元

规模过大

Track 规模过大的迹象：

• 超过 5 个阶段
• 超过 25 个任务
• 包含多个不相关的功能
• 预计耗时 > 1 周

解决方案：将其拆分为多个边界清晰的 Track。

规模过小

Track 规模过小的迹象：

• 只有一个阶段，且仅包含 1-2 个任务
• 无需进行有意义的验证
• 可以作为其他 Track 的子任务
• 工作时间少于几小时

解决方案：与相关工作合并，或作为现有 Track 的一部分处理。

常见 Track 模式

功能 Track 模式

Phase 1: Foundation
- Data models
- Database migrations
- Basic API structure

Phase 2: Core Logic
- Business logic implementation
- Input validation
- Error handling

Phase 3: Integration
- UI integration
- API documentation
- End-to-end tests

Bug 修复 Track 模式

Phase 1: Reproduction
- Write failing test capturing bug
- Document reproduction steps

Phase 2: Fix
- Implement fix
- Verify test passes
- Check for regressions

Phase 3: Verification
- Manual verification
- Update documentation if needed

重构 Track 模式

Phase 1: Preparation
- Add characterization tests
- Document current behavior

Phase 2: Refactoring
- Apply changes incrementally
- Maintain green tests throughout

Phase 3: Cleanup
- Remove dead code
- Update documentation

最佳实践

1. 一个 Track，一个关注点：让 Track 专注于单一的逻辑变更
2. 阶段要小：每个阶段最多拆分为 3-5 个任务
3. 阶段完成后进行验证：始终包含验证任务
4. 立即更新标记：工作时及时标记任务状态
5. 记录 SHA：始终记录已完成任务的提交 SHA
6. 规划前审查规格：创建计划前确保规格完整
7. 关联依赖项：明确注明 Track 之间的依赖关系
8. 归档，不要删除：保留已完成的 Track 以供参考
9. 规模适当：让 Track 的工作量保持在 1-5 天
10. 验收标准明确：每项要求都必须可测试

铁律

1. 始终先创建 Track 目录和 spec.md，再编写任何实现代码
2. 绝不在没有已提交的 plan.md（包含任务拆分和依赖关系）的情况下开始实现
3. 始终在每个工作时段结束时，将会话进度记录到 progress.md
4. 绝不在没有证明工作已提交的提交 SHA 时，将任务标记为 [x] 已完成
5. 始终将受阻任务移至 [!]，并注明阻塞原因，而不是让其保持进行中状态

反模式

反模式	失败原因	正确做法
未编写 spec.md 就开始实现	要求未定义，范围不断扩大	先编写 spec.md；完成前阻止实现
任务完成后未更新 plan.md	过时的计划会误导后续会话	随着工作推进实时更新任务状态
会话之间没有 progress.md 记录	恢复工作时丢失上下文，导致重复劳动	停止前将会话日志追加到 progress.md
未提供提交 SHA 就标记 [x]	无法追溯；无法验证完成了哪些工作	为每个已完成任务记录提交 SHA
忽略受阻任务	未解决的阻塞会使 Track 偏离计划	立即升级处理 [!] 阻塞项；不要跳过

记忆协议（强制）

开始前：

cat .claude/context/memory/learnings.md

完成后：

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

假设工作会被中断：如果没有记录在记忆中，就等于没发生。