| name | entropy-management |
| description | 定期维护代码库健康度。扫描架构漂移、过期文档、低质量代码,防止技术债积累。应在完成若干任务后或怀疑代码库退化时触发。 |
熵管理(Garbage Collection)
概述
AI Agent 会复制仓库中已有的模式——包括不好的模式。随着时间推移,这不可避免地导致漂移。
手动清理不可持续。熵管理将清理系统化,定期执行,像垃圾回收一样防止技术债积累。
核心原则:技术债是高利贷——持续小额偿还远优于积累后大规模清理。
铁律
发现的问题不能只修一次——必须同时编码为约束,防止再次发生。
每次熵管理运行结束后,必须更新质量评分和技术债追踪。
触发条件
- 完成 5 个以上任务后(定期维护)
code-reviewer 审查中反复出现同类问题(模式漂移信号)
- 用户主动要求代码库健康检查
- 怀疑文档与代码不一致
- 新成员加入前(确保仓库状态良好)
执行流程
第一阶段:自动化传感器扫描
运行 Harness 传感器套件收集机器可检测的问题:
node scripts/hooks/dispatcher.cjs stop
记录所有 [FAIL] 和 [WARN] 项。
第二阶段:推理型扫描
自动化传感器无法覆盖的维度,需要人工/Agent 推理检查:
2.1 文档-代码一致性
| 检查项 | 方法 |
|---|
| CLAUDE.md 引用路径是否有效 | 逐条验证文件/目录存在 |
| docs/ 文档描述是否匹配实际行为 | 抽样对比 |
| SKILL.md 中的流程是否被实际遵循 | 回顾近期任务记录 |
| 模板是否与当前实践一致 | 对比模板与近期产出 |
2.2 架构漂移检测
| 检查项 | 方法 |
|---|
| 是否有文件放在错误目录 | 检查目录约定是否被遵守 |
| 是否有重复/冗余文件 | 搜索相似文件名和内容 |
| 技能包结构是否一致 | 抽样检查 SKILL.md 格式 |
| 协作产物是否在正确位置 | 检查 .orchestration// 结构 |
2.3 质量回归检测
| 检查项 | 方法 |
|---|
| 近期审查中的高频问题 | 分析 .orchestration//code-reviewer/ |
| 是否有被跳过的工作流阶段 | 检查产物完整性 |
| 是否有"沉默的传感器"(从不报错) | 评估传感器有效性 |
第三阶段:修复与编码
对发现的问题分类处理:
| 问题类型 | 处理方式 |
|---|
| 可快速修复的具体问题 | 立即修复(文档更新、文件移动等) |
| 需要编码为约束的重复模式 | 在 scripts/hooks/checks/ 加 check,让违规自动触发 [FAIL] |
| 需要架构讨论的系统性问题 | 与用户讨论;动手前先达成共识 |
第四阶段:沉淀与追踪
把本次发现和处理沉淀到下列位置(按相关性挑,不必每次都全做):
- 反复出现的违规模式 → 在
scripts/hooks/checks/ 加自动化 check
- 团队级架构决策 / 新约束 → 写进
docs/PROJECT_CONTEXT.md 或 docs/ARCHITECTURE.md
- 跨会话需要记得的代码模式 → 写进
docs/rules/<topic>.md 或 docs/red-flags.md
- 用户当前活跃状态 / 个人偏好 → 让 Claude 写进原生 memory(
~/.claude/projects/<slug>/memory/,自动加载)
- 新增的危险信号 → 加入
docs/red-flags.md
- 新增的强制规则 → 加入
docs/rules/<topic>.md
产出清单
每次熵管理运行后,应产出:
✅ dispatcher 扫描结果(node scripts/hooks/dispatcher.cjs stop)
✅ 推理型扫描发现清单
✅ 修复的问题列表
✅ 新增的约束 / check / 规则文档(如有)
Red Flags — 停下来
| 信号 | 行动 |
|---|
| 传感器全部通过但直觉上代码库有问题 | 传感器覆盖不足,加新 check |
| 修复一个漂移又发现三个 | 可能是架构问题,先与用户讨论再动 |
| 反复出现同类问题但没有沉淀为约束 | 必须在 scripts/hooks/checks/ 加自动检测 |
关联技能
- verification-before-completion — 修复后验证
- systematic-debugging — 深入调查发现的问题