feature-tracking

機能トラッキングスキル

階層型のFRコードを使って、要件ドキュメントに照らし合わせながら機能の実装状況を追跡します。

概要

機能トラッカーは、ソースドキュメント（例：REQUIREMENTS.md）の要件と実装状況を対応付けたJSONファイルを管理します。次の機能をサポートしています。

• 階層型FRコード：FR1、FR2.1、FR2.1.1など
• フェーズベースの開発：機能を開発フェーズごとにグループ化
• PRDとの統合：機能を製品要件ドキュメントにリンク
• タスク追跡：進行中および保留中のタスクを追跡（work-overview.mdを置き換え）
• 同期対象：TODO.mdを同期

使用するタイミング

次の場合に機能トラッキング操作を実行します。

• 機能の実装状況が変わったとき
• 新しいPRDが追加または完了したとき
• 主要な開発マイルストーンの後
• ステータスレポートを生成する前
• 新しい開発フェーズを開始するとき

基本概念

機能ステータス

各機能には、次の5つのステータスのいずれかが設定されます。

• complete：実装ファイルが存在し、テストに合格し、TODO項目にチェックが入っている
• partial：一部の実装はあるが、すべてのサブ機能が完了していない
• in_progress：作業中で、ファイルが最近変更されている
• not_started：実装ファイルがなく、TODOにチェックが入っていない
• blocked：依存関係が不足しているか、明示的にブロック済みとしてマークされている

階層構造

機能は階層的に整理されます。

FR1 (Game Setup & Configuration)
├── FR1.1 (Window Configuration)
├── FR1.2 (Game Mode Selection)
│   ├── FR1.2.1 (Versus Mode)
│   └── FR1.2.2 (Cooperative Mode)
└── FR1.3 (Scenario Setup)

フェーズ別の整理

機能は開発フェーズごとにグループ化されます。

• phase-0：基盤
• phase-1：コアゲームプレイ
• phase-2：高度な機能
• など

ファイル構成

docs/blueprint/
├── feature-tracker.json       # Main tracker file (source of truth)
└── schemas/                   # Optional: local schema copy
    └── feature-tracker.schema.json

プロジェクトのTODO.mdは、チェックボックスの状態を同期する対象です。

注：v1.1.0以降、feature-tracker.jsonには進行中および保留中のタスクを追跡するtasksセクションが含まれており、独立したwork-overview.mdファイルを置き換えています。

クイックコマンド

完了状況の統計を表示

jq '.statistics' docs/blueprint/feature-tracker.json

未完了の機能を一覧表示

jq -r '.. | objects | select(.status == "not_started") | .name' docs/blueprint/feature-tracker.json

PRDの完了状況を表示

jq '.prds | to_entries | .[] | "\(.key): \(.value.status)"' docs/blueprint/feature-tracker.json

フェーズ別に機能を一覧表示

jq -r '.. | objects | select(.phase == "phase-1") | .name' docs/blueprint/feature-tracker.json

ステータス別に機能数を集計

jq '[.. | objects | select(.status?) | .status] | group_by(.) | map({(.[0]): length}) | add' docs/blueprint/feature-tracker.json

スキーマ

機能トラッカーは、検証にJSON Schemaを使用します。スキーマはblueprint-pluginに同梱されており、次の場所にあります。

schemas/feature-tracker.schema.json

主なスキーマ機能：

• 厳密なFRコード検証：^FR\d+(\.\d+)*$
• フェーズパターン検証：^phase-\d+$
• 入れ子に対応した再帰的な機能定義
• PRDの命名パターン：^PRD_[A-Z_]+$

トラッカーを検証

# Using ajv-cli or similar JSON schema validator
ajv validate -s schemas/feature-tracker.schema.json \
             -d docs/blueprint/feature-tracker.json

統合ポイント

マニフェストとの統合

manifest.jsonは機能トラッカーを参照します。

{
  "structure": {
    "has_feature_tracker": true
  },
  "feature_tracker": {
    "file": "feature-tracker.json",
    "source_document": "REQUIREMENTS.md",
    "sync_targets": ["TODO.md"]
  }
}

PRDとの対応付け

機能はprdフィールドを介してPRDにリンクされます。

{
  "name": "Terrain Visual Enhancement",
  "status": "complete",
  "prd": "PRD_TERRAIN_VISUAL_ENHANCEMENT"
}

PRDでは、実装する機能を追跡します。

{
  "PRD_TERRAIN_VISUAL_ENHANCEMENT": {
    "name": "Terrain Visual Enhancement",
    "status": "complete",
    "features_implemented": ["FR2.8.1", "FR2.8.2", "FR2.8.3"],
    "tests_passing": 107
  }
}

作業指示との統合

作業指示では、特定のFRコードを参照できます。作業指示が完了したら、トラッカー内の対応する機能ステータスを更新します。

同期プロセス

同期プロセスでは、次の内容の一貫性を保ちます。

1. feature-tracker.json（機能とタスクの信頼できる唯一の情報源）
2. TODO.md（チェックボックスベースのタスクリスト）

同期手順

1. feature-tracker.jsonから現在の状態（機能とタスク）を読み込む
2. TODO.mdのチェックボックスの状態と比較する
3. 各機能の実装状況を確認する
4. 統計を再計算する
5. 変更を反映してTODO.mdを更新する
6. 同期した内容を報告する

人が読みやすい概要

--summaryフラグを使うと、概要をMarkdown形式で生成できます。

/blueprint:feature-tracker-sync --summary

ステータスの確認

各機能について、次の内容を確認します。

• complete：ファイルが存在し、テストに合格し（該当する場合）、TODOにチェックが入っている
• partial：一部のファイルは存在するが、すべてのサブ機能が完了していない
• in_progress：最近のコミットで機能のファイルが変更されている
• not_started：実装の証拠がない
• blocked：依存関係の問題が文書化されている

コマンド

関連するblueprintコマンド：

• /blueprint:feature-tracker-status：統計と完了状況の概要を表示
• /blueprint:feature-tracker-sync：トラッカーを同期対象と同期

例：機能ステータスの更新

機能を完了したら：

1. feature-tracker.json の機能ステータスを更新します：

   {
     "name": "Unit Selection",
     "status": "complete",
     "phase": "phase-2",
     "implementation": {
       "files": ["src/systems/selection.rs"],
       "notes": "Box selection and click selection",
       "tests": ["tests/selection_tests.rs"]
     }
   }
   

2. /blueprint:feature-tracker-sync を実行して、次の項目を更新します：

   • タスクを tasks.in_progress から tasks.completed に移動します
   • TODO.md のチェックボックス
   • 統計を再計算します

3. 一貫性を保つため、すべての変更をまとめてコミットします

統計

トラッカーは集計統計を保持します：

{
  "statistics": {
    "total_features": 42,
    "complete": 22,
    "partial": 4,
    "in_progress": 2,
    "not_started": 14,
    "blocked": 0,
    "completion_percentage": 52.4
  }
}

これらは同期処理中に再計算されます。