slop-eval

slop-eval

クイックスタート • CLI リファレンス • ライブラリ API • MCP サーバー • 比較 • FAQ

LLM の判定によって、AI が生成した UI のありきたりさを評価します。CI チェックで、人間のレビュアーが見ればすぐに指摘する「どれも他の AI 製アプリと同じに見える」という問題を検出できます。

npx slop-eval-cli score --screenshot ./preview.png --json

インストール手順は不要です。npx が公開済みの npm パッケージを直接取得して実行します。Python をお好みですか？pip install slop-eval-cli を実行すると、スコアリングロジックを独立して移植した、本格的な同一 CLI を利用できます。

npm と Python の 2 つの配布形態を公開中

slop-eval-cli は npm と PyPI（パッケージ名 slop_eval）の両方で公開中です。Python 版は、TypeScript 版と同じ評価基準および Anthropic の判定プロンプトに基づいて、独立して実装・ビルド・テストされた移植版です（この検証では 60 件中 60 件のテストに合格しました）。Python 固有の使い方については、python/README.md を参照してください。

このツールが存在する理由と、そうではないもの

21,000 以上のスターを獲得している人気の AI デザインスキル、Nutlope の Hallmark には、あるユーザーが「全部がスロップに見える」と率直に述べた未解決の Issue があります。メンテナーはこれを NOT_PLANNED としてクローズしました。また別の寄稿者が Hallmark に対し、「Hallmark の出力向けに評価駆動型の品質ハーネスを追加」というタイトルの PR を作成しましたが、本稿執筆時点で約 2 か月間、未マージのままオープンになっています。どちらも本稿執筆時点で実在し、日付も確認できます。需要が大きいことを証明するものではありませんが、このギャップが実在し、現在も解消されていないことを示しています。

slop-eval はこの分野で初めてのツールではなく、初めてを目指しているわけでもありません。すでに近い領域には、無料で利用できる実在のツールが 2 つあります。

• Impeccable（pbakaus/impeccable、スター 54,000 以上、Apache 2.0）は、AI 生成 UI に見られる 59 種類の具体的な視覚的特徴（グラデーションパレット、グラスモーフィズム、側面のストライプ状ボーダー、WCAG のコントラスト違反など）を検出する CLI を提供しています。モデル呼び出しは不要で、すべてがデフォルトで有効です。別の impeccable critique コマンドでは、追加のオプトイン方式による LLM ベースの判定も利用できます。デフォルトのチェックにはモデルが不要なため、コアとなる検出は高速です。Claude Code、Cursor、Codex 向けの包括的なデザイン言語スキルへと発展しており、合計 23 個のコマンドを備えています。
• aislop（MIT、スター 500 以上）は、AI 生成の コード（UI ではありません）に対して、決定論的なルールベースの検出を行います。8 言語を対象とする 50 以上の正規表現／AST ルールを備え、実行時に LLM は使わず、CI 品質ゲートとして明確に位置づけられています。

どちらも、総合的な判断に基づく UI スコアリング、つまり「このレイアウトは新鮮に感じられるか」「このコンポーネントの選択には考慮が感じられるか」といった、固定ルールでは簡単に表現できない種類の評価には対応していません。slop-eval はこのギャップを埋めるものであり、Impeccable のようなツールに取って代わるのではなく、それらと組み合わせて使えるように設計されています。

特長

このリポジトリのコードと直接照合して確認済みです。

