clean-ai-slop

AI Slop Cleaner

AI が生成したコードを整理するための矯正的な規律です。コード生成後に実行します。run-plan、手動セッション、その他どのようなソースによる生成にも適用できます。

根本的な問題は、LLM が動作はするものの、特有のにおいを持つコードを生成することです。コメントの付けすぎ、不要な抽象化、起こり得ないシナリオへの過剰な防御、冗長な命名などです。放置すると、これらが積み重なり、手書きのコードよりも読みづらく、保守しにくいコードベースになります。

このスキルでは、動作を変えずに、においをカテゴリごとに一つずつ体系的に取り除きます。

厳守事項

これらのルールには例外がありません。

1. 整理する前に動作を固定します。 既存のテストを実行してください。カバレッジが不十分な場合は、これから手を加えるコードのリグレッションテストを追加してください。テストカバレッジがなければ、整理を行ってはいけません。
2. 1 回のパスにつき、においのカテゴリは 1 つに限定します。 不要なコードの削除と命名の修正を混在させてはいけません。1 つのパスを完了して検証してから、次のパスに進んでください。
3. 各パスの後にテストを実行します。 テストが失敗した場合は、そのパスを元に戻して原因を調査してください。次のカテゴリに進んではいけません。
4. 範囲を守ります。 AI が生成または変更したファイルだけに手を加えてください。改善できそうに見える「近くの」コードに範囲を広げてはいけません。
5. 動作を厳密に維持します。 整理によって観測可能な動作が変わる場合は、新しい動作のほうが「優れている」と思えても、変更を元に戻してください。動作の変更には別のタスクが必要です。

使用する場面

• run-plan の完了後、実装は動作するものの、AI が書いたような読み心地になっているとき
• 重要なコード生成セッションの後
• AI が生成した PR をレビューするとき
• ユーザーがコードの整理や、AI らしい冗長さの除去を明示的に依頼したとき

使用しない場面

• 人間が書いたコード（においの種類も対処方法も異なります）
• テストが存在せず、すぐに追加することもできないとき（まず動作を固定してください）
• 実装の途中（機能を完成させてから整理してください）

においのカテゴリ

パスは次の順序で実行します。次のパスを始める前に、各パスを完全に完了させてください。

パス 1：不要なコード

目的のないコードを削除します。

• 未使用のインポート
• 未使用の変数やパラメーター
• 到達不能な分岐
• コメントアウトされたコードブロック
• 例外を握りつぶす空のエラーハンドラー

検出方法：コンパイラーの警告、リンターの出力、IDE でグレーアウトされたシンボルを確認します。ツールの判断を信頼してください。

パス 2：コメントの付けすぎ

コードの内容をそのまま言い換えているコメントを削除します。

対象：

• let counter = 0 の上にある // Initialize the counter
• return result の上にある // Return the result
• 関数シグネチャを繰り返すだけで、追加情報のない JSDoc
• 情報を付け加えないセクション区切り（// --- Helper Functions ---）
• ファイル名から明らかな内容を説明するファイルヘッダー

残すもの：何をするかではなく、なぜそうするのかを説明するコメント。自明でない制約に関するコメント。外部ドキュメントや課題へのリンク。

パス 3：不要な抽象化

目的のない間接化を取り除きます。

対象：

• 1 回しか呼び出されないヘルパー関数（インライン化します）
• すべての処理を単一の内部オブジェクトに委譲するラッパークラス
• 今後設定する予定のない項目の設定オブジェクト
• 常に同じものを生成するファクトリー関数
• 追加実装の予定がない、単一の実装だけで使われるインターフェースや型定義

判断基準：抽象化を取り除くことで、コードが短くなり、かつ読みやすさも変わらないなら、その抽象化は不要です。

パス 4：過剰な防御

起こり得ないシナリオへのエラー処理を取り除きます。

対象：

