clean-code-guard

clean-code-guard

生成または変更されたコードをリリース前にレビューします。最初の実装後のガードパスとして、以下のルールを適用してください。このスキルが有効になった後は、同じセッション内でその後に行うすべてのコード変更にも適用し続け、以前にスキルを読み込んだからといってガードなしの出力に戻さず、編集のたびに提出前のセルフチェックを再実行してください。ユーザーがコードを書く前にこのスキルを明示的に呼び出した場合は、同じルールを執筆中にも適用し、提出前にセルフチェックを実行してください。

互換性

これは移植可能な指示スキルです。MCP サーバー、ネットワークアクセス、API キー、シェルコマンド、ローカル実行ファイル、同梱スクリプトは必要ありません。SKILL.md と直接リンクされた references/ ファイルをサポートする任意のランタイムで使用できます。agents/openai.yaml は軽量な表示メタデータです。

このスキルは、プロジェクトのリンター、フォーマッター、型チェッカー、テストランナーに代わるものではありません。機械的な検証にはプロジェクト独自のツールを使用し、コード品質やレビューに関する判断にはこのスキルを使用してください。

このスキルの使い方

このスキルには3つのモードがあります。ユーザーの依頼に応じて選択してください。

ガードパスモード（推奨）：コードを生成、編集、リファクタリング、修正した後、変更差分または対象ファイルを以下の常に適用する必須ルールに照らして確認します。作業を提示、コミット、またはマージする前に、違反を修正してください。

ライブモード（明示的な呼び出し時）：ユーザーがリスクの高いコード編集の前にこのスキルを呼び出した場合、執筆中に同じ必須ルールを適用し、提出前のセルフチェックのチェックリストを実行してください。ルールに違反した場合は、ユーザーに提示する前に修正してください。

レビューモード（ユーザーがコードのレビュー、監査、批評、評価を依頼したときに実行）：references/review-checklist.md に沿って対象ファイルを確認し、構造化された指摘レポートを作成します。依頼されない限り、レビューモードではコードを編集しないでください。

3つのモードすべてにおいて、ルールの詳細は references/ にあります。次の場合は、該当するリファレンスファイルを読んでください。

• ルールの理由を十分に把握していない場合。
• ユーザーがルールに異議を唱え、根拠となる引用元が必要な場合。
• レビューモードで、チェックリスト全体が必要な場合。
• レビュー対象のコードが特定の原則に関係する場合（例：サブクラス化 → references/solid.md、重複排除 → references/dry-kiss-yagni.md）。

リファレンスファイルは次のとおりです。

• references/naming-and-functions.md — 名前、関数の規模、パラメーター、コマンドとクエリの分離。
• references/comments-and-formatting.md — コメントを付けるタイミング、削除するタイミング、周囲のコードスタイルとの統一。
• references/solid.md — SRP、OCP、LSP、ISP、DIPと、現代的な表現および検出の手掛かり。
• references/dry-kiss-yagni.md — 知識の重複とコードの重複、Sandi Metz の再インライン化ルール、McCabe の複雑度、Fowler による YAGNI のコスト分類。
• references/ai-failure-modes.md — LLM が質の低いコードを生成する14の体系的なパターン。このスキルを読む AI エージェントは、まずこのファイルを読んでください。 このスキルの中で最も効果の高いファイルです。
• references/review-checklist.md — レビューモードで使用する構造化された確認手順。
• references/sources.md — 出典 URL の一覧。外部の出典を確認または引用する必要がある場合にのみ読んでください。

例

• コーディングエージェントがエンドポイントを実装する場合: 作業が提示またはコミットされる前に、差分に対して guard-pass モードを使用します。
• ユーザーが「この PR をレビューして」または「これはマージすべき？」と尋ねた場合: レビューモードを使用し、references/review-checklist.md から検出事項を報告します。求められない限り編集しないでください。
• ユーザーが「clean-code-guard を使ってこのエンドポイントを実装して」と尋ねた場合: 記述中はライブモードを使用し、納品前にセルフチェックを実行します。
• ユーザーが「この関数を同じ動作のままリファクタリングして」と尋ねた場合: 観察可能な動作を正確に維持し、あらゆるバグ修正は別の変更として扱います。

成功基準

このスキルが機能しているのは、コード記述タスクが列挙された失敗モードを回避し、コードレビュータスクが具体的な根拠を伴う優先順位付けされた検出事項を生成し、ユーザーが明示的に動作変更を求めない限りリファクタリングが動作を維持する場合です。frontmatter の除外項目で対象となる概念的タスク、CI、git ワークフロー、文章、データ分析、テスト実行のタスクでは、沈黙を保つべきです。

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

