Back to Details

track-management

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Track Management

Track管理

Guide for creating, managing, and completing tracks - the logical work units that organize features, bugs, and refactors through specification, planning, and implementation phases.
本指南介绍如何创建、管理及完成Track——一种用于统筹功能开发、Bug修复、代码重构等工作的逻辑单元，覆盖需求定义、规划与实施全流程。

When to Use This Skill

何时使用该方法

  • Creating new feature, bug, or refactor tracks
  • Writing or reviewing spec.md files
  • Creating or updating plan.md files
  • Managing track lifecycle from creation to completion
  • Understanding track status markers and conventions
  • Working with the tracks.md registry
  • Interpreting or updating track metadata
  • 创建新的功能、Bug修复或代码重构Track
  • 编写或评审spec.md文件
  • 创建或更新plan.md文件
  • 管理Track从创建到完成的全生命周期
  • 理解Track状态标记与规范
  • 维护tracks.md注册表
  • 解读或更新Track元数据

Track Concept

Track概念

A track is a logical work unit that encapsulates a complete piece of work. Each track has:
  • A unique identifier
  • A specification defining requirements
  • A phased plan breaking work into tasks
  • Metadata tracking status and progress
Tracks provide semantic organization for work, enabling:
  • Clear scope boundaries
  • Progress tracking
  • Git-aware operations (revert by track)
  • Team coordination
Track是封装完整工作内容的逻辑单元，每个Track包含：
  • 唯一标识符
  • 定义需求的规格说明书
  • 拆解为多阶段任务的实施计划
  • 跟踪状态与进度的元数据
Track为工作提供语义化组织，实现：
  • 清晰的范围边界
  • 进度跟踪
  • 支持Git的操作（按Track回滚）
  • 团队协作协同

Track Types

Track类型

feature

feature

New functionality or capabilities. Use for:
  • New user-facing features
  • New API endpoints
  • New integrations
  • Significant enhancements
新增功能或能力，适用于：
  • 面向用户的新功能
  • 新API接口
  • 新集成对接
  • 重要功能增强

bug

bug

Defect fixes. Use for:
  • Incorrect behavior
  • Error conditions
  • Performance regressions
  • Security vulnerabilities
缺陷修复，适用于：
  • 功能异常
  • 错误场景
  • 性能回退
  • 安全漏洞

chore

chore

Maintenance and housekeeping. Use for:
  • Dependency updates
  • Configuration changes
  • Documentation updates
  • Cleanup tasks
日常维护与内务工作，适用于：
  • 依赖更新
  • 配置变更
  • 文档更新
  • 代码清理

refactor

refactor

Code improvement without behavior change. Use for:
  • Code restructuring
  • Pattern adoption
  • Technical debt reduction
  • Performance optimization (same behavior, better performance)
不改变功能的代码优化，适用于：
  • 代码结构调整
  • 设计模式应用
  • 技术债务清理
  • 性能优化（功能不变，仅提升性能）

Track ID Format

Track ID格式

Track IDs follow the pattern: 
{shortname}_{YYYYMMDD}
  • shortname: 2-4 word kebab-case description (e.g., 
    user-auth
    , 
    api-rate-limit
    )
  • YYYYMMDD: Creation date in ISO format
Examples:
  • user-auth_20250115
  • fix-login-error_20250115
  • upgrade-deps_20250115
  • refactor-api-client_20250115
Track ID遵循以下格式：
{shortname}_{YYYYMMDD}
  • shortname：2-4个单词的短横线分隔描述（如
    user-auth
    、
    api-rate-limit
    ）
  • YYYYMMDD：ISO格式的创建日期
示例：
  • user-auth_20250115
  • fix-login-error_20250115
  • upgrade-deps_20250115
  • refactor-api-client_20250115

Track Lifecycle

Track生命周期

1. Creation (newTrack)

1. 创建阶段（newTrack）

Define Requirements
  1. Gather requirements through interactive Q&A
  2. Identify acceptance criteria
  3. Determine scope boundaries
  4. Identify dependencies
