---
name: devbooks-entropy-monitor
description: devbooks-entropy-monitor：定期采集系统熵度量（结构熵/变更熵/测试熵/依赖熵），生成量化报告，当指标超阈值时建议重构。用户说"熵度量/复杂度趋势/重构预警/代码健康/技术债务度量"等时使用。
recommended_experts: ["Performance Engineer", "System Architect"]
allowed-tools:
  - Glob
  - Grep
  - Read
  - Bash
---

# DevBooks：系统熵度量与预警（Entropy Monitor）

## 渐进披露
### 基础层（必读）
目标：明确本 Skill 的核心产出与使用范围。
输入：用户目标、现有文档、变更包上下文或项目路径。
输出：可执行产物、下一步指引或记录路径。
边界：不替代其他角色职责，不触碰 tests/。
证据：引用产出物路径或执行记录。

### 进阶层（可选）
适用：需要细化策略、边界或风险提示时补充。

### 扩展层（可选）
适用：需要与外部系统或可选工具协同时补充。

## 推荐 MCP 能力类型
- 代码检索（code-search）
- 引用追踪（reference-tracking）
- 影响分析（impact-analysis）

> 来源：《人月神话》第16章"没有银弹" — "软件实体的复杂性是根本属性...控制复杂性是软件开发的关键"

## 前置：配置发现（协议无关）

- `<truth-root>`：当前真理目录根
- `<change-root>`：变更包目录根

执行前**必须**按以下顺序查找配置（找到后停止）：
1. `.devbooks/config.yaml`（如存在）→ 解析并使用其中的映射
2. `dev-playbooks/project.md`（如存在）→ Dev-Playbooks 协议，使用默认映射
3. `project.md`（如存在）→ template 协议，使用默认映射
4. 若仍无法确定 → **停止并询问用户**

**关键约束**：
- 如果配置中指定了 `agents_doc`（规则文档），**必须先阅读该文档**再执行任何操作
- 禁止猜测目录根
- 禁止跳过规则文档阅读

## 核心理念

**系统熵** = 代码复杂度随时间的增长趋势

熵度量的目标：
1. **定量化**：所有指标都是数值/比率，可对比
2. **趋势可视**：历史数据支持趋势分析
3. **阈值预警**：超阈值时主动建议重构
4. **定期执行**：作为独立任务，不嵌入每次 code review

## 执行方式

1) 先阅读并遵守：`~/.claude/skills/_shared/references/AI行为规范.md`（可验证性 + 结构质量守门）。
2) 严格按完整提示词输出：`references/熵度量方法论.md`。

## 脚本

| 脚本 | 用途 | 示例 |
|------|------|------|
| `entropy-measure.sh` | 采集熵指标 | `entropy-measure.sh --project-root /path/to/repo` |
| `entropy-report.sh` | 生成报告 | `entropy-report.sh --output report.md` |

## 指标体系（四维度）

### A) 结构熵（Structural Entropy）

| 指标 | 采集方式 | 健康阈值 | 说明 |
|------|---------|---------|------|
| 圈复杂度均值 | 静态分析 | < 10 | 函数级平均 |
| 圈复杂度 P95 | 静态分析 | < 20 | 95 分位数 |
| 文件行数 P95 | 行数统计 | < 500 | 过大文件预警 |
| 函数行数 P95 | 静态分析 | < 50 | 过长函数预警 |

### B) 变更熵（Change Entropy）

| 指标 | 采集方式 | 健康阈值 | 说明 |
|------|---------|---------|------|
| 热点文件占比 | git log | < 0.1 | 频繁修改的文件占比 |
| 耦合变更率 | git log | < 0.3 | 经常一起修改的文件对比例 |
| 代码流失率 | git diff | < 0.5 | 新增代码在30天内被删除的比例 |

### C) 测试熵（Test Entropy）

| 指标 | 采集方式 | 健康阈值 | 说明 |
|------|---------|---------|------|
| Flaky 测试占比 | CI 日志 | < 0.01 | 不稳定测试占比 |
| 测试覆盖率 | 覆盖工具 | > 0.7 | 代码覆盖率 |
| 测试/代码比 | 行数统计 | > 0.5 | 测试代码与生产代码比例 |

### D) 依赖熵（Dependency Entropy）

| 指标 | 采集方式 | 健康阈值 | 说明 |
|------|---------|---------|------|
| 过期依赖占比 | npm/pip audit | < 0.2 | 超过2个大版本的依赖 |
| 安全漏洞数 | 安全扫描 | = 0 | 高危漏洞数量 |
| 依赖深度 P95 | 依赖树分析 | < 10 | 传递依赖层数 |

## 产物落点

| 产物 | 路径 | 说明 |
|------|------|------|
| 熵报告 | `<truth-root>/_meta/entropy/entropy-report-YYYY-MM-DD.md` | 当次采集报告 |
| 历史数据 | `<truth-root>/_meta/entropy/history.json` | 所有历史指标 |
| 阈值配置 | `<truth-root>/_meta/entropy/thresholds.json` | 可配置阈值 |

## 执行频率建议

| 项目规模 | 建议频率 | 触发方式 |
|---------|---------|---------|
| 小型（< 10K LOC） | 每周 | 手动 / CI 定时 |
| 中型（10K-100K LOC） | 每日 | CI 定时 |
| 大型（> 100K LOC） | 每次合并 | PR 合并触发 |

## 与其他 Skill 的关系

| Skill | 关系 |
|-------|------|
| devbooks-reviewer | 熵度量**不**嵌入每次 review，作为独立任务 |
| devbooks-proposal-author | 熵报告可作为重构提案的数据支撑 |
| devbooks-impact-analysis | 高熵区域变更需更谨慎的影响分析 |

## 硬约束

1. **定量优先**：所有指标必须是数值/比率，禁止主观评价
2. **阈值可配**：所有阈值通过 `thresholds.json` 管理，不硬编码
3. **历史可追**：每次采集结果追加到 `history.json`
4. **独立执行**：不嵌入其他工作流，作为定期任务独立运行

---

## 上下文感知

本 Skill 在执行前自动检测上下文，选择合适的采集范围。

检测规则参考：`skills/_shared/上下文检测模板.md`

### 检测流程

1. 检测历史数据文件是否存在
2. 检测上次采集时间
3. 检测是否有指标超阈值

### 本 Skill 支持的模式

| 模式 | 触发条件 | 行为 |
|------|----------|------|
| **首次采集** | 历史数据不存在 | 执行完整采集并建立基线 |
| **增量采集** | 距上次采集超过间隔 | 采集新数据并对比趋势 |
| **预警模式** | 检测到指标超阈值 | 生成预警报告并建议重构 |

### 检测输出示例

```
检测结果：
- 历史数据：存在（15 条记录）
- 上次采集：2026-01-10
- 超阈值指标：2 个（圈复杂度 P95、热点文件占比）
- 运行模式：增量采集 + 预警模式
```