Communityコーディング&開発github.com

クリーンコードガード

生成または変更されたプロダクションコードがリリースされる前に、クリーンコード、SOLID、DRY、KISS、YAGNI、およびLLM特有の障害モードチェックを用いてレビューします。任意のプログラミング言語で動作します。

クリーンコードガード とは?

このスキルは、AIエージェント(Claude Code、Cursor、Codexなど)が生成または変更したコードをリリース前にレビューし、クリーンコード、SOLID、DRY、KISS、YAGNIといった古典的な原則と、LLM特有の16種類の障害モードチェックを組み合わせて適用します。任意のプログラミング言語で動作し、MCPサーバーやネットワークアクセス、APIキーなどの外部依存関係は不要です。すべてのチェックリストやガイダンスは同梱のreferences/ディレクトリにローカル保存されており、AIエージェントはこれらのファイルを参照してルールを適用します。このスキルは、単なる機械的なリントやフォーマットチェックを超えた「判断レイヤー」を提供し、コードの重複、パッケージ幻覚、エラーの握りつぶし、ハードコードされた成功レスポンスなど、LLM生成コードに一般的に見られる問題を体系的に防ぎます。

対応✓Claude Code✓Codex CLI~Cursor
Part ofReact
npx skills add https://github.com/EthanZ-ZJ/dsh-agent-team-roles/tree/HEAD/templates/software-dev/skills/cr/clean-code-guard

Installed? Explore more コーディング&開発 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

clean-code-guard(クリーンコードガード)

あなたは生成または変更されたコードがリリースされる前にそれをレビューしています。最初の実装パスの後に、以下のルールをガードパスとして適用してください。このスキルがアクティブになったら、同じセッション内のその後のコード変更に対しても常に適用し、毎回の編集後に配信前の自己チェックを再実行してください。以前にスキルがロードされたからといって、ガードされていない出力に戻してはいけません。ユーザーが明示的にコード記述前にこのスキルを呼び出した場合は、記述中も同じルールを適用し、配信前に自己チェックを実行してください。

エージェントチーム連携

リポジトリのルール、受け入れられた契約、ロール権限、ユーザースコープは、このガイドとその参照よりも優先されます。DEVは自身の変更に対してガードパスを使用します。CRは読み取り専用のレビューモードを使用し、実装を編集しません。数値制限、命名禁止、引数形状、抽象化ルールは、自動編集やブロックではなく、調査のシグナルとして扱ってください。発見事項は、コンテキストにおける具体的な正確性またはメンテナンスコストを説明する必要があります。コードを分割したり、インターフェースを壊したり、単にカウントを満たすためだけに例外コメントを追加したりしないでください。変更されたコードと、それに直接影響を受ける呼び出し元をレビューしてください。無関係な負債はレビュー対象外です。

このパッケージが使用するすべてのガイダンスとチェックリストはローカルにあります。外部の出版物名は帰属のみを示すものです。ブラウジングではなく、リポジトリの証拠とバンドルされた参照を使用してください。このタスクがスキルの範囲外である場合は、リポジトリの通常のプロセスに従ってください。兄弟スキルは必要ありません。

互換性

これはポータブルな指示スキルです。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の中央書誌。外部ソースを検証または引用する必要がある場合にのみ読んでください。

例

  • コーディングエージェントがエンドポイントを実装した場合:作業が提示またはコミットされる前に、差分に対してガードパスモードを使用してください。
  • ユーザーが「このPRをレビューして」または「これをマージしても安全ですか?」と尋ねた場合:レビューモードを使用し、references/review-checklist.mdから発見事項を報告してください。要求がない限り編集しないでください。
  • ユーザーが「このエンドポイントをclean-code-guardを使って実装して」と依頼した場合:記述中にライブモードを使用し、その後配信前に自己チェックを実行してください。
  • ユーザーが「この関数をリファクタリングして、同じ動作を維持して」と依頼した場合:観測可能な動作を正確に保持し、バグ修正は個別の変更として扱ってください。

成功基準

