トラック管理

Conductor トラック（特性、バグ、リファクタリングの論理的作業単位）を作成、管理、完了するためのガイド。仕様、計画、実装フェーズ全体を通じて、作業を組織化します。

このスキルを使う場面

• 新しい特性、バグ、またはリファクタリングトラックを作成する場合
• 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. インタラクティブな Q&A を通じて要件を収集
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）の構造

# {トラックタイトル}

## 概要

このトラックが何を達成し、なぜ必要かについての簡潔な説明。

## 機能要件

### FR-1: {要件名}

機能要件の説明。

- 受け入れ条件：この要件が満たされていることを確認する方法

### FR-2: {要件名}

...

## 非機能要件

### NFR-1: {要件名}

非機能要件の説明（パフォーマンス、セキュリティなど）

- 目標：具体的な測定可能な目標
- 検証：テスト方法

## 受け入れ条件

- [ ] 条件 1：具体的でテスト可能な条件
- [ ] 条件 2：具体的でテスト可能な条件
- [ ] 条件 3：具体的でテスト可能な条件

## スコープ

### スコープ内

- 明示的に含まれるアイテム
- 実装する機能
- 変更するコンポーネント

### スコープ外

- 明示的に除外されるアイテム
- 将来の検討事項
- 関連するが別の作業

## 依存関係

### 内部

- このトラックが依存する他のトラックまたはコンポーネント
- 必要なコンテキストアーティファクト

### 外部

- サードパーティサービスまたは API
- 外部依存関係

## リスクと対策

| リスク       | 影響          | 対策戦略         |
| ------------ | ------------- | -------------- |
| リスク説明   | 高/中/低      | 対策戦略       |

## 未解決の質問

- [ ] 解決が必要な質問
- [x] 解決済みの質問 - 回答

計画（plan.md）の構造

# 実装計画：{トラックタイトル}

トラック ID：`{track-id}`
作成日：YYYY-MM-DD
ステータス：pending | in-progress | completed

## 概要

実装アプローチの簡潔な説明。

## フェーズ 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 |                     |      | pending   |
| フェーズ 2 |                     |      | pending   |
| フェーズ 3 |                     |      | pending   |

ステータスマーカー規約

plan.md で一貫したマーカーを使用します：

マーカー	意味	使用場面
[ ]	保留中	タスクが開始されていない
[~]	進行中	現在取り組み中
[x]	完了	タスク完了（SHA を含める）
[-]	スキップ	意図的に実施しない
[!]	ブロック	依存関係を待機中

例：

- [x] **タスク 1.1**：データベーススキーマをセットアップ `abc1234`
- [~] **タスク 1.2**：ユーザーモデルを実装
- [ ] **タスク 1.3**：検証ロジックを追加
- [!] **タスク 1.4**：認証サービスを統合（ブロック：API キー待機中）
- [-] **タスク 1.5**：レガシーマイグレーション（スキップ：不要）

トラックレジストリ（tracks.md）フォーマット

# トラックレジストリ

## アクティブトラック

| トラック ID                                       | タイプ    | ステータス    | フェーズ | 開始日     | 担当者     |
| ------------------------------------------------ | ------- | ----------- | ------ | ---------- | --------- |
| [user-auth_20250115](tracks/user-auth_20250115/) | feature | in-progress | 2/3    | 2025-01-15 | @developer |
| [fix-login_20250114](tracks/fix-login_20250114/) | bug     | pending     | 0/2    | 2025-01-14 | -         |

## 完了トラック

| トラック ID                                      | タイプ | 完了日     | 期間    |
| ---------------------------------------------- | ----- | ---------- | ------- |
| [setup-ci_20250110](tracks/setup-ci_20250110/)  | chore | 2025-01-12 | 2 days  |

## アーカイブトラック