LLM が生成したコードには、一般的な「クリーンコードに従う」という指示では捉えられない、測定可能で体系的な失敗モードがあります。公表された研究に裏付けられた例:

• 追跡対象のコードベースにおいて、コードの重複が 8 倍に増加しました（2021 年から 2024 年の間、GitClear 2025 レポート）。
• パッケージのハルシネーション率は平均 19.6% です（16 モデルにわたる、Spracklen ら、USENIX Security '25）。
• LLM はしばしば、エラーを握りつぶす広範な catch-all ハンドラーでリスクのある操作を包み込みます（Karpathy）。
• AI エージェントは、ハードコードされたフィクスチャ値を返すことで、**「テストが失敗しているにもかかわらず成功を宣言する」**ことがあります（Fowler、Patterns for Reducing Friction）。
• AI 支援によるコミットでは、関数のサイズが 142 から 267 LoC に、循環的複雑度が 4.2 から 8.1 に増加しました（GitClear）。

古典的な原則（Clean Code、SOLID、DRY/KISS/YAGNI）は依然として基盤です。しかし、このスキルは、ほとんどのルールパックが見落としている AI 固有 の層を追加します。

常に適用される必須事項

これらはすべてのコード変更で従うべきルールです。これらは提案ではなく、必須事項です。

関数と命名

1. 名前は意図を明らかにする。 修飾子なしで data、data2、result、result_final、item、temp、value、obj、info、helper、manager、utils、または handle_*/process_*/do_* を決して使用しないでください。名前は それがなぜ存在し、何をするのか に答えなければなりません。（Clean Code 第 2 章）
2. 関数は小さく保つ。 目標は ≤20 行、抽象化のレベルは 1 つ、1 つのことだけを行います。本体を言い換えない名前で関数を抽出できるなら、親は 1 つ以上のことをしていました。（Clean Code 第 3 章）
3. 引数は 4 つが上限です。 5 つになったら、手を止めてリクエスト/設定オブジェクト（レコード、構造体、DTO、または同等のもの）を導入してください。boolean のフラグ引数は決して使用しないでください。代わりに 2 つの関数に分割します。
4. 出力引数は禁止です。 関数は値を返す（クエリ）か、副作用を持つ（コマンド）かのどちらかです。両方を行ってはいけません。コマンド名は動詞を使用し、クエリ名は名詞または getter 形式の名前を使用します。（CQS）

コメントと構造

5. コメントは 何を ではなく なぜ を説明する。 その下の行を言い換えているだけのコメントは削除してください。手順番号の足場となるコメントは削除してください。コメントアウトされたコードは削除してください。バージョン管理があります。（Clean Code 第 4 章）
6. ファイルの既存のスタイルに合わせる。 書く前に、編集しているファイルと少なくとも 1 つの隣接ファイルを読んでください。ケーシング、import の順序、エラー処理、ログ記録、HTTP/DB クライアントの選択を踏襲してください。2 つ目のパターンを導入しないでください。

SOLID

7. 1モジュールにつき1アクター。 クラスは1つのステークホルダーグループ（経理、認証、レポート）に対してのみ責任を負うべきです。無関係な2つのサブシステムが同じクラスに手を伸ばしているなら、分割してください。（SRP、Uncle Bob 2014）
8. 拡張は新しいコードで行い、編集では行わない。 新しいバリアントを追加するために既存の関数にもう1つ型タグの分岐が必要になるなら、まずレジストリ、ストラテジー、またはポリモーフィックディスパッチにリファクタリングしてください。（OCP）
9. サブクラスは親の契約を拒否してはならない。 「未実装」や「サポートされていない操作」を示すためにメソッドをオーバーライドしてはいけません。オーバーライドで事前条件を強化したり、事後条件を弱めたりしてはいけません。そうする必要があるなら、その継承は誤りです。（LSP）
10. 抽象は実装ではなく、クライアントとともに置く。 インターフェース、プロトコル、または抽象契約を導入するときは、具体的なクラスの隣ではなく、それを利用するパッケージに置いてください。（DIP）

DRY、KISS、YAGNI

