fluff-detector

冗余内容检测器

用途

验证 Agent、命令和技能是否面向大模型编写，而非面向人类读者。每个词元都应有助于执行，而不是提供安慰或可信度。

适用场景

• 创建新的 Agent、命令或技能
• 审查新增或修改大模型制品的 PR
• 合并前的质量门禁
• 审计现有制品中的词元浪费

冗余内容类别

1. 归属信号

旨在为人类建立可信度、但对大模型毫无价值的内容。

模式	示例	问题
“受 X 启发”	“受 DHH 的方法启发”	大模型无法按作者检索
“基于 X 的方法论”	“基于 Martin Fowler 的模式”	纯粹的可信度信号
“根据 X”	“根据行业专家的说法”	诉诸权威
“正如……所建议的”	“正如 Google 所建议的”	对执行没有帮助

例外： 定义某种风格的名称（例如，“DHH 风格的 Rails”）具有实际作用，并非归属信息。

检测模式：

(inspired by|based on|according to|as recommended by|following|using|applying)\s+[A-Z][a-z]+('s)?

2. 装饰性引言

没有实际价值的励志或哲理引言。

模式	示例
题词	“最好的代码就是没有代码”——某人
哲理	“秉持简约精神……”
激励	“优秀的工程师总是……”

检测模式：

^>\s*[""].*[""].*[-—]\s*[A-Z]
[""][^""]{20,}[""][\s]*[-—]

3. 人设冗余

描述大模型“是什么”，而不是告诉它该做什么的角色说明。

模式	示例	更好的做法
身份陈述	“你是一名资深工程师”	（删除）
能力声明	“你在……方面拥有深厚的专业知识”	（删除）
个性特征	“你乐于助人且做事周全”	（删除）
自我指涉	“作为一名 AI 助手……”	（删除）

检测模式：

^(You are|As an?|I am|Acting as)\s+(a |an |the )?[a-z]+(ly)?\s+(and\s+[a-z]+\s+)?

4. 冗余解释

解释大模型已经知道或可以推断的内容。

模式	示例
工具说明	“Read 工具可用于读取文件”
显而易见的上下文	“此 Agent 用于……”
元评论	“以下部分将介绍……”
格式说明	“输出应采用……格式”（已展示格式时）

检测模式：

(this (agent|skill|command) (is used|helps|allows|enables))
(the following (section|content|instructions))
(as (shown|described|mentioned) (above|below|previously))

5. 营销用语

不适用于大模型指令的宣传或销售用语。

模式	示例
最高级表述	“一流”“世界级”“尖端”
承诺	“确保完美结果”“保证成功”
流行词	“革命性”“颠覆性”“下一代”
含糊的断言	“高效”“极其强大”

检测模式：

(best-in-class|world-class|cutting-edge|state-of-the-art|revolutionary|game-chang|next-gen|highly efficient|extremely powerful|ensures? (perfect|optimal)|guarantee)

6. 模糊措辞

毫无价值的不确定性表达。

模式	示例	更好的做法
“尝试”	“尝试遵循最佳实践”	“遵循最佳实践”
“设法”	“设法减少错误”	“减少错误”
“考虑”	“考虑使用 X”	“在 Y 时使用 X”
“也许”	“也许添加验证”	“如果满足 X，则添加验证”

检测模式：

\b(try to|attempt to|consider\s+(using|adding|implementing)|you (might|may|could) want to|perhaps|maybe)\b

7. 填充短语

不提供任何信息、仅用于凑字数的短语。

模式	删除
“需要指出的是”	✓
“请记住”	✓
“不言而喻”	✓
“毋庸赘言”	✓
“为了”	改用“以”
“由于……这一事实”	改用“因为”
“在当前这个时间点”	改用“现在”

检测模式：

(it('s| is) (important|worth|crucial) to (note|mention|remember)|please (keep in mind|note|remember)|goes without saying|needless to say|in order to|due to the fact|at this point in time|as a matter of fact|for all intents and purposes)

用法

验证单个文件

./scripts/detect-fluff.sh path/to/file.md

验证所有 Agent

for agent in plugins/*/agents/**/*.md; do
  ./scripts/detect-fluff.sh "$agent"
done

CI 集成

- name: Detect Fluff
  run: |
    find plugins -name "*.md" -path "*/agents/*" -o -name "*.md" -path "*/skills/*" -o -name "*.md" -path "*/commands/*" | while read f; do
      .claude/skills/fluff-detector/scripts/detect-fluff.sh "$f" || exit 1
    done

输出格式

Analyzing: plugins/majestic-engineer/agents/qa/test-reviewer.md

[WARN] Line 12: Attribution signal
  > "Based on Kent Beck's TDD principles"
  Suggestion: Remove attribution or rephrase as pattern name

[WARN] Line 45: Persona fluff
  > "You are an expert test reviewer with deep knowledge"
  Suggestion: Delete - LLM doesn't need identity statements

[WARN] Line 78: Filler phrase
  > "It's important to note that tests should be isolated"
  Suggestion: "Tests should be isolated"

Summary: 3 fluff instances found

严重级别

级别	操作	示例
ERROR	必须修复	人设陈述、营销用语
WARN	应当修复	归属信息、模糊措辞、填充语
INFO	可考虑修复	冗余解释（可能是有意为之）

误报处理

某些模式有合理用途：

模式	合理用途
"Based on"	"Based on user input"（并非归因）
"Consider"	在带有条件的决策树中
名字	定义风格时（DHH、Warren Buffett）

该脚本会进行上下文分析，以减少误报。

错误代码

代码	含义
0	未检测到冗余内容
1	发现警告（不阻塞）
2	发现错误（阻塞）