| トラック ID                                            | 理由         | アーカイブ日 |
| ---------------------------------------------------- | ----------- | ----------- |
| [old-feature_20241201](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. /conductor:new-track を実行
2. インタラクティブな質問に回答
3. 生成された spec.md を確認
4. 生成された plan.md を確認
5. トラック作成を確認

実装の開始

1. spec.md と plan.md を読む
2. コンテキストアーティファクトが最新であることを確認
3. 最初のタスクを [~] に設定
4. TDD ワークフローを開始

フェーズの完了

1. すべてのフェーズタスクが [x] であることを確認
2. 検証タスクを完了
3. チェックポイント承認を待つ
4. チェックポイント SHA を記録
5. 次のフェーズに進む

トラックの完了

1. すべてのフェーズが完了していることを確認
2. すべての受け入れ条件が満たされていることを確認
3. 必要に応じて product.md を更新
4. tracks.md でトラックを完了としてマーク
5. metadata.json を更新

トラックの戻す

1. /conductor:revert を実行
2. 戻すトラックを選択
3. 粒度を選択（track/phase/task）
4. 戻す操作を確認
5. ステータスマーカーを更新

トラック依存関係の処理

依存関係の特定

トラック作成時に以下を特定します：

• ハード依存：このトラック開始前に完了する必要がある
• ソフト依存：並行して進行可能だが統合に影響する可能性
• 外部依存：サードパーティサービス、API、チーム決定

依存関係の文書化

spec.md で、依存関係を以下情報で記載します：

• 依存関係のタイプ（ハード/ソフト/外部）
• 現在のステータス（利用可能/保留中/ブロック中）
• 解決パス（実施が必要なこと）

ブロックされたトラックの管理

トラックがブロックされた場合：

1. ブロックされたタスクを [!] で理由とともにマーク
2. tracks.md ステータスを更新
3. metadata.json にブロッカーを文書化
4. 必要に応じて依存トラックの作成を検討

トラックサイジングガイドライン

適切なサイズのトラック

以下を目指すトラック：

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

大きすぎるトラック

トラックが大きすぎることの兆候：

• 5 を超えるフェーズ
• 25 を超えるタスク
• 複数の無関係な機能
• 推定期間が 1 週間以上

解決策：明確な境界線を持つ複数のトラックに分割します。

小さすぎるトラック

トラックが小さすぎることの兆候：

• 1～2 タスクの単一フェーズ
• 意味のある検証が不要
• 別のトラックのサブタスクになる可能性
• 数時間未満の作業

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

仕様品質チェックリスト

spec.md を最終化する前に以下を確認します：

要件品質

• 各要件に明確な受け入れ条件がある
• 要件がテスト可能である
• 要件が独立している（個別に検証可能）
• 曖昧な表現がない（「高速である」→「応答 < 200ms」）

スコープの明確さ

• スコープ内のアイテムが具体的
• スコープ外のアイテムがスコープクリープを防止
• 実装者に対して明確な境界線

依存関係の特定

• すべての内部依存関係が記載されている
• 外部依存関係に所有者/連絡先がいる
• 依存関係ステータスが最新

リスクの対応

• 主要なリスクが特定されている
• 影響評価が現実的
• 対策が実行可能

計画品質チェックリスト

実装を開始する前に plan.md を確認します：

タスク品質

• タスクがアトミック（1 つの論理的アクション）
• タスクが独立して検証可能
• タスク説明が明確
• サブタスクが有用な詳細を提供

フェーズ組織

• フェーズが関連タスクをグループ化
• 各フェーズがテスト可能なもの提供
• 各フェーズ後に検証タスク
• フェーズが論理的に相互構築

完全性

• すべての仕様要件に対応するタスクがある
• ドキュメンテーションタスクが含まれる
• テストタスクが含まれる
• 統合タスクが含まれる

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

特性トラックパターン

フェーズ 1：基礎
- データモデル
- データベースマイグレーション
- 基本的な API 構造

フェーズ 2：コアロジック
- ビジネスロジック実装
- 入力検証
- エラーハンドリング

フェーズ 3：統合
- UI 統合
- API ドキュメント
- エンドツーエンドテスト

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

フェーズ 1：再現
- バグをキャプチャする失敗テストを記述
- 再現ステップを文書化

フェーズ 2：修正
- 修正を実装
- テスト合格を確認
- リグレッションをチェック

フェーズ 3：検証
- 手動検証
- 必要に応じてドキュメントを更新

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

フェーズ 1：準備
- キャラクタライゼーションテストを追加
- 現在の動作を文書化

フェーズ 2：リファクタリング
- 変更を段階的に適用
- 全体を通じてテストを緑に保つ

フェーズ 3：クリーンアップ
- デッドコードを削除
- ドキュメントを更新

ベストプラクティス

1. 1 つのトラック、1 つの懸念：トラックを単一の論理的変更に焦点を当てる
2. 小さなフェーズ：作業を最大 3～5 タスクのフェーズに分割
3. フェーズ後の検証：常に検証タスクを含める
4. マーカーを即座に更新：作業しながらタスクステータスをマーク
5. SHA を記録：完了したタスクに常にコミット SHA を記載
6. 計画前に仕様を確認：計画を作成する前に仕様が完成していることを確認
7. 依存関係をリンク：トラック依存関係を明示的に記載
8. 削除ではなくアーカイブ：完了したトラックを参照用に保持
9. 適切なサイズ：トラックを 1～5 日間の作業に保つ
10. 明確な受け入れ条件：すべての要件がテスト可能である