fluff-detector

冗長表現検出ツール

目的

エージェント、コマンド、スキルが人間の読者向けではなく、LLM 向けに記述されていることを確認します。すべてのトークンは、安心感や信頼性を与えるのではなく、実行の改善に役立つべきです。

使用する場面

• 新しいエージェント、コマンド、スキルの作成時
• LLM 用アーティファクトを追加・変更する PR のレビュー時
• マージ前の品質ゲート
• 既存アーティファクトでトークンの無駄を監査する時

冗長表現のカテゴリ

1. 出典を示す表現

人間に信頼性を示すものの、LLM にとって価値のない内容です。

パターン	例	問題
「X に着想を得た」	「DHH のアプローチに着想を得た」	LLM は著者を手がかりに取得できません
「X の方法論に基づく」	「Martin Fowler のパターンに基づく」	信頼性を示すだけの表現です
「X によると」	「業界の専門家によると」	権威への訴えです
「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. ペルソナの冗長表現

LLM に何をすべきかではなく、「何者であるか」を伝える役割の説明です。

パターン	例	改善案
アイデンティティの表明	「あなたはシニアエンジニアです」	（削除）
能力の主張	「あなたは……に深い専門知識を持っています」	（削除）
性格の特徴	「あなたは親切で、丁寧です」	（削除）
自己言及	「AI アシスタントとして……」	（削除）

検出パターン：

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

4. 重複した説明

LLM がすでに知っている、または推測できることを説明する表現です。

パターン	例
ツールの説明	「Read ツールを使うとファイルを読み取れます」
明白な文脈	「このエージェントは……に使用されます」
メタコメント	「次のセクションでは……について説明します」
形式の説明	「出力は……の形式にしてください」（形式を示している場合）

検出パターン：

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

5. マーケティング表現

LLM 向けの指示には不適切な、宣伝または販売を目的とした表現です。

パターン	例
最上級表現	「クラス最高」「世界クラス」「最先端」
成果の保証	「完璧な結果を実現」「成功を保証」
流行語	「革新的」「画期的」「次世代」
曖昧な主張	「非常に効率的」「極めて強力」

検出パターン：

(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

すべてのエージェントの検証

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	エラーが見つかりました（処理がブロックされます）