• 3つの評価カテゴリ。それぞれに必須の引用付き根拠。 src/rubric/v1.json では、レイアウトの新規性、ビジュアルアイデンティティの独自性、コンポーネントパターンの新規性を、それぞれ0〜10点で評価します。具体的な引用がない指摘は、有効なスコアではなくバグとして扱われます（src/sources/RuleSource.ts を参照）。
• 強制ツール呼び出しによるLLM評価。構造化JSONを返します。 LLMJudgeSource は tool_choice を submit_slop_scores スキーマに固定してAnthropic APIを呼び出します。レスポンスは、正規表現で分解しなければならないチャット返信ではなく、信頼性の高い構造化JSONとして返されます。
• CIやエージェント向けの --json モード。 どの実行でも、成功時・エラー時の両方で、解析可能な { target, rubric, compositeScore, findings[], summary, disclaimer } オブジェクトを標準出力に出力できます。そのため、スクリプトやエージェントはエラー文字列を見つけるために出力形式を判別する必要がありません。
• 実際の終了コード仕様。 0 は成功（しきい値がない場合、またはスコアが --fail-below 以上の場合）、1 は成功だがしきい値未満、2 は使用方法のエラーまたは回復不能な失敗です。このセッションでは、ビルド済みCLIと実際のnpm/PyPIパッケージを使って直接確認しました。CLIリファレンスを参照してください。
• コンテンツハッシュによるキャッシュ。 src/cache/judge-cache.ts は入力バイト列のハッシュを計算し、変更のない入力に対する再実行ではAPI呼び出しを完全に省略します。これはコスト削減だけでなく、正確性を保証するものでもあります。変更のないPRで、LLMの実行ごとのばらつきによってCIゲートの結果が揺れることはありません。
• 組み合わせ可能な RuleSource プラグインインターフェース。 src/sources/RuleSource.ts は、すべての評価ソースが実装する境界です。現在は実際のソースが1つ（LLMJudgeSource）、仕様として記載されたスタブが1つ（ScreenshotDiffSource。実際にラベル付けされたコーパスができるまでは、正直に not_scored と報告されます）です。そのため、将来ルールカタログや2つ目のLLMプロバイダーを追加しても、複合スコアラーを変更する必要はありません。
• スクリーンショット入力（実際のビジュアル判定）、または --url による代替。 --screenshot は、実際にレンダリングされた画像を評価に送ります。--url は、v0.1における制約として記載されています。同梱のヘッドレスブラウザーはないため、生のHTML/テキストを取得し、レイアウトではなくマークアップとコピーをもとに評価します。
• 具体的な指摘を最初に示し、続けてスコアを記載するGitHub Action。 action/action.yml は、最も具体的なフラグ付き指摘を先頭に、その後に複合スコアを記載したPRコメントを投稿し、レビュー担当者にスコアの根拠を伝えます。
• バージョン管理された公開ルーブリック。 各スコアには、その算出に使用したルーブリックのバージョン（現在は v1）が記載されます。ルーブリックの変更は新しいファイルとして提供され、既存のファイルが通知なしに編集されることはありません。
• CLIと並ぶ、実際に使えるエージェントネイティブなライブラリAPI。 どちらの配布形式も、プログラムから呼び出すエントリーポイント（Pythonでは score_composite など、TypeScriptでは runScore／scoreComposite）をエクスポートするため、エージェントフレームワークはシェルコマンドを実行せずに、プロセス内でslop-evalを呼び出せます。ライブラリAPIを参照してください。

クイックスタート

Node.js 18+（npm）またはPython 3.9+（PyPI）と、ANTHROPIC_API_KEY が必要です（BYOキー。console.anthropic.comで取得できます）。

ローカルでのクローンやビルドが不要な最短の方法は、このREADMEの冒頭にあるワンライナーです。

npx slop-eval-cli score --screenshot ./preview.png --json

このセッションでは、実際の公開済みnpmパッケージを使い、./preview.png に実際のPNGを用意し、ANTHROPIC_API_KEY を設定しない状態で確認しました。

$ npx --yes slop-eval-cli@latest score --screenshot ./preview.png --json
{
  "error": "ANTHROPIC_API_KEY environment variable is not set.\nslop-eval calls the Anthropic API to run the LLM judge, and is BYO-key (bring your own key) -- there is no default or shared key baked into this tool. Set your key and try again:\n\n  export ANTHROPIC_API_KEY=\"sk-ant-...\"\n\nGet a key at https://console.anthropic.com/"
}
# exit code 2

ソースからビルドする場合：

git clone https://github.com/RudrenduPaul/slop-eval.git
cd slop-eval
npm install
npm run build

export ANTHROPIC_API_KEY="sk-ant-..."
./dist/cli.js score --screenshot ./test/fixtures/sample.png