Generate Specification
  1. Create 
    spec.md
    with structured requirements
  2. Document functional and non-functional requirements
  3. Define acceptance criteria
  4. List dependencies and constraints
Generate Plan
  1. Create 
    plan.md
    with phased task breakdown
  2. Organize tasks into logical phases
  3. Add verification tasks after phases
  4. Estimate effort and complexity
Register Track
  1. Add entry to 
    tracks.md
    registry
  2. Create track directory structure
  3. Generate 
    metadata.json
  4. Create track 
    index.md
定义需求
  1. 通过互动沟通收集需求
  2. 明确验收标准
  3. 确定范围边界
  4. 识别依赖关系
生成规格说明书
  1. 创建
    spec.md
    文件，结构化记录需求
  2. 文档化功能与非功能需求
  3. 定义验收标准
  4. 列出依赖与约束条件
生成实施计划
  1. 创建
    plan.md
    文件，将工作拆解为多阶段任务
  2. 按逻辑组织任务到不同阶段
  3. 在各阶段后添加验证任务
  4. 评估工作量与复杂度
注册Track
  1. 向
    tracks.md
    注册表添加条目
  2. 创建Track目录结构
  3. 生成
    metadata.json
    文件
  4. 创建Track的
    index.md
    文件

2. Implementation

2. 实施阶段

Execute Tasks
  1. Select next pending task from plan
  2. Mark task as in-progress
  3. Implement following workflow (TDD)
  4. Mark task complete with commit SHA
Update Status
  1. Update task markers in plan.md
  2. Record commit SHAs for traceability
  3. Update phase progress
  4. Update track status in tracks.md
Verify Progress
  1. Complete verification tasks
  2. Wait for checkpoint approval
  3. Record checkpoint commits
执行任务
  1. 从计划中选择下一个待处理任务
  2. 标记任务为进行中
  3. 遵循TDD工作流实施
  4. 标记任务完成并记录提交SHA
更新状态
  1. 更新plan.md中的任务标记
  2. 记录提交SHA以实现可追溯性
  3. 更新阶段进度
  4. 更新tracks.md中的Track状态
验证进度
  1. 完成验证任务
  2. 等待检查点审批
  3. 记录检查点提交

3. Completion

3. 完成阶段

Sync Documentation
  1. Update product.md if features added
  2. Update tech-stack.md if dependencies changed
  3. Verify all acceptance criteria met
Archive or Delete
  1. Mark track as completed in tracks.md
  2. Record completion date
  3. Archive or retain track directory
同步文档
  1. 若新增功能则更新product.md
  2. 若依赖变更则更新tech-stack.md
  3. 验证所有验收标准均已满足
归档或删除
  1. 在tracks.md中标记Track为已完成
  2. 记录完成日期
  3. 归档或保留Track目录

Specification (spec.md) Structure

规格说明书（spec.md）结构

markdown
undefined
markdown
undefined

{Track Title}

{Track标题}

Overview

概述

Brief description of what this track accomplishes and why.
简述本Track的目标与价值。

Functional Requirements

功能需求

FR-1: {Requirement Name}

FR-1: {需求名称}

Description of the functional requirement.
  • Acceptance: How to verify this requirement is met
功能需求描述。
  • 验收标准：如何验证该需求已满足

FR-2: {Requirement Name}

FR-2: {需求名称}

...
...

Non-Functional Requirements

非功能需求

NFR-1: {Requirement Name}

NFR-1: {需求名称}

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
  • 标准1：具体、可测试的条件
  • 标准2：具体、可测试的条件
  • 标准3：具体、可测试的条件

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
  • 依赖的其他Track或组件
  • 所需的上下文工件

External

外部依赖

  • Third-party services or APIs
  • External dependencies
  • 第三方服务或API
  • 外部依赖项

Risks and Mitigations

风险与缓解措施

RiskImpactMitigation
Risk descriptionHigh/Medium/LowMitigation strategy
风险影响程度缓解措施
风险描述高/中/低缓解策略

Open Questions

待解决问题

  • Question that needs resolution
  • Resolved question - Answer
