entropy-management

熵管理（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 — 深入调查发现的问题