track-management

トラック管理

トラックの作成、管理、完了に関するガイドです。トラックとは、仕様策定、計画、実装の各段階を通じて、機能、バグ、リファクタリングを整理する論理的な作業単位です。

このスキルを使用する場面

• 新しい機能、バグ、リファクタリングのトラックを作成するとき
• spec.md ファイルを作成またはレビューするとき
• plan.md ファイルを作成または更新するとき
• 作成から完了までのトラックのライフサイクルを管理するとき
• トラックのステータスマーカーや規約を理解するとき
• tracks.md レジストリを扱うとき
• トラックのメタデータを解釈または更新するとき

トラックの概念

トラックは、作業全体をまとめる論理的な作業単位です。各トラックには次の要素があります。

• 一意の識別子
• 要件を定義する仕様
• 作業をタスクに分割した段階的な計画
• ステータスと進捗を記録するメタデータ

トラックを使うと、作業を意味的に整理でき、次のことが可能になります。

• 明確なスコープ境界の設定
• 進捗の追跡
• Git と連携した操作（トラック単位での取り消し）
• チーム内の連携

トラックの種類

feature

新しい機能や能力に使用します。対象は次のとおりです。

• ユーザー向けの新機能
• 新しい API エンドポイント
• 新しい統合
• 大幅な機能強化

bug

不具合の修正に使用します。対象は次のとおりです。

• 誤った動作
• エラー状態
• パフォーマンスの低下
• セキュリティ上の脆弱性

chore

保守や雑務に使用します。対象は次のとおりです。

• 依存関係の更新
• 設定の変更
• ドキュメントの更新
• クリーンアップ作業

refactor

動作を変更せずにコードを改善するときに使用します。対象は次のとおりです。

• コードの再構成
• パターンの導入
• 技術的負債の削減
• パフォーマンスの最適化（動作は同じで、パフォーマンスを向上）

トラック ID の形式

トラック 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

トラックのライフサイクル

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)

トラックレジストリ（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.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"]
}

トラックの規模に関するガイドライン

適切な規模のトラック

以下を目安にしてください。

• 作業期間が1～5日で完了する
• フェーズが2～4個ある
• タスクの合計が8～20個ある
• 一貫性があり、テスト可能な単位を提供する

大きすぎる場合

トラックが大きすぎる兆候は次のとおりです。

• フェーズが5個を超える
• タスクが25個を超える
• 関連性のない機能が複数含まれている
• 予想所要期間が1週間を超える

解決策：明確な境界を設けて、複数のトラックに分割します。

小さすぎる場合

トラックが小さすぎる兆候は次のとおりです。

• フェーズが1つで、タスクが1～2個しかない
• 意味のある検証が不要
• 別のトラックのサブタスクにできる
• 作業時間が数時間未満

解決策：関連する作業と統合するか、既存のトラックの一部として対応します。

一般的なトラックのパターン

機能トラックのパターン

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

バグ修正トラックのパターン

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

リファクタリングトラックのパターン

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. 1つのトラックにつき1つの目的：トラックは単一の論理的な変更に集中させます
2. フェーズは小さく：作業を最大3～5個のタスクからなるフェーズに分けます
3. 各フェーズの後に検証：必ず検証タスクを含めます
4. マーカーはすぐに更新：作業を進めながらタスクのステータスを更新します
5. SHAを記録：完了したタスクのコミットSHAを必ず記録します
6. 計画前に仕様を確認：計画を作成する前に仕様が完成していることを確認します
7. 依存関係を明記：トラックの依存関係を明示的に記録します
8. 削除せずアーカイブ：完了したトラックは参照用に保存します
9. 適切な規模にする：トラックの作業期間は1～5日にします
10. 明確な受け入れ基準：すべての要件をテスト可能にします

絶対厳守事項

1. 実装コードを書く前に、必ずトラックディレクトリと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を記録する
ブロックされたタスクを無視する	表面化しないブロッカーがトラックを妨げる	[!]のブロッカーはすぐにエスカレーションし、飛ばさない

メモリプロトコル（必須）

開始前：

cat .claude/context/memory/learnings.md

完了後：

• 新しいパターン -> .claude/context/memory/learnings.md
• 発見した問題 -> .claude/context/memory/issues.md
• 下した決定 -> .claude/context/memory/decisions.md

中断されることを前提にしてください。メモリに記録されていなければ、起きていないのと同じです。