CIやエージェントで利用する場合は、--json を追加してください。--json は成功時・エラー時のどちらでも、常に有効なJSONオブジェクトを標準出力に出力します。--url と --screenshot の同時指定チェックは、解析可能であることを信頼できる実際の使用方法エラーの例です。

./dist/cli.js score --screenshot ./test/fixtures/sample.png --json

{
  "target": "./test/fixtures/sample.png",
  "rubric": "v1",
  "compositeScore": 62,
  "findings": [
    {
      "ruleId": "llm-judge.layout-novelty",
      "category": "Layout novelty",
      "score": 4,
      "evidence": "Matches a common hero + 3-card grid + footer CTA pattern.",
      "status": "flag"
    }
  ],
  "summary": { "pass": 1, "flagged": 1, "notScored": 1 },
  "disclaimer": "This score is a heuristic quality signal from an LLM judge, not a certification..."
}

CLI リファレンス

このセッションでビルドした CLI 上で ./dist/cli.js score --help を直接実行し、一言一句そのまま取得した内容です。

Usage: slop-eval score [options]

Score a URL or screenshot for AI-UI genericness against a versioned rubric.

Note on --url mode (v0.1 limitation): this tool does not bundle a headless
browser. If --url is given, the raw HTML/text response is fetched and given to
the judge as a fallback input, instead of a rendered screenshot -- the judge
can reason about markup and copy, but not the actual visual layout. For the
stronger, layout-aware signal, render the page yourself and pass --screenshot.

Options:
  --url <url>          URL to score (fetched as raw HTML/text -- see
                        limitation note above)
  --screenshot <path>  path to a screenshot image to score (preferred over
                        --url)
  --rubric <name>       rubric version to use, reads src/rubric/<name>.json
                        (default: "v1")
  --json                output structured JSON instead of a human-readable
                        report (default: false)
  --fail-below <n>      exit code 1 if the composite score is below this
                        threshold (0-100); no threshold by default
  -h, --help             display help for command

終了コード：0 成功（しきい値の指定がない場合、またはスコアが --fail-below 以上の場合）、1 成功だがしきい値未満、2 使用方法エラーまたは回復不能な失敗（API キーがない、ファイルを読み取れない、ルーブリックの形式が不正、--url と --screenshot の併用）。

--url と --screenshot は同時に指定できません。両方を指定した場合も、どちらも指定しなかった場合も、どちらの出力モードでも使用方法エラー（終了コード 2）になります。このセッションでビルドした CLI を使い、どちらのケースも直接検証しました。

メモ

--url は設計上、v0.1 の制限があります。ヘッドレスブラウザーは同梱されていません。生の HTML／テキストを取得し、レンダリングされたレイアウトではなくマークアップと文言を評価するテキストの代替手段として判定モデルに渡します。より強いシグナルとなるのは --screenshot です。ページを自分でレンダリングし（Playwright、Puppeteer、または CI で既に使用しているプレビュー画像の取得手順など）、画像を渡してください。

Python CLI（pip install slop-eval-cli でインストールするコンソールスクリプト slop-eval）も、同一のフラグセットと終了コードの仕様を提供します。このセッションで --help の出力を使って確認しました。

ライブラリ API

どちらのディストリビューションも、CLI に加えて、実際に利用できるドキュメント付きのプログラムエントリーポイントを公開しています。これは、エージェントフレームワークや CI スクリプトがシェルコマンドを実行する代わりに、プロセス内で呼び出すインターフェースです。

Python（slop_eval/__init__.py）：

from slop_eval import score_composite, ScoreInput, LLMJudgeSource, ScreenshotDiffSource

sources = [LLMJudgeSource("v1"), ScreenshotDiffSource()]
result = score_composite(sources, ScoreInput(screenshot_path="./preview.png"))
print(result.composite_score, result.findings)

score_composite(sources: List[RuleSource], score_input: ScoreInput) -> CompositeResult は、すべての RuleSource をリスト順に実行し、各評価結果をまとめて、composite_score: float（0～100）と findings: List[RuleFinding] を含む CompositeResult を返します。そのほか、RuleFinding、RuleFindingStatus、RuleSource、Rubric、RubricCategory、load_rubric、build_json_report、render_human_report、print_report、print_error、MissingApiKeyError、RubricLoadError もエクスポートされています。