undefined
  • 需要解决的问题
  • 已解决问题 - 答案
undefined

Plan (plan.md) Structure

实施计划（plan.md）结构

markdown
undefined
markdown
undefined

Implementation Plan: {Track Title}

实施计划: {Track标题}

Track ID: 
{track-id}
Created: YYYY-MM-DD Status: pending | in-progress | completed
Track ID: 
{track-id}
创建日期: YYYY-MM-DD 状态: pending | in-progress | completed

Overview

概述

Brief description of implementation approach.
简述实施方法。

Phase 1: {Phase Name}

阶段1: {阶段名称}

Tasks

任务

  • Task 1.1: Task description
    • Sub-task or detail
    • Sub-task or detail
  • Task 1.2: Task description
  • Task 1.3: Task description
  • 任务1.1: 任务描述
    • 子任务或细节
    • 子任务或细节
  • 任务1.2: 任务描述
  • 任务1.3: 任务描述

Verification

验证

  • Verify 1.1: Verification step for phase
  • 验证1.1: 阶段验证步骤

Phase 2: {Phase Name}

阶段2: {阶段名称}

Tasks

任务

  • Task 2.1: Task description
  • Task 2.2: Task description
  • 任务2.1: 任务描述
  • 任务2.2: 任务描述

Verification

验证

  • Verify 2.1: Verification step for phase
  • 验证2.1: 阶段验证步骤

Phase 3: Finalization

阶段3: 最终收尾

Tasks

任务

  • Task 3.1: Update documentation
  • Task 3.2: Final integration test
  • 任务3.1: 更新文档
  • 任务3.2: 最终集成测试

Verification

验证

  • Verify 3.1: All acceptance criteria met
  • 验证3.1: 所有验收标准均已满足

Checkpoints

检查点

PhaseCheckpoint SHADateStatus
Phase 1pending
Phase 2pending
Phase 3pending
undefined
阶段检查点SHA日期状态
阶段1pending
阶段2pending
阶段3pending
undefined

Status Marker Conventions

状态标记规范

Use consistent markers in plan.md:
MarkerMeaningUsage
[ ]
PendingTask not started
[~]
In ProgressCurrently being worked
[x]
CompleteTask finished (include SHA)
[-]
SkippedIntentionally not done
[!]
BlockedWaiting on dependency
Example:
markdown
- [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)
在plan.md中使用统一标记：
标记含义使用场景
[ ]
待处理任务未开始
[~]
进行中当前正在处理
[x]
已完成任务已完成（需包含SHA）
[-]
已跳过有意不执行
[!]
已阻塞等待依赖项完成
示例:
markdown
- [x] **任务1.1**: 搭建数据库架构 `abc1234`
- [~] **任务1.2**: 实现用户模型
- [ ] **任务1.3**: 添加验证逻辑
- [!] **任务1.4**: 集成认证服务（阻塞：等待API密钥）
- [-] **任务1.5**: 遗留系统迁移（已跳过：无需执行）

Track Registry (tracks.md) Format

Track注册表（tracks.md）格式

markdown
undefined
markdown
undefined

Track Registry

Track注册表

Active Tracks

活跃Track

Track IDTypeStatusPhaseStartedAssignee
user-auth_20250115featurein-progress2/32025-01-15@developer
fix-login_20250114bugpending0/22025-01-14-
Track ID类型状态阶段开始日期负责人
user-auth_20250115featurein-progress2/32025-01-15@developer
fix-login_20250114bugpending0/22025-01-14-

Completed Tracks

已完成Track

Track IDTypeCompletedDuration
setup-ci_20250110chore2025-01-122 days
Track ID类型完成日期持续时间
setup-ci_20250110chore2025-01-122天

Archived Tracks

已归档Track

Track IDReasonArchived
old-feature_20241201Superseded2025-01-05
undefined
Track ID原因归档日期
old-feature_20241201已被替代2025-01-05
undefined

Metadata (metadata.json) Fields

元数据（metadata.json）字段

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"]
}
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"]
}

Track Sizing Guidelines

Track规模指南