このスキルが機能している状態とは、コード作成タスクがリストされた障害モードを回避し、コードレビュータスクが具体的な証拠とともに優先順位付けされた発見事項を生成し、ユーザーが明示的に動作変更を要求しない限りリファクタリングが動作を保持する場合です。フロントマターの除外事項でカバーされる概念的なタスク、CI、gitワークフロー、散文、データ分析、テスト実行タスクについては沈黙を保つべきです。

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

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

  • 追跡されたコードベースでコード重複が2021年から2024年の間に8倍に増加(GitClear 2025年レポート)。
  • 16モデル全体でのパッケージ幻覚率は平均19.6%(Spracklenら、USENIX Security '25)。
  • LLMはリスクのある操作を広範なキャッチオールハンドラーでラップし、エラーを飲み込むことが多い(Karpathy)。
  • AIエージェントはハードコードされたフィクスチャ値を返すことで**「テストに失敗しても成功を宣言する」**(Fowler、摩擦を減らすためのパターン)。
  • AI支援コミットでは、関数サイズが142行から267行に、サイクロマティック複雑度が4.2から8.1に増加(GitClear)。

古典的な原則(クリーンコード、SOLID、DRY/KISS/YAGNI)は依然として基盤ですが、このスキルはほとんどのルールパックが見逃しているAI固有のレイヤーを追加します。

常時適用される必須事項

これらはすべてのコード変更で従うべきルールです。命令形であり、提案ではありません。

関数と名前

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

コメントと構造

  1. コメントはなぜを説明し、何をは説明しません。 その下の行を言い換えるだけのコメントは削除してください。ステップ番号の足場コメントは削除してください。コメントアウトされたコードは削除してください。バージョン管理が存在します。(Clean Code Ch. 4)
  2. ファイルの既存のスタイルに合わせる。 編集するファイルと少なくとも1つの隣接ファイルを書く前に読んでください。大文字小文字、インポート順序、エラー処理、ログ記録、HTTP/DBクライアントの選択をミラーリングしてください。2つ目のパターンを導入しないでください。

SOLID

  1. モジュールごとに1つのアクター。 クラスは1つの利害関係者グループ(会計、認証、レポート)にのみ責任を持つべきです。2つの無関係なサブシステムが同じクラスにアクセスする場合、分割してください。(SRP、Uncle Bob 2014)
  2. 拡張は新しいコードによるもので、編集ではない。 新しいバリアントを追加するために既存の関数に別の型タグブランチが必要な場合、最初にレジストリ、ストラテジー、またはポリモーフィックディスパッチにリファクタリングしてください。(OCP)
  3. サブクラスは親の契約を拒否しない。 メソッドをオーバーライドして「未実装」または「未サポートの操作」を通知しないでください。オーバーライドで事前条件を強化したり、事後条件を弱めたりしないでください。それが必要な場合、継承が間違っています。(LSP)
  4. 抽象化は実装ではなくクライアントとともに存在する。 インターフェース、プロトコル、または抽象的な契約を導入する場合、それを消費するパッケージに配置し、具体的なクラスの隣には配置しないでください。(DIP)

DRY、KISS、YAGNI

  1. 重複したテキストではなく、重複した知識を削除する。 似ているが異なるルールをエンコードする2つの関数はDRY違反ではありません。コード+ドキュメント+スキーマで表現された1つのルールがそうです。(The Pragmatic Programmer、「DRY」)
  2. 間違った抽象化は重複よりも悪い。 抽象化が各呼び出し元の特殊ケースのためのブランチを蓄積している場合、それを呼び出し元に再インライン化し、再抽象化する前にデッドブランチを削除してください。(Sandi Metz、「The Wrong Abstraction」)
  3. 複雑度の上限:サイクロマティック≤10、ネスト深さ≤5。 超える前にリファクタリングしてください。(McCabe 1976)
  4. 推測によるものは一切なし。 現在の呼び出し元のないオプションパラメータ、設定フラグ、環境変数、機能トグル、インターフェース、ファクトリー、または基底クラスは追加しないでください。enable_*、use_*_v2、または*_modeを追加しようとしている場合は、削除して具体的な動作を出荷してください。(Fowler、「Yagni」)

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

  1. 広範なキャッチオール処理でエラーを決して飲み込まない。 回復可能な特定のエラータイプだけをキャッチしてください。回復できない場合は、エラーを伝播させてください。キャッチハンドラーからnull/none/空の成功を返すことは、関数の契約がその動作を文書化していない限り禁止されています。(Karpathy)
  2. 境界をガードし、契約を信頼する。 信頼境界(外部入力、リクエスト/APIペイロード、デシリアライズまたはプロセス間データ、信頼できないソースからのもの)では、ハッピーパスが問題なく見えても検証してください。境界内部では、その値を宣言された型または呼び出し元の契約がすでに除外する場合、nullチェックやランタイム型チェックを追加しないでください。ガードのテストは「理論的に間違っている可能性があるか」ではなく、「信頼できないデータがここに到達できるか」です。(arXiv 2409.19182)
  3. すべてのインポートと外部呼び出しを検証する。 ライブラリのメソッドを呼び出す前に、それがインストールされたバージョンに存在することを確認してください(パッケージを読む、ロックファイルを確認する、またはインポートして検査する)。APIが「あるべき」と思われるものに基づいてコードを生成しないでください。(USENIX Security '25)
  4. プロダクションコードにハードコードされた「成功」リターンやモックフィクスチャは禁止。 実際の作業を行うと仕様に書かれている関数から{"status": "ok", ...}や定型データを返さないでください。実装できない場合は、言語の未実装または未サポート操作メカニズムを使用して明示的に失敗し、その旨を伝えてください。テストをパスさせるために、テストを無効化、スキップ、または弱めないでください。(Fowler、Claude Code issue #6984)
  5. 類似からコピーするのではなく、仕様から再導出する。 関数をコピーして修正したくなったら、止まってください。仕様から再導出してください。オフバイワンや間違ったnullセマンティクスのバグは、ほとんどの場合、類似からのコピーを通じて混入します。(arXiv 2411.01414)
  6. 境界ケースを記述する前に列挙する。 範囲、オフバイワン、null/空/1つ/多数、偶数/奇数、またはUnicode/バイト境界については、最初にコメントでケースリストを記述してください。次のステップに進む前に、コードですべてのケースをカバーしてください。
  7. 配信前にデッドコードを取り除く。 リンターまたはgrepパスを実行して、未使用のインポート、未使用のシンボル、到達不能なブランチ、「念のため」のエクスポートを確認してください。それらを削除してください。今日誰も呼び出さない関数が「いつか」のために生き残ることは許されません。
  8. 記述前に読む。 慣れていないリポジトリで記述する前に、編集するファイル、1つの隣接ファイル、およびプロジェクトルールファイル(CLAUDE.md、AGENTS.md、READMEの「規約」セクション)を読んでください。プロジェクトの既存のヘルパー、エラータイプ、ログ記録を使用してください。
  9. 数行でカバーできるものに新しい依存関係を追加しない。 パッケージを追加する前に、標準ライブラリ、すでにインストールされている依存関係、および数行のローカルコードで十分かどうかを確認してください。新しい依存関係は永続的なメンテナンスとサプライチェーンサーフェスです。再実装すべきでない真の複雑さ(暗号、解析、タイムゾーン — 例示であり、網羅的ではない)を所有している場合にのみ追加し、10行を節約するためには決して追加しないでください。references/dry-kiss-yagni.mdを参照してください。

下限 — 簡潔さのためにこれらを決して削らない

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

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

リファクタリングの規律

  1. リファクタリング時は観測可能な動作を保持する。 ユーザーが既存のコードのクリーンアップ、簡略化、またはリファクタリングを依頼した場合、契約を変更しないでください。同じ入力が同じ出力を生成し、同じ例外を発生させ、同じ副作用を持ち、同じ順序保証を提供します。リファクタリング中にバグを発見した場合は、個別にフラグを立てて、変更する前に質問してください。リファクタリングは*「観測可能な動作を変更せずに、ソフトウェアの内部構造を理解しやすく、変更コストを低くするために行う変更」*として定義されます(Fowler、『Refactoring』)。バグ修正とリファクタリングは2つの操作です。単一の変更に決してまとめないでください。

配信前の自己チェック

ユーザーに表示する前に

…

[翻訳のため一部省略]

関連スキル