TypeScript（src/cli.ts。パッケージの main／types エントリーポイントからエクスポート）：runScore(options: ScoreOptions, buildSources?) => Promise<number> と buildProgram(): Command の 2 つがエクスポートされたエントリーポイントで、ScoreOptions インターフェースも公開されています。scoreComposite（src/scorer/composite.ts）は、CLI が内部で呼び出す複合スコアリング関数と同じものです。これらは主に、テストスイートからプロセス内で CLI を実行するために用意されています。2 つのうち、Python パッケージの __init__.py のほうが、エージェントが直接利用するライブラリのインターフェースとして、より明確にドキュメント化されています。

MCP サーバー

slop-eval には Model Context Protocol サーバーが付属しているため、MCP 対応エージェント（Claude Desktop、Claude Code、Cursor、オーケストレーター）は、CLI をシェルから実行して標準出力を解析する代わりに、ツールとして slop-eval を直接呼び出せます。

pip install "slop-eval-cli[mcp]"

Claude Desktop の設定：

{
  "mcpServers": {
    "slop-eval": {
      "command": "slop-eval-mcp",
      "env": { "ANTHROPIC_API_KEY": "sk-ant-..." }
    }
  }
}

サーバーは run(args: list[str]) -> dict というツールを 1 つ公開します。これは CLI の汎用ラッパーです。コマンドラインで渡すものと同じ argv（先頭の slop-eval を除く）を渡すと、CLI の解析済み JSON 出力を返します。終了コードが 0 以外の場合、タイムアウトした場合、またはサブプロセスでエラーが発生した場合は、構造化された {"error": ...} の dict を返します。ツール呼び出し自体が例外を送出することはありません。例：

run(["score", "--screenshot", "./preview.png", "--json"])
# -> {"result": {"target": "./preview.png", "rubric": "v1", "compositeScore": 62.0, "findings": [...], ...}}

stdio トランスポートで slop-eval-mcp を直接実行して起動します。ベースパッケージには Python 3.9 以降が必要です。mcp エクストラ自体には mcp>=2.0.0 が必要です。

GitHub Action

- uses: RudrenduPaul/slop-eval/action@main
  with:
    url: ${{ steps.deploy.outputs.preview_url }}
    fail-below: 50
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

最も具体的なフラグ付き評価結果を先頭に、その後に複合スコアを続ける PR コメントを投稿します。呼び出し元のワークフローに permissions: pull-requests: write が必要です。入力と出力の完全なリファレンスは action/README.md にあります。

正直な比較

	slop-eval	Impeccable	aislop
対象	AI 生成の UI	AI 生成の UI	AI 生成の コード
検出方法	LLM による判定（総合的）	決定論的なルール。デフォルトで 59 項目をチェック。別の critique コマンドでは、オプトインで追加の LLM 判定を実行	決定論的なルール（50 項目以上をチェック）
API キーが必要か	はい（Anthropic キーは利用者が用意）	デフォルトの決定論的な 59 項目のチェックでは不要	いいえ
速度	設計上、遅めです。実際のモデル呼び出しがクリティカルパスに含まれます	決定論的なチェックはほぼ即時	1 秒未満。ネットワーク呼び出しなし
構成可能なルールソース	はい。RuleSource プラグインインターフェースがあります	いいえ（固定のルールセット）	いいえ（固定のルールセット）
GitHub のスター数	新規（このリポジトリ）	54,000+	500+
ライセンス	Apache 2.0	Apache 2.0	MIT
CI ゲートの方式	GitHub Action、--fail-below のしきい値	主に CI 製品として位置付けられているわけではありません	はい、CI 品質ゲート

既知の AI 生成 UI の特徴を、速く、決定論的に、無料でチェックしたい場合は、現時点では Impeccable のツールがより適しています。スター数と対応範囲から見ても、はるかに確立されたプロジェクトです。固定のルールセットでは簡単に表現できない、レイアウトやコンポーネントの新規性に関する総合的な判断を求める場合、それが slop-eval の追加する価値です。同じ CI ジョブで両方を実行することもできます。

