# Expert Entropy Auditor

> 熵增审计技能，发现设计意图与代码实现之间的裂痕，识别代码库中的 AI 残渣。当用户需要技术债务审计、PRD 一致性检查时触发。触发词：审计技术债务、PRD一致性、AI残渣检测、熵增审计。

- Skill: `wonderslife/expert-entropy-auditor` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add wonderslife/expert-entropy-auditor`
- Raw SKILL.md: https://api.skillmd.com/api/skills/wonderslife/expert-entropy-auditor/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- License: MIT
- Author: wonderslife (https://skillmd.com/u/wonderslife)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/wonderslife/expert-entropy-auditor

---


# 熵增审计 (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 | 危险 | 紧急重构 |

---

## 输出格式

### 熵增审计报告

```markdown
# 熵增审计报告 - 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 项）
```

---

## 配置选项

```yaml
# 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**：集成熵增检查到代码审查