agentleFS
wonderslifewonderslife/pdd-skills-v3/skills/core/pdd-entropy-reduction/SKILL.md

pdd-entropy-reduction

Skill15 starsChanged 28 days agoMITView on GitHub

PDD熵减智能体,持续监控和偿还技术债务,防止系统腐化。触发:熵减、技术债务、代码清理、文档更新、架构对齐、垃圾回收、entropy reduction。

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

Files
SKILL.md

PDD Entropy Reduction Agent - 熵减智能体

"Technical debt is like a high-interest loan: better to repay in small amounts than let it accumulate." —— OpenAI Harness Engineering

目标:通过定期运行智能体发现文档不一致或架构违反,对抗系统熵增与衰减。

熵增 vs 熵减:代码腐化(重复/过长/命名)→重构;文档过时→同步;债务累积(TODO/临时方案)→偿还;架构漂移(依赖方向/边界)→对齐;测试不足→补充。

四大专业子技能

协调器(pdd-entropy-reduction)负责调度和聚合结果,不直接执行具体操作:

  • pdd-doc-gardener:文档园丁,检测代码-文档不一致/注释过时/API不匹配,自动创建修复PR
  • expert-arch-enforcer:架构约束强制,检测依赖方向违规/边界数据缺失/文件过大/命名违规,运行Linter
  • expert-entropy-auditor:熵增审计,检测PRD-代码不一致/AI残渣/分散工具类,归集到共享工具包
  • expert-auto-refactor:自动化重构,检测重复代码/复杂逻辑/命名优化,定期发起重构PR

工作流程

触发(手动/定时/事件) → 扫描(文档/代码/架构) → 分析(熵评分/分类/优先级) → 执行(自动修复/创建PR/更新文档)

熵评分系统(0-100,100=最有秩序):90-100优秀维持 | 70-89良好小幅改进 | 50-69一般计划清理 | 30-49警告优先处理 | 0-29危急紧急重构

维度评分按问题密度折算(100 - 100×sqrt(min(1, 扣分/KLOC ÷ 容忍密度))),使不同规模项目可比、不因代码量大而一律撞底;容忍密度 文档6/架构10/代码45/债务10。详见 references/entropy-report-template.md §1.3。

执行指南

  1. 熵增检测:选择范围 全量/仅文档/仅架构/仅代码
  2. 生成熵减报告:用 references/entropy-report-template.md,含熵评分/问题列表(按优先级)/修复建议/预估工作量
  3. 熵减执行:简单修复(命名/格式)→自动修复提交;中等(文档更新)→创建PR;复杂(重构)→Issue+PR

黄金原则

  1. 使用共享工具包,避免手写辅助函数
  2. 验证边界数据,不猜测数据结构(API入口必须有Schema验证)
  3. 保持代码简洁,优先可读性(单文件≤300行,单函数≤50行)
  4. 文档即代码,保持同步(过时文档=技术债务)
  5. 小额还贷,持续改进(每次commit都是改进机会)

配置文件(entropy-config.yaml)

entropy_reduction:
  triggers: { schedule: "0 2 * * *", on_commit: false, on_pr_merge: true }
  detection:
    docs: { enabled: true, paths: ["docs/", "*.md"], max_age_days: 30 }
    architecture: { enabled: true, layers: ["types","config","repo","service","runtime","ui"] }
    code: { enabled: true, max_file_lines: 300, max_function_lines: 50 }
  execution: { auto_fix: true, create_pr: true, max_pr_per_run: 5 }

输出格式

每次执行后生成报告存到 docs/entropy-reports/:# Entropy Reduction Report - YYYY-MM-DD + 熵评分 + 问题列表(Critical/Warning/Info) + 修复建议与执行结果。

与PDD流程集成

PDD正向流程(PRD→功能提取→规格→实现→验收) ←→ PDD熵减流程(检测→报告→执行→自动修复→PR创建)

Iron Law 铁律

  1. 子技能协调不替代:协调器只调度和聚合,不直接执行子技能具体操作。
  2. 熵评分客观化:基于可量化指标(代码重复率/文档过时率/架构违规数),不得凭主观感觉。
  3. 修复策略分级:按问题类型和严重程度选策略(自动修复/PR/人工),不一刀切。
  4. 变更影响可控:控制单次变更范围(如单次PR≤文件数),避免大规模重构引风险。
  5. 执行结果可度量:每次前后有度量对比(熵分变化/修复数/新问题数),无法度量=没做。
  • 违规:❌直接写修复逻辑不调auto-refactor ❌"感觉代码质量不太好"模糊评分 ❌全自动修复 ❌一次提交50+文件 ❌只说"清理完成"无量化
  • 合规:✅调doc-gardener、arch-enforcer ✅报告"文档过时15%、架构违规2处、重复率8%→72分" ✅Critical自动修复/Warning建PR/Suggestion待观察 ✅单次PR≤5文件 ✅"68→82分,修复Critical 3个"

Rationalization 陷阱

  • "全能选手":协调器想自己完成所有→只负责调度/聚合/报告
  • "模糊评分":评分无量化依据→建立指标+权重+计算方法
  • "暴力清洗":一次性大规模修改→安全阈值(≤5文件/≤100行)
  • "无闭环":执行了未验证→报告含前后对比+回归验证

Red Flags 红旗

  • L1 输入:INPUT-ER-001 项目目录不可访问→🔴;002 config缺失→🔵默认;003 未指定范围→🔵默认全量
  • L2 执行:EXEC-ER-001 协调器直接执行子技能→🟡;002 评分缺量化→🔴;003 单次修复超上限→🔴;004 自动修复未备份→🟡
  • L3 输出:OUTPUT-ER-001 缺前后对比→🔴;002 缺行动计划→🟡;003 声明"已修复"缺证据→🔴
  • 处理:🔴立即停止上报 | 🟡记录警告尝试修复 | 🔵记录正常继续

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.