feature-tracking

功能跟踪技能

使用分层 FR 代码，根据需求文档跟踪功能实现状态。

概述

功能跟踪器维护一个 JSON 文件，将源文档（例如 REQUIREMENTS.md）中的需求映射到实现状态。它支持：

• 分层 FR 代码：FR1、FR2.1、FR2.1.1 等
• 按阶段开发：按开发阶段对功能分组
• PRD 集成：将功能关联到产品需求文档
• 任务跟踪：跟踪进行中和待处理的任务（替代 work-overview.md）
• 同步目标：使 TODO.md 保持同步

适用场景

在以下情况下运行功能跟踪操作：

• 功能实现状态发生变化
• 新增或完成 PRD
• 重大开发里程碑之后
• 生成状态报告之前
• 开始新的开发阶段

核心概念

功能状态

每项功能有五种状态之一：

• 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 进行验证。该 Schema 与 blueprint-plugin 一同打包，位于：

schemas/feature-tracker.schema.json

Schema 的主要特性：

• 严格验证 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
  }
}

这些数据会在同步操作期间重新计算。