Right-Sized Tracks

合适的Track规模

Aim for tracks that:
  • Complete in 1-5 days of work
  • Have 2-4 phases
  • Contain 8-20 tasks total
  • Deliver a coherent, testable unit
理想的Track应满足：
  • 1-5天可完成
  • 包含2-4个阶段
  • 总任务数8-20个
  • 交付一个完整、可测试的工作单元

Too Large

过大的Track

Signs a track is too large:
  • More than 5 phases
  • More than 25 tasks
  • Multiple unrelated features
  • Estimated duration > 1 week
Solution: Split into multiple tracks with clear boundaries.
Track过大的迹象：
  • 超过5个阶段
  • 超过25个任务
  • 包含多个不相关功能
  • 预估时长超过1周
解决方案：拆分为多个边界清晰的Track。

Too Small

过小的Track

Signs a track is too small:
  • Single phase with 1-2 tasks
  • No meaningful verification needed
  • Could be a sub-task of another track
  • Less than a few hours of work
Solution: Combine with related work or handle as part of existing track.
Track过小的迹象：
  • 单阶段仅1-2个任务
  • 无需有意义的验证步骤
  • 可作为其他Track的子任务
  • 工作量不足数小时
解决方案：与相关工作合并，或作为现有Track的一部分处理。

Common Track Patterns

常见Track模式

Feature Track Pattern

功能开发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
阶段1: 基础搭建
- 数据模型
- 数据库迁移
- 基础API结构

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

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

Bug Fix Track Pattern

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
阶段1: 复现问题
- 编写捕获Bug的失败测试
- 文档化复现步骤

阶段2: 修复问题
- 实施修复
- 验证测试通过
- 检查是否引入回归

阶段3: 验证确认
- 人工验证
- 按需更新文档

Refactor Track Pattern

代码重构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: 准备工作
- 添加特征测试
- 文档化当前行为

阶段2: 重构实施
- 增量式应用变更
- 全程保持测试通过

阶段3: 清理收尾
- 删除死代码
- 更新文档

Best Practices

最佳实践

  1. One track, one concern: Keep tracks focused on a single logical change
  2. Small phases: Break work into phases of 3-5 tasks maximum
  3. Verification after phases: Always include verification tasks
  4. Update markers immediately: Mark task status as you work
  5. Record SHAs: Always note commit SHAs for completed tasks
  6. Review specs before planning: Ensure spec is complete before creating plan
  7. Link dependencies: Explicitly note track dependencies
  8. Archive, don't delete: Preserve completed tracks for reference
  9. Size appropriately: Keep tracks between 1-5 days of work
  10. Clear acceptance criteria: Every requirement must be testable
  1. 单一职责：每个Track聚焦于单一逻辑变更
  2. 小阶段：将工作拆分为最多3-5个任务的小阶段
  3. 阶段后验证：每个阶段后务必包含验证任务
  4. 即时更新标记：处理任务时及时更新状态标记
  5. 记录SHA：完成任务时务必记录提交SHA
  6. 先评审规格再规划：确保规格说明书完整后再创建计划
  7. 关联依赖：明确标注Track依赖关系
  8. 归档而非删除：保留已完成Track作为参考
  9. 合理规模：保持Track在1-5天的工作量
  10. 清晰验收标准：所有需求必须可测试

Memory Protocol (MANDATORY)

记忆协议（强制要求）

Before starting:
bash
cat .claude/context/memory/learnings.md
After completing:
  • New pattern -> 
    .claude/context/memory/learnings.md
  • Issue found -> 
    .claude/context/memory/issues.md
  • Decision made -> 
    .claude/context/memory/decisions.md
ASSUME INTERRUPTION: If it's not in memory, it didn't happen.
开始前：
bash
cat .claude/context/memory/learnings.md
完成后：
  • 新模式 -> 写入
    .claude/context/memory/learnings.md
  • 发现问题 -> 写入
    .claude/context/memory/issues.md
  • 决策记录 -> 写入
    .claude/context/memory/decisions.md
假设会被中断：未记录在记忆中的内容视为未发生。