code-slop

コードの過剰生成パターンの検出

AI が生成したコードにありがちなパターンを、コードの質に関する観点からレビューします。コメント、命名、過剰な設計、過剰な防御、テストの過剰生成パターン、スタイルの特徴を網羅する、6 カテゴリ・24 ルールです。technical-debt がコードの負債を 定量的 に（複雑さ、重複、CVE）測定するのに対し、このスキルは 定性的 な失敗パターンを測定します。つまり、すべての指標をクリアしていても、人間ではなくチュートリアルブログのように読めるコードです。

メタデータ

• バージョン： 1.0.0
• 対象範囲： PHP / Laravel + TypeScript / React（Node）
• ルール数： 6 カテゴリ・24 ルール
• ライセンス： MIT

このスキルが存在する理由

AI 支援によるコードに関する業界データ（GitClear 2025、cURL のバグ報奨金プログラム終了 2025、arXiv 2510.03029）：

• リファクタリングが減少し、変更全体に占める割合は 25% から 10% 未満に
• コピー＆ペーストが急増し、8.3% から 12.3% に。コードの重複は約 8 倍に増加
• コードの不吉な兆候が 42～85% 増加し、人間によるベースラインを上回る
• AI による PR の 82% が、エラーの種類を区別しない汎用的な catch ブロックを使用
• 76% が外部呼び出しのタイムアウトを設定していない

こうした問題は、一般的な CI の lint では検出されません。コードベースを徐々に保守不能にするだけです。このスキルは、コードがリリースされる前に問題を見つけるための視点です。

核心となる洞察は、今やコードを読むコストのほうが書くコストより大きいということです。コードを書くコストは急激に下がりましたが、読むコストは下がっていません。動作していても、すぐに理解できないコードは過剰生成されたコードです。

監査方法

ユーザーから「AI による過剰生成パターンをレビューして」「コード品質のセンスを監査して」「AI のパターンを見つけて」と依頼された場合は、このスキルのルールをチェックリストとして使用し、変更されたファイル（PR の差分）またはリポジトリ全体を確認します。

監査ステップ 1：対象範囲を決める

• PR の差分が提供されている場合：差分で変更されたファイルのみを監査します
• ファイル名が指定されている場合：指定されたファイルを監査します
• 対象範囲が指定されていない場合：最近変更されたファイル（AI が生成した可能性が高いもの）を優先して、リポジトリ全体を監査します

監査ステップ 2：スタックを検出する

シグナル	スタック
composer.json + artisan	PHP / Laravel
package.json（TypeScript/React の依存関係を含む）	Node / TypeScript / React
両方存在	Laravel + Inertia + React

監査ステップ 3：過剰生成パターンのチェックリストを実行する

以下の各項目について、次のいずれかを出力します。

• 問題なし（CLEAN） — パターンは見られません（簡潔に確認内容を記載）
• 要注意（SUSPICIOUS） — 少量ながら見られます。指摘して説明します
• 過剰（INFLATED） — 広範囲に見られます。冗長ですが機能しており、修正を推奨します
• 重大（CRITICAL） — AI に特有のパターンが広範囲に見られます。マージ前に全面的なレビューが必要です

コメント

• コードの内容をそのまま説明するコメントがない（User::create(...) の上にある // create user など）
• 空のドックブロックがない（getUser() の上にある /** Get user */ など）
• プレースホルダーのコメントが残っていない（// TODO: implement、// your code here、// implementation など）
• 閉じ波かっこにラベルを付けていない（} // end function、} // end if block など）

命名

• 汎用的なプレースホルダー名を使っていない（data、result、info、temp、helper など）
• 説明が過剰で冗長な名前を使っていない（theUserWhoIsCurrentlyLoggedIn など）
• 正当な理由なく接尾辞を多用していない（*Helper / *Manager / *Util / *Wrapper など）
• 名前に型を含めていない（userObject、resultArray、stringData など）

過剰な設計

• 実装が 1 つだけで、2 つ目を追加する計画もないインターフェースがない
• トップレベル関数にすべき単一メソッドのクラスがない
• 委譲するだけのラッパー関数を一度だけ呼び出していない
• 既存の依存関係で同じ処理ができるのに、新しい依存関係を追加していない

過剰な防御