速度について： slop-eval は、クリティカルパスに LLM 呼び出しが含まれるため、Impeccable のコアチェックや aislop より実際に遅くなります。新規クローンとビルドを使ってこのセッション中に測定した、CLI オーバーヘッドの実測値です（--help とエラーパス。スコアリング呼び出しはありません）。

コマンド	実測時間
slop-eval score --help	約 0.05 秒
slop-eval score --screenshot <x>（API キーなし。即時に失敗し、ローカルファイルの読み取りのみ）	約 0.05 秒
slop-eval score --url <x>（API キーなし。即時に失敗）	0.18～0.91 秒。キーのチェックより先に URL を取得するため、ネットワーク遅延によって変動します

実際のスコアリング実行のレイテンシ（実際の LLM 判定呼び出し。キャッシュなし／キャッシュあり）を測るには、この環境にはない有効な ANTHROPIC_API_KEY が必要です。そのため、以下の 2 つの数値は実測待ちの目標値です。キャッシュなしでは 10 秒未満、同一入力でキャッシュがヒットした場合は 1 秒未満です。キャッシュヒット時の数値は、src/cache/judge-cache.ts のコンテンツハッシュキャッシュのロジックによって保証されています。キャッシュなしの数値は推定値です。再現できない数値を断言するより、目標値であると明記することを選びます。

スコアが示すもの（および示さないもの）

slop-eval のスコアは、明示されたルーブリックに照らして、ある LLM が UI を評価したヒューリスティックな品質指標です。AI 生成かどうかを認定するものではなく、スコアが良好でも、あらゆる基準で UI が優れているという意味ではありません。このバージョンのこのルーブリックでは、問題が指摘されなかったというだけです。

ルーブリックは公開され、バージョン管理されています

すべてのスコアは、実際に存在するバージョン管理済みのファイル src/rubric/v1.json に基づいて評価されます。このファイルは直接開いて読むことができます。内容を確認して変更を提案したり、--rubric で特定のバージョンを指定したりできます。ルーブリックのバージョンがその場で編集されることはありません。変更は新しいファイルとしてリリースされるため、過去のスコアには、そのスコアを算出したルーブリックが常に記録されます。

ロードマップ

• v0.1（今回のリリース）： LLM による判定、CLI、GitHub Action、コンテンツハッシュキャッシュ、--json モード、両方のディストリビューションでのライブラリ API。
• v0.2： 実際にラベル付けされたコーパスが整った時点で、ScreenshotDiffSource を実用化します。ライセンス確認を前提とする Impeccable カタログアダプター。ルーブリックの更新が黙って行われないよう、明示的な rescore --rubric v2 コマンドを追加します。

セキュリティ

ANTHROPIC_API_KEY は環境変数からのみ読み込まれ、ログに記録されたり、コンテンツハッシュキャッシュに書き込まれたりすることはありません。完全なポリシーと非公開の脆弱性報告プロセスについては、SECURITY.md を参照してください。

よくある質問

slop-eval とは何ですか？リンターとはどう違いますか？ 汎用的な見た目（「slop」）を評価する、CLI、GitHub Action、ライブラリです。固定された決定論的なパターンチェックではなく、バージョン管理されたルーブリック（src/rubric/v1.json）を使い、Anthropic の LLM に判定させて AI 生成 UI を評価します。人間のレビュアーが見たときに感じる「どれも同じような AI 製アプリに見える」という印象を捉え、同じ CI ジョブやエージェントのループ内で決定論的なリンターと併用できるように設計されています。

API キーは必要ですか？ はい。slop-eval は Anthropic API 用の BYOK（独自のキーを持ち込む方式）で、共有キーやホスト済みのキーはありません。Anthropic API 以外に情報が送信されることはありません。

インストール方法と、対応プラットフォームを教えてください。 独立した 2 種類の配布方法があり、どちらもこのセッションでインストールと実行を確認済みです。npm：npx slop-eval-cli score ...（インストール不要）、または npm install -g slop-eval-cli。Node.js 18 以降が必要です（package.json の engines を参照）。PyPI：pip install slop-eval-cli。Python 3.9～3.13 が必要です（python/pyproject.toml の分類子を参照）。どちらのパッケージにもネイティブバイナリやプラットフォーム固有のビルド手順はないため、macOS、Linux、Windows のいずれでも同じ方法でインストールできます。