• 型システムによって null にならないことが保証されている値への null チェック
• 例外をスローし得ないコードを囲む try-catch ブロック
• 内部関数のパラメーターの検証（システム境界でのみ検証します）
• 必須フィールドのフォールバック値
• 冗長な型アサーション

残すもの：システム境界（ユーザー入力、外部 API、ファイル I/O）での検証。実行時に実際に失敗する可能性がある箇所のエラー処理。

パス 5：冗長な命名

冗長な情報を含む名前を短くします。

対象：

• getUserDataFromDatabase → getUser（データの取得元はほかにありません）
• userAccountStatus → status（User クラス内で使う場合、接頭辞は冗長です）
• handleButtonClickEvent → onClick
• responseDataObject → response
• tempVariableForCalculation → temp、またはインライン化します

ルール：スコープ内で曖昧さが残らない範囲で、名前はできるだけ短くします。スコープが広ければ名前も長く、スコープが狭ければ名前も短くします。

パス 6：LLM 生成の冗長表現

LLM の生成スタイルによる痕跡を取り除きます。

対象：

• コード、コメント、コミットメッセージ内の絵文字（プロジェクトで意図的に使っている場合を除く）
• コメント内の会話調の表現（「では」「次に必要なのは」「すばらしい！」など）
• 「デバッグ用」として追加された過剰な console.log / print 文
• 型推論で対応できる冗長な型注釈
• 問題の自然な形ではなく、テンプレートのパターンに従った過度に構造化されたコード

手順

1. Identify scope (which files to clean)
2. Run existing tests — all must pass before starting
3. Add regression tests if coverage is thin
4. Execute Pass 1 → verify → commit
5. Execute Pass 2 → verify → commit
6. ... continue through all relevant passes
7. Run full test suite
8. Report summary of changes

すべてのパスが、すべてのコードベースに当てはまるわけではありません。該当箇所がないパスはスキップします。ただし、順番どおりに実行してください。先のパスへ飛ばしてはいけません。

アンチパターン

ついやってしまうこと	うまくいかない理由
「まとめて一度に全部整理しよう」	テストが失敗したとき、変更が混在しているとデバッグできません
「この抽象化はよくない。再設計しよう」	再設計は別のタスクであり、クリーンアップではありません
「テストに通ったから、パスごとの検証は省略しよう」	後のパスが前の変更に影響する場合があります
「近くにあるこのコードも雑に見える」	スコープの逸脱です。スコープ内のものだけをクリーンアップしてください
「どうせ動作が間違っているから、クリーンアップ中に直そう」	動作の変更には、専用のタスクとテストが必要です
「回帰テストは不要です。コードは単純なので」	単純なコードでも壊れます。まず動作を固定してください

危険信号

次のように考えていることに気づいたら、作業を止めて再検討してください。

• 「時間がかかりすぎているので、残りのパスをまとめて実行しよう」
• 「この別のファイルもさっと直してしまおう」
• 「テストはおそらく問題ないので、もう一度実行する必要はない」
• 「この動作はどうせ変えるべきだ」
• 「コメントを削除するだけなので、テストは不要」

完了基準

次の条件を満たしたら、クリーンアップは完了です。

• 該当するすべてのパスを順番どおりに実行している
• 個々のパスの実行後にテストが成功している
• 最後にテストスイート全体が成功している
• 動作が一切変わっていない
• 変更対象が特定されたファイルのみに限定されている

いずれかの条件を満たしていない場合、クリーンアップは完了していません。

最小チェックリスト

クリーンアップ中に、次の項目を確認してください。

• 開始前にテストで動作を固定している
• 現在のパスでは、1 種類のコード上の問題だけを対象にしている
• 現在のパスの実行後にテストが成功している
• 定義されたスコープ外のファイルに触れていない
• 動作を変更していない

次のステップ

クリーンアップが完了したら：

• コードが run-plan で生成された場合 → 結果をユーザーに報告します
• 生成時に実装規律が欠けていた場合 → 発生源でずさんなコードを防ぐため、今後のセッションで karpathy の適用を検討します