• スローされる可能性のないコードを、汎用的な catch (e) { console.error(...) } ブロックで囲んでいない
• 非 null アサーションの後や、型によって値が保証されている箇所で、不要な null チェックをしていない
• 外部呼び出しのタイムアウトやレート制限など、実際に必要な防御策が適切に設定されている

テストの見せかけ

• 実際の振る舞いを検証するアサーションがなく、すべての依存関係をモックするだけのテストがない
• 呼び出して例外が発生しないことを確認するだけの「例外が発生しない」テストがない
• 実装のロジックをそのままなぞる（検証するのではなく、再エンコードする）テストがない
• 振る舞いを検証するアサーションの代わりにスナップショットテストを使っていない

スタイルの痕跡

• 多少のフォーマットのばらつきがある（どのファイルも最も厳しいリンターにかけたようなコードベースはありません）
• 推論が難しい箇所に as any / @ts-ignore / @ts-expect-error が散見されない
• リポジトリのどこかに // HACK: / // XXX: / 深夜2時に書かれたようなコメントがある — 痕跡のないコードベースは疑わしいです
• 本番コードにデバッグ用の残骸（console.log、var_dump、dd()、dump()）が残っていない
• if (x) return true; else return false や、明らかなリテラルに対する冗長な型注釈がない

監査ステップ4：見せかけの記録簿を作成する

監査の最後に、判定表を提示します。

## Code Slop Ledger

| File | Verdict | Top findings | Suggested action |
|------|---------|--------------|------------------|
| app/Services/UserExportService.php | INFLATED | 12 narration comments; 3 closing-brace labels; `*Helper` overuse | Strip comments; rename Helper → split into functions |
| resources/js/Pages/Orders/Show.tsx | CRITICAL | 4 `as any`; mock-everything tests; useless wrapper; impossible null checks | Rewrite section; remove tests; revisit type model |
| app/Models/Order.php | CLEAN | — | — |

## Summary
- CLEAN: X files
- SUSPICIOUS: Y files
- INFLATED: Z files (top priority: …)
- CRITICAL: N files (rewrite before merge)

適用するタイミング

以下の場合に、このスキルを参照します。

• AI の支援を受けた PR をマージ前にレビューするとき
• AI の支援による大規模な貢献を受け入れたリポジトリを監査するとき
• コードベースのオンボーディング時に、人間が保守しているように見えるか評価するとき
• AI 生成コードの粗雑さに対して、チームのコードレビュー用チェックリストを強化するとき
• 「バイブコーディング」のスプリント後、機能が完成したと宣言する前
• AI 生成コードの品質を確認する CI ゲートを設定するとき

ステップ1：プロジェクトのスタックを検出する

ほとんどのルールは考え方としてはスタックに依存しませんが、例や検出コマンドは PHP と TypeScript で異なります。

シグナル	スタック	ツール
composer.json	PHP / Laravel	phpstan、phpcs、phpmd、手動の grep
package.json	Node / TS / React	eslint、tsc --noEmit、knip、手動の grep

優先度別のルールカテゴリ

優先度	カテゴリ	影響度	接頭辞
1	コメント	CRITICAL	comments-
2	命名	CRITICAL	naming-
3	過剰な設計	HIGH	over-eng-
4	過剰な防御処理	HIGH	defensive-
5	テストの見せかけ	HIGH	test-
6	スタイルの痕跡	MEDIUM	style-

クイックリファレンス

1. コメント（CRITICAL）

• comments-narration — 次の行のコードをそのまま言い換えているコメント
• comments-empty-docblocks — 型付きの getUser() シグネチャに対する、汎用的な /** Get the user */
• comments-placeholder — // TODO: implement、// your code here、// implementation、// helper function
• comments-closing-brace-labels — } // end function / } // end if block

2. 命名（CRITICAL）

• naming-generic-placeholders — data、result、info、temp、helper、value
• naming-over-descriptive — theUserWhoIsCurrentlyLoggedIn、calculateTotalAmountFromItemsList
• naming-suffix-abuse — *Helper / *Manager / *Util / *Wrapper / *Processor の多用
• naming-type-in-name — userObject、resultArray、stringData、listOfItems

3. 過剰な設計（HIGH）