slop-eval は Impeccable と具体的にどう違いますか？ 詳細は、上記の公正な比較の表をご覧ください。簡単に言うと、Impeccable の中核は決定論的なチェック 59 項目で、すべてデフォルトで有効になっており、API キー不要でほぼ瞬時に実行できます。また、プロジェクト自体は slop の検出にとどまらず、はるかに大規模なデザイン言語スキルへと発展しています（スター 54,000 件以上、コマンド 23 個）。別個の critique コマンドを使うと、決定論的なチェックに加えて LLM による判定も実行できます。slop-eval は Anthropic のキーを独自に用意する必要がある単一の LLM 判定呼び出しで、実際のモデル呼び出しがクリティカルパスに含まれるため、意図的に処理が遅くなっています。その代わり、固定ルールでは簡単に表現できない、レイアウトやコンポーネントを総合的に判断できます。どちらも同じ CI ジョブで一緒に実行できるように設計されています。

別のモデルプロバイダー（OpenAI、Gemini）を使えますか？ v0.1 では使えません。LLMJudgeSource は Anthropic API を直接呼び出します。ANTHROPIC_MODEL で選べるのは、別の Anthropic モデルだけです。後にプラグイン可能なプロバイダーを RuleSource インターフェースに追加するのは自然な拡張ですが、まだ実装されていません。そのため、現時点で「組み合わせ可能なルールソース」が「複数プロバイダー対応」を意味すると解釈しないでください。

--url はブラウザーのようにページをレンダリングしますか？また、スコアの実行に失敗した場合はどうなりますか？ いいえ、v0.1 ではレンダリングしません。--url は生の HTML／テキストレスポンスを取得し、フォールバックとして判定に渡します。実際の見た目を評価するには、自分でページをレンダリングして --screenshot を渡してください。一般に、ANTHROPIC_API_KEY が設定されていない場合を含むすべてのエラーパスは、コード 2 で終了し、明確なメッセージを表示します（--json モードでは {"error": ...} オブジェクトを表示します）。そのため、実行に失敗した場合も、何を修正すればよいか必ず分かります。

同じ PR で slop-eval を再実行すると、CI チェックの結果が変わることはありますか？ いいえ。同一の入力（同じスクリーンショットのバイト列、または同じ URL と取得したコンテンツ）では、src/cache/judge-cache.ts のコンテンツハッシュキャッシュが使われ、API は再度呼び出されません。そのため、同じ入力には常に同じキャッシュ結果が返されます。

screenshot-diff-vs-corpus は現在、実際にチェックを行いますか？ いいえ。コード内では実際の RuleSource 実装ですが、比較用のラベル付きコーパスがまだ存在しないため、v0.1 では正直に not_scored を返すスタブとして提供されています。検証されていないコーパスを手作業で用意するより、「スコア対象外」と報告するほうが、より誠実なシグナルになります。コーパスに基づく差分評価は v0.2 で予定されています。

クローズドソース製品を含め、slop-eval を商用利用できますか？ はい。どちらの配布物も Apache 2.0（LICENSE、python/LICENSE）で、商用利用、改変、クローズドソースでの再配布を認める寛容なライセンスであり、明示的な特許許諾も含まれています。クローズドソースのプロジェクトから CLI、Action、ライブラリを呼び出しても、ソースを公開する義務はありません。再配布する slop-eval 自身のコードに、ライセンスと著作権表示を同梱する必要があります。

貢献

Issue や PR を歓迎します。CONTRIBUTING.md をご覧ください（npm パッケージと Python パッケージの両方、およびパッケージごとのカバレッジ要件について記載されています）。新しい RuleSource の実装は、最も効果の高い貢献です。新しい検出方法を追加しても、複合スコアラーに手を加える必要がないよう、プラグインインターフェースが用意されています。

ライセンス

Apache 2.0。詳細は LICENSE をご覧ください。