expert-entropy-auditor

name	expert-entropy-auditor
description	熵增审计技能，发现设计意图与代码实现之间的裂痕，识别代码库中的 AI 残渣。当用户需要技术债务审计、PRD 一致性检查时触发。触发词：审计技术债务、PRD一致性、AI残渣检测、熵增审计。
license	MIT
compatibility	需要 PRD 文档和代码库
metadata	{"author":"[e-mail]","version":"1.0"}

熵增审计 (expert-entropy-auditor)

核心理念

"像垃圾回收器一样，将分散在代码库中的'AI残渣'识别出来，并建议将其归集到共享的实用程序包中。" —— Harness Engineering

熵增审计技能专门用于发现"设计意图"与"代码实现"之间的裂痕，识别代码库中的熵增点。

审计维度

1. PRD 与代码一致性

审计方法：

• 解析 PRD 文档中的功能点
• 扫描代码实现
• 对比功能点与实现

示例：

PRD 功能点：用户登录后显示欢迎消息
代码实现：用户登录后直接跳转到首页
→ 审计结果：实现与 PRD 不一致

2. Spec 文档与代码一致性

审计方法：

• 解析 Spec 文档中的技术规格
• 检查代码是否符合规格
• 标记偏差

示例：

Spec 规格：API 返回 { code, data, message }
代码实现：API 返回 { status, result }
→ 审计结果：返回格式不符合规格

3. AI 残渣检测

什么是 AI 残渣：

• 重复生成的相似代码
• 猜测的数据结构
• 不一致的命名模式
• 分散的辅助工具

检测方法：

• 代码相似度分析
• 命名模式分析
• 重复代码检测

示例：

文件 A：function formatDate(date) { ... }
文件 B：function formatDateString(d) { ... }
文件 C：function dateFormat(dateVal) { ... }
→ 审计结果：AI 残渣，建议提取到共享工具包

4. 技术债务累积

检测方法：

• 扫描 TODO/FIXME/HACK 注释
• 检查临时方案标记
• 统计技术债务数量

示例：

技术债务统计：
- TODO: 15 个
- FIXME: 3 个
- HACK: 2 个
→ 审计结果：技术债务累积，建议处理

---

审计流程

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   收集      │ ──→ │   分析      │ ──→ │   评分      │ ──→ │   报告      │
│             │     │             │     │             │     │             │
│ • PRD 文档  │     │ • 一致性    │     │ • 熵值计算  │     │ • 问题清单  │
│ • Spec 文档 │     │ • 重复检测  │     │ • 债务评估  │     │ • 改进建议  │
│ • 代码实现  │     │ • 模式分析  │     │ • 风险评级  │     │ • 优先排序  │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘

---

熵值评分系统

评分维度

维度	权重	评分标准
PRD 一致性	25%	功能点与实现匹配度
Spec 一致性	25%	技术规格符合度
AI 残渣	25%	重复代码比例
技术债务	25%	债务数量与严重度

评分计算

熵值 = 100 - (不一致数 × 5 + AI残渣数 × 3 + 技术债务数 × 2)

示例：
- PRD 不一致：2 项 → 扣 10 分
- Spec 不一致：1 项 → 扣 5 分
- AI 残渣：5 项 → 扣 15 分
- 技术债务：10 项 → 扣 20 分

熵值 = 100 - (10 + 5 + 15 + 20) = 50

状态判定

分数范围	状态	建议动作
90-100	优秀	维持现状
70-89	良好	小额改进
50-69	一般	计划性清理
30-49	警告	优先处理
0-29	危险	紧急重构

---

输出格式

熵增审计报告

# 熵增审计报告 - YYYY-MM-DD

## 熵值评分：XX/100

## 审计范围
- PRD 文档：X 份
- Spec 文档：X 份
- 代码文件：X 个

## 一致性审计

### PRD 与代码不一致
| PRD 功能点 | 代码实现 | 偏差描述 |
|-----------|---------|---------|
| FP-001 用户登录欢迎消息 | 未实现 | 缺少欢迎消息显示 |

### Spec 与代码不一致
| Spec 规格 | 代码实现 | 偏差描述 |
|----------|---------|---------|
| API 返回格式 | 不符合 | 缺少 message 字段 |

## AI 残渣检测

### 重复代码
| 文件 A | 文件 B | 相似度 | 建议 |
|-------|-------|-------|------|
| utils/formatDate.js | utils/dateFormat.js | 85% | 提取到共享工具包 |

### 猜测的数据结构
| 文件 | 问题 | 建议 |
|------|------|------|
| service/UserService.ts | 硬编码字段名 | 定义类型接口 |

## 技术债务统计

| 类型 | 数量 | 平均存在时间 |
|------|------|-------------|
| TODO | 15 | 14 天 |
| FIXME | 3 | 7 天 |
| HACK | 2 | 30 天 |

## 改进建议

### 高优先级
1. 修复 PRD 不一致项（2 项）
2. 提取重复代码到共享工具包（5 项）

### 中优先级
1. 处理 FIXME 注释（3 项）
2. 定义缺失的类型接口（3 项）

### 低优先级
1. 清理过时 TODO（12 项）

---

配置选项

# entropy-auditor-config.yaml
entropy_auditor:
  # 审计范围
  scope:
    prd_paths: ["docs/prd/", "docs/业务分析/"]
    spec_paths: ["docs/specs/", "docs/dev-specs/"]
    code_paths: ["src/"]
  
  # 检测阈值
  thresholds:
    code_similarity: 0.8      # 代码相似度阈值
    max_todo_age_days: 30     # TODO 最大存在时间
    max_fixme_age_days: 14    # FIXME 最大存在时间
  
  # 评分权重
  weights:
    prd_consistency: 0.25
    spec_consistency: 0.25
    ai_residue: 0.25
    tech_debt: 0.25

---

使用示例

示例 1：全面熵增审计

用户：执行技术债务审计

AI：
1. 收集 PRD、Spec、代码
2. 分析一致性
3. 检测 AI 残渣
4. 计算熵值评分
5. 生成审计报告

示例 2：PRD 一致性检查

用户：检查 PRD 与代码是否一致

AI：
1. 解析 PRD 功能点
2. 扫描代码实现
3. 对比功能点与实现
4. 生成偏差报告

示例 3：AI 残渣检测

用户：检测代码中的 AI 残渣

AI：
1. 代码相似度分析
2. 命名模式分析
3. 识别重复代码
4. 建议提取到共享工具包

---

与其他技能的协作

• pdd-entropy-reduction：作为子技能被协调调用
• pdd-doc-gardener：传递文档不一致问题
• expert-auto-refactor：传递重构建议
• pdd-code-reviewer：集成熵增检查到代码审查