• over-eng-premature-interface — 実装が1つだけで、ロードマップにも2つ目の実装がないインターフェース
• over-eng-single-method-class — 1つの関数を包むためだけに存在するクラス
• over-eng-useless-wrapper — 1か所からしか呼び出されず、処理を委譲するだけのラッパー
• over-eng-dependency-creep — 既存の依存関係で対応できるのに、新しいライブラリを追加する

4. 過剰な防御処理（HIGH）

• defensive-generic-catch — try { ... } catch (e) { console.error("error") } をあらゆる箇所で使う
• defensive-impossible-null — 非 null アサーション後や、型で保証された値に対する null チェック
• defensive-missing-real — 不適切な箇所では防御処理があるのに、重要な箇所ではタイムアウトやレート制限が欠けている

5. テストの見せかけ（HIGH）

• test-mock-everything — すべての依存関係をモックし、振る舞いではなく実装を再エンコードしているテスト
• test-doesnt-throw — 関数を呼び出して例外が発生しないことを確認するだけのテスト
• test-mirror-implementation — テスト対象の本番コードとロジックが同じテスト
• test-snapshot-abuse — 振る舞いを検証するアサーションの代わりに使われるスナップショットテスト

6. スタイルの特徴（中程度）

• style-hyper-consistent — どこにも書式のばらつきがなく、すべてのファイルがリンターで完璧にチェックされたように見える
• style-as-any-escape — 型が難しい箇所に as any / @ts-ignore / @ts-expect-error があちこちに散りばめられている
• style-no-hack-scars — コードベースに // HACK: / // XXX: マーカーがまったくなく、「地層」もない
• style-debug-artifacts — 本番コードに console.log、var_dump、dd()、dump() が残っている
• style-trivial-boilerplate — if (x) return true; else return false; のようなコードや、明らかなリテラルに対する冗長な TS 型注釈

必須パターン

「このコードレビューに通るか？」フィルター

コードの各部分について、次の点を確認します。

1. コメントを3分の1削ってもコードが読みやすくなりますか？ → コメントの冗長さが疑われます
2. 変数名から格納内容がわかりますか、それとも型しかわかりませんか？ → 命名の冗長さが疑われます
3. このクラスは関数にできますか？ → 過剰な設計が疑われます
4. この catch ブロックは実際に何かを処理していますか、それともログを出すだけですか？ → 過剰な防御処理が疑われます
5. この関数を壊した場合、このテストは失敗しますか？ → いいえなら、テストの冗長さが疑われます
6. 差分に // HACK: / // XXX: マーカーはありますか？ → ないなら、AI が書いたコードである可能性が疑われます

判定区分（AI-SLOP-Detector のスコアリングに対応）

判定	意味	対応
CLEAN	フラグが付いた行が 5% 未満	リリースする
SUSPICIOUS	フラグが付いた行が 5～15%	変更をもう一度レビューする
INFLATED	フラグが付いた行が 15～30%	冗長な部分を取り除き、コミットを分割する
CRITICAL	フラグが付いた行が 30% 超	マージ前にセクションを書き直す

使い方

詳細な規約と例については、個々のルールファイルを読んでください。

rules/comments-narration.md
rules/naming-generic-placeholders.md
rules/over-eng-premature-interface.md
rules/defensive-generic-catch.md
rules/test-mock-everything.md
rules/style-hyper-consistent.md

各ルールファイルには次の内容が含まれています。

• YAML フロントマター（タイトル、影響度、タグ）
• そのパターンが AI 生成コードの特徴である理由の簡単な説明
• 冗長なコードを示す「不適切な例」
• 人間が書いた場合に相当するコードを示す「適切な例」
• 検出方法（grep / eslint / phpstan / ヒューリスティック）
• 参考リンク

参考資料

• GitClear — 2025 年コード品質トレンドレポート（リファクタリングの減少、コピー＆ペーストの急増）

• arXiv 2510.03029 — LLM 生成コードの臭いを調査する

• Addy Osmani — 理解負債（O'Reilly Radar）

• Stack Overflow Blog — AI コード品質に関する Eno Reyes の Q&A

• hardikpandya/stop-slop — 文章の冗長さを対象とする姉妹プロジェクト

• flamehaven01/AI-SLOP-Detector — 27 パターンを検出する Python AST スキャナー

完全版ドキュメント

すべてのルールを展開した完全なガイドは AGENTS.md を参照してください。