11. 削除すべきは重複した知識であり、重複したテキストではない。 見た目は似ていても異なるルールを表現している2つの関数は、DRY違反ではありません。コード + ドキュメント + スキーマで表現された1つのルールは違反です。（Pragmatic Programmer、「DRY」）
12. 誤った抽象は重複よりも悪い。 抽象が各呼び出し元の特殊ケースごとに分岐を蓄積してしまっているなら、いったん呼び出し元にインライン展開して戻し、その後、再抽象化する前に死んだ分岐を削除してください。（Sandi Metz、「The Wrong Abstraction」）
13. 複雑さの上限：循環的複雑度 ≤10、ネストの深さ ≤5。 超える前にリファクタリングしてください。（McCabe 1976）
14. 投機的なものは一切作らない。 現在の呼び出し元がいないオプションパラメータ、設定フラグ、環境変数、フィーチャートグル、インターフェース、ファクトリ、基底クラスは一切作らないでください。enable_*、use_*_v2、*_mode を追加している自分に気づいたら、それを削除して具体的な振る舞いを出荷してください。（Fowler、「Yagni」）

AI 固有のガードレール — 最も効果の高いセクション

15. 広範な catch-all 処理でエラーを握りつぶさないこと。 回復可能な特定のエラー型のみをキャッチしてください。回復できない場合は、エラーを伝播させます。catch ハンドラーから null/none/空の成功を返すことは、関数のコントラクトがその動作を文書化していない限り禁止です。(Karpathy)
16. 境界をガードし、コントラクトを信頼する。 信頼境界 — 外部入力、リクエスト/API ペイロード、デシリアライズされたデータやプロセス間データ、信頼できないソースからのあらゆるもの — では、ハッピーパスが問題なく見えても検証してください。境界の内側では、宣言された型や呼び出し元のコントラクトがそのケースをすでに排除している値に対して、null チェックや実行時の型チェックを追加しないでください。ガードのテストは「これは理論的に間違っている可能性があるか」ではなく、「信頼できないデータがここに到達しうるか」です。(arXiv 2409.19182)
17. すべてのインポートと外部呼び出しを検証すること。 ライブラリのメソッドを呼び出す前に、インストールされているバージョンにそれが存在することを確認してください (パッケージを読む、lockfile を確認する、またはインポートして検査する)。API が「こうあるべき」という姿に基づいてコードを生成しないでください。(USENIX Security '25)
18. 本番コードにハードコードされた「成功」の戻り値やモックフィクスチャを入れないこと。 仕様が実際の処理を行うと述べている関数から、{"status": "ok", ...} や定型データを決して返さないでください。実装できない場合は、その言語の未実装または未サポート操作のメカニズムで明示的に失敗し、その旨を伝えてください。テストを合格させるために、テストを無効化、スキップ、または弱体化しないでください。(Fowler, Claude Code issue #6984)
19. 類似からコピーせず、再導出すること。 関数をコピーして修正したくなったら、手を止めてください。仕様から再導出します。オフバイワンや誤った null セマンティクスのバグは、ほとんど常に類似からのコピーを通じて入り込みます。(arXiv 2411.01414)
20. 境界ケースは書く前に列挙すること。 範囲、オフバイワン、null/空/1 件/多数、偶数/奇数、または unicode/バイト境界については、まずコメントでケースリストを書いてください。次に進む前に、各ケースをコードでカバーします。
21. 納品前にデッドコードを削除すること。 未使用のインポート、未使用のシンボル、到達不能な分岐、「念のため」のエクスポートについて、リンターまたは grep を実行してください。それらを削除します。今日何も呼び出していない関数は、「いつか」のために生き残ることはできません。
22. 書く前に読むこと。 不慣れなリポジトリで書く前に、編集するファイル、隣接するファイルを 1 つ、そしてプロジェクトのルールファイル (CLAUDE.md、AGENTS.md、README の「conventions」セクション) を読んでください。プロジェクトに既存のヘルパー、エラー型、ログを使用します。
23. 数行でカバーできることに新しい依存関係を追加しないこと。 パッケージを追加する前に、標準ライブラリ、すでにインストールされている依存関係、そして数行のローカルコードで用が足りるかを確認してください。新しい依存関係は恒久的なメンテナンスとサプライチェーンの表面積です。再実装すべきでない実際の複雑さ (暗号化、パース、タイムゾーン — 例示であり、網羅的ではありません) を担う場合にのみ追加し、10 行を節約するためには決して追加しないでください。references/dry-kiss-yagni.md を参照してください。

最低ライン — シンプルさのために決して削ってはいけないもの

ルール 16 は境界の内側でコントラクトを信頼します。以下の項目は、投機 (14)、防御的ガード (16)、デッドコード (21) を削っている間も残ります。これらの 1 つを削除することは動作の変更であり、クリーンアップではありません — 保持するか、フラグを立てて質問してください。

• あらゆる信頼境界での検証とサニタイズ — 外部入力、リクエスト/API ペイロード、デシリアライズされたデータやプロセス間データ。
• データ損失を防ぐエラー処理。
• セキュリティ対策 — 認可、出力エスケープ、パラメーター化クエリ、シークレットの取り扱い。
• ユーザーが明示的に要求した動作。 何気なく言及された ≠ 要求された、ただし要求されたものを落とさないでください。

リファクタリングの規律

24. リファクタリング時は観測可能な動作を保持する。 ユーザーが既存コードのクリーンアップ、簡素化、またはリファクタリングを依頼した場合、コントラクトを変更しないでください — 同じ入力は同じ出力を生成し、同じ例外が発生し、同じ副作用があり、同じ順序保証が維持されます。リファクタリング中にバグを見つけた場合は、別途報告し、変更する前に確認してください。リファクタリングは*「観測可能な動作を変更せずに、ソフトウェアの内部構造を変更して理解しやすく、修正しやすくすること」*と定義されます（Fowler、Refactoring）。バグ修正とリファクタリングは2つの操作です — 決して1つの変更にまとめないでください。

納品前のセルフチェック

作成または編集したコードをユーザーに見せる前に：

1. 命令1〜24を自分の差分に対して確認します。すべての違反を修正します。
2. 新しい関数について数えます：行数は20以下か？ パラメータは4以下か？ 複雑度は10以下と感じられるか？ 名前は意図を明らかにしているか？
3. 新しいコメントについて問います：これはなぜを説明しているか？ 何を説明しているなら、削除します。
4. 新しいエラー処理について：キャッチしたエラーの型は具体的か？ ハンドラーは黙ってreturnする以外のことをしているか？
5. 新しい抽象化（インターフェース、ファクトリ、基底クラス、レジストリ）について：今日、2人目の具体的な利用者はいますか？ いなければ、インライン化します。
6. 編集したファイルと少なくとも1つの隣接ファイルを読みましたか？ 自分のスタイルは一致していましたか？
7. ハードコードされた「ok」リターンやフィクスチャデータはありますか？ ある場合は、実際の実装または明示的な未実装/未サポート操作の失敗に置き換えます。
8. これがリファクタリングの場合：観測可能な動作を変更しましたか？ はいの場合、バグ修正をまとめてしまっています — それを分離し、ユーザーに確認します。

すべてのチェックにはいと答えられない場合、出荷前に修正します。

ガードパス後、実行されたことをユーザーが確認できるように提示します（ガードパスモードとライブモード — レビューモードは独自の検出事項フォーマットで報告します）。各修正を <file>[:<line>] — <what changed> としてリストし、行番号が不安定な場合は省略し、最後に1行で締めくくります：clean-code-guard: <N> fixed, <M> flagged for author — 何もトリガーされなかった場合は clean-code-guard: clean。実際に行った変更のみを報告してください。品質スコアやパーセンテージを推定してはいけません — ベースラインが存在しないため、そのような数値はでっち上げることになります。これはパスの報告であり、提示やコミットをブロックするものではありません。

ユーザーがルールに異議を唱えた場合

該当する references/ ファイル内のソース名を参照させ、URLが必要な場合にのみ references/sources.md を使用します。ルールは防御可能です — 一次資料（Uncle Bob、Fowler、Hunt & Thomas、McCabe、Metz）およびLLMコード生成に関する2024〜2026年の公開研究に基づいています。ユーザーが状況に応じた上書きの理由を持つ場合（例：コンストラクタが設定DTOのために本当に8つのパラメータを必要とする）、上書きされる原則、その理由、および再検討トリガー — 再検討すべき条件 — を記したコードコメントで例外を文書化します。再検討トリガーのない例外コメントは、それ自体が次のパスでの検出事項です：出口のないトレードオフは、単に先送りされた負債にすぎません。

トラブルシューティング

• タスクがコードを生成するものではなく概念的なものである場合、このスキルを適用しないでください； 概念に直接答えてください。
• レビューモードがスタイルのみのフィードバックを生成し始めた場合、 references/review-checklist.md を使用し、動作上のバグ、脆弱性、 保守性のリスクを優先してください。
• ルールが明示的なプロジェクトの規約と競合する場合、プロジェクトの 規約に従い、将来のメンテナーを驚かせる場合にのみ例外を文書化してください。
• スキルが広すぎると感じる場合、まずフロントマターの除外を使用してください；この一般的なガードスキルに ランタイム固有のルールを追加しないでください。

このスキルが行わないこと

• リンターや静的解析を実行すること。これらはツールレベルの関心事であり、このスキルは何を書くかと何を探すかに関するものです。
• 言語固有のフォーマッターやリンターの設定を強制すること。プロジェクトのスタイルツールに委ねます。
• テストを置き換えること。クリーンなコードはテストに合格します。クリーンなコードがなければテストに合格しませんが、テストのないクリーンなコードもまた欠陥です。