devbooks-entropy-monitor

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、热点文件占比）
- 运行模式：增量采集 + 预警模式