drift-analysis

漂移分析

用于分析项目状态、检测计划漂移和制定优先级重建计划的知识与模式。

架构概览

/drift-detect
        │
        ├─→ collectors.js (pure JavaScript)
        │   ├─ scanGitHubState()
        │   ├─ analyzeDocumentation()
        │   └─ scanCodebase()
        │
        └─→ plan-synthesizer (Opus)
            └─ Deep semantic analysis with full context

数据收集：纯 JavaScript（无大模型开销） 语义分析：使用完整上下文进行一次 Opus 调用

漂移检测模式

漂移类型

计划漂移：文档中的计划与实际实现不一致

• PLAN.md 中的项目长期处于未勾选状态
• 路线图中的里程碑延期但未更新
• 代码变更未体现迭代／阶段目标

文档漂移：文档落后于实现

• 新功能已存在，但没有相应文档
• README 描述了并不存在的功能
• API 文档与实际端点不符

问题漂移：问题跟踪与实际情况不一致

• 已不再适用的过时问题
• 工作已完成，但问题仍未关闭
• 高优先级项目被忽略

范围漂移：项目范围超出原定计划

• 文档记录的功能多于可交付的功能
• 持续添加功能，却没有完成项目
• 待办事项不断增加，却没有精简

检测信号

HIGH-CONFIDENCE DRIFT INDICATORS:
- Milestone 30+ days overdue with open issues
- PLAN.md < 30% completion after 90 days
- 5+ high-priority issues stale > 60 days
- README features not found in codebase

MEDIUM-CONFIDENCE INDICATORS:
- Documentation files unchanged for 180+ days
- Draft PRs open > 30 days
- Issue themes don't match code activity
- Large gap between documented and implemented features

LOW-CONFIDENCE INDICATORS:
- Many TODOs in codebase
- Stale dependencies
- Old git branches not merged

优先级框架

优先级计算

function calculatePriority(item, weights) {
  let score = 0;

  // Severity base score
  const severityScores = {
    critical: 15,
    high: 10,
    medium: 5,
    low: 2
  };
  score += severityScores[item.severity] || 5;

  // Category multiplier
  const categoryWeights = {
    security: 2.0,    // Security issues get 2x
    bugs: 1.5,        // Bugs get 1.5x
    infrastructure: 1.3,
    features: 1.0,
    documentation: 0.8
  };
  score *= categoryWeights[item.category] || 1.0;

  // Recency boost
  if (item.createdRecently) score *= 1.2;

  // Stale penalty (old items slightly deprioritized)
  if (item.daysStale > 180) score *= 0.9;

  return Math.round(score);
}

时间范围阈值

分类	条件	最大项目数
立即处理	severity=critical 或 priority >= 15	5
短期	severity=high 或 priority >= 10	10
中期	priority >= 5	15
待办	其他所有情况	20

优先级权重（默认）

security: 10     # Security issues always top priority
bugs: 8          # Bugs affect users directly
features: 5      # New functionality
documentation: 3 # Important but not urgent
tech-debt: 4     # Keeps codebase healthy

交叉引用模式

文档与代码的匹配

// Fuzzy matching for feature names
function featureMatch(docFeature, codeFeature) {
  const normalize = s => s
    .toLowerCase()
    .replace(/[-_\s]+/g, '')
    .replace(/s$/, ''); // Remove trailing 's'

  const docNorm = normalize(docFeature);
  const codeNorm = normalize(codeFeature);

  return docNorm.includes(codeNorm) ||
         codeNorm.includes(docNorm) ||
         levenshteinDistance(docNorm, codeNorm) < 3;
}

常见不匹配

文档描述	实现形式
“用户身份验证”	auth/、login/、session/
“API 端点”	routes/、api/、handlers/
“数据库模型”	models/、entities/、schemas/
“缓存层”	cache/、redis/、memcache/
“日志系统”	logger/、logs/、telemetry/

输出模板

漂移报告章节

## Drift Analysis

### {drift_type}
**Severity**: {severity}
**Detected In**: {source}

{description}

**Evidence**:
{evidence_items}

**Recommendation**: {recommendation}

差距报告章节

## Gap: {gap_title}

**Category**: {category}
**Severity**: {severity}

{description}

**Impact**: {impact_description}

**To Address**:
1. {action_item_1}
2. {action_item_2}

重建计划章节

## Reconstruction Plan

### Immediate Actions (This Week)
{immediate_items_numbered}

### Short-Term (This Month)
{short_term_items_numbered}

### Medium-Term (This Quarter)
{medium_term_items_numbered}

### Backlog
{backlog_items_numbered}

最佳实践

分析漂移时

1. 比较时间戳，而不只是内容

   • 文档上次更新时间与代码上次变更时间分别是什么时候？
   • 里程碑的日期是否切合实际？

2. 关注模式，而不是单个项目

   • 一个过时问题不算漂移；10 个过时问题才算一种模式
   • 一个未记录的功能不算漂移；5 个未记录的功能才算

3. 考虑上下文

   • 活跃开发自然会产生一定程度的漂移
   • 成熟项目应尽量减少漂移
   • 项目上线后，文档往往会出现滞后

4. 根据影响确定权重

   • 面向用户的漂移比内部漂移影响更大
   • 公开 API 的漂移比实现细节的漂移影响更大

制定计划时

1. 注重可执行性，而非面面俱到

   • 列出最优先的 5 个立即处理项目，而不是前 50 个
   • 每个项目都应能在合理时间内完成

2. 将相关项目归类

   • 写成“更新身份验证文档”，而不是“更新登录页面文档”＋“更新注册文档”

3. 明确成功标准

   • 如何判断某个漂移问题已解决？

4. 平衡各类别

   • 安全问题优先，但也不要忽略其他所有事项
   • 将快速见效的项目与重要工作结合起来

数据收集（JavaScript）

collectors.js 模块无需大模型开销即可提取数据：

GitHub 数据

• 按标签分类的未关闭问题
• 包含草稿状态的未关闭 PR
• 含截止日期的里程碑
• 长期未更新的项目（超过 90 天未活动）
• 根据标题进行主题分析

文档数据

• 解析 README、PLAN.md、CLAUDE.md、CHANGELOG.md
• 复选框完成数量
• 章节分析
• 功能列表

代码数据

• 目录结构
• 框架检测
• 是否存在测试框架
• 健康状况指标（CI、代码检查、测试）

语义分析（Opus）

计划合成器接收所有收集的数据，并执行以下操作：

1. 交叉引用：将文档中记录的功能与实现进行匹配
2. 偏差识别：查找偏差模式
3. 差距分析：识别缺失的内容
4. 优先级排序：结合上下文进行排序
5. 报告生成：提供可执行的建议

输入/输出示例

收集的数据（来自 collectors.js）

{
  "github": {
    "issues": [...],
    "categorized": { "bugs": [...], "features": [...] },
    "stale": [...]
  },
  "docs": {
    "files": { "README.md": {...}, "PLAN.md": {...} },
    "checkboxes": { "total": 15, "checked": 3 }
  },
  "code": {
    "frameworks": ["Express"],
    "health": { "hasTests": true, "hasCi": true }
  }
}

分析输出（来自 plan-synthesizer）

# Reality Check Report

## Executive Summary
Project has moderate drift: 8 stale priority issues and 20% plan completion.
Strong code health (tests + CI) but documentation lags implementation.

## Drift Analysis
### Priority Neglect
**Severity**: high
8 high-priority issues inactive for 60+ days...

## Prioritized Plan
### Immediate
1. Close #45 (already implemented)
2. Update README API section...