clean-code

クリーンコード

モデルを選ぶ前に、ブランチを選択してください。コーディネーターの作業と決定的なコマンドは、呼び出しの権限内で実行します。現在のロールでこの手法を適用してください。ワーカーへのディスパッチは行いません。ワーカーをディスパッチする場合は、shared/references/model-preview.md と、そこで承認されている唯一のルートスナップショットを使用してください。ネストされたスキルとランナーは、再選択やワーカーなしでそれを使用します。

動作をデフォルトで維持しながら、既存のコードを読みやすく、変更時の安全性を高め、テストしやすくします。

運用ルール

• ユーザーが動作変更を明示的に求めない限り、動作を維持してください。変更が依頼の一部でない限り、公開 API、副作用、エラーの動作とメッセージ、パフォーマンス特性、観測可能なタイミングに関する前提、エッジケース、データ構造を安定させてください。
• 広範な書き換えよりも、役に立つ最小限の変更を優先してください。
• コメントや抽象化を追加する前に、名前を改善してください。
• ドメインの用語を見える状態に保ってください。ビジネスルールを汎用ヘルパーの背後に隠さないでください。
• 重複したコードが同じ概念を表し、同じ理由で変更される場合にのみ、重複を取り除いてください。
• 実際の複雑さを明確に軽減しない限り、新しいパターン、依存関係、フォーマットの大幅な変更、モジュールの移動は避けてください。
• テストが不足または不十分で、リファクタリングにリスクがある場合は、構造を大きく変更する前に、既存のテストを改善するか、動作を維持するための集中的な特性テストを追加または提案してください。依拠できるテストがないレガシーコードでは、まず safe-incremental-coding を適用してから、ここに戻ってください。

ワークフロー

1. コードを理解します。

   • コードの目的、公開インターフェース、入力、出力、副作用、不変条件、フレームワークの制約、既存のテストを特定します。
   • ユーザーがレビューのみを依頼した場合は、編集せずに問題点を報告します。

2. 作業を分類します。

   • 命名、定数化、簡単な抽出、制御フローの明確化には local cleanup を使用します。
   • 動作を維持する構造的な変更には refactor を使用します。
   • ユーザーが動作変更を許可した場合、または依頼されたバグが明らかな場合に限り、bug fix plus cleanup を使用します。
   • ユーザーが明示的に依頼しない限り、redesign は対象外として扱います。
   • 安全な方法に再設計、依存関係の変更、または依頼の範囲を超える動作変更が必要な場合は、作業を止め、選択肢をユーザーに報告してください。

3. 改善点を選びます。

   • 意図が分かりにくい識別子の名前を変更します。
   • マジック値を意味のある定数として切り出します。
   • ドメイン上の実際の手順に名前を付ける場合は、小さなヘルパーを切り出します。
   • ガード節を使って、入れ子になった制御フローを平坦化します。
   • 解析、検証、ビジネスルール、永続化、フォーマット、オーケストレーション、副作用が絡み合っている場合は、分離します。
   • 既存のエラーを弱めずに、エラー処理の一貫性を高めます。

4. 安全に編集します。

   • 変更を依頼されたコードパスに限定します。
   • 可能な場合は、一度に一つの論理的な改善を行います。
   • 上記のルールに照らして、変更が動作を維持していることを再確認します。
   • 明快なコードを、巧妙なコードに置き換えないでください。

5. 検証します。

   • 利用できる場合は、最も関連性の高い既存のテストやチェックを実行します。
   • テストを実行できない場合は、その理由を説明します。
   • 名前が意図を表しているか、関数が役割に集中しているか、抽象化のレベルが一貫しているか、コメントが正確か、副作用が見える状態かを再確認します。

コードの臭いチェックリスト

臭いを名前で診断してください。何かを変更する前に、どの臭いがあるかを述べてください。臭いに名前を付けることで修正が明確になり、変更によって振る舞いが変わるのを防げます。以下の各項目は専門用語です。言い換えず、用語を使ってください。

• 命名の臭い：不明瞭な名前、マジック値。
• 関数の臭い：長い関数、深いネスト、複雑なブール式、フラグ引数、抽象度の不統一。
• 責務の臭い：責務の混在、大きなクラス、隠れた変更。
• データの臭い：プリミティブ型への執着、データの塊、長い引数リスト。
• 重複の臭い：ロジックの重複（同じ概念で、変更する理由も同じ場合に限ります）。
• コメントの臭い：コードの繰り返しや弁解に終始するノイズの多いコメント。
• 安全性の臭い：一貫性のないエラー処理、脆弱なテスト、またはテストの欠如。

臭いを示してから、それに対応する改善を適用してください。「この引数にはプリミティブ型への執着とデータの塊があります」は、各編集の前に述べるべき文の例です。

命名ガイド

• elapsedTimeInDays、customerRepository、isEligibleForDiscount、calculateInvoiceTotal、parsePaymentRequest のように、意図が伝わる名前を優先してください。
• data、info、manager、processor、helper のような曖昧な名前は、ドメインで実際にその用語が使われている場合を除き、避けてください。
• ブール値は自然に読める名前にしてください。例：isActive、hasPermission、canRetry、shouldNotifyCustomer。
• 可能な場合、関数名には動詞を使ってください。例：calculateTotal、validateRequest、loadCustomer、sendReceipt、formatCurrency。

コメント

すべてのコメントを、価値あるコメントかノイズかに分類してください。コメントが価値あるものとなるのは、コードだけでは伝えられない情報（ビジネスルール、外部制約、セキュリティ上の懸念、パフォーマンス上のトレードオフ、歴史的背景、明白でない判断）を含む場合に限ります。編集時に、その理由も述べてください。「これは価値あるコメントです。パラメーター名だけでは伝えられない認証上の制約を記録しています」のようにします。それ以外はすべてノイズです。コードの説明を繰り返すコメント、当たり前のことを言い直すコメント、名前の変更や抽出をすべきコードを弁解するコメント、または AI が書いたような（謝罪的なもの、仮置きのもの、変更内容を逐一語るもので、熟練した開発者なら残さないような）コメントは削除してください。

• 価値あるコメントは残してください。ビジネスルール、外部制約、セキュリティ上の懸念、パフォーマンス上のトレードオフ、歴史的背景、明白でない判断が該当します。
• 価値のないコメントは削除してください。コードの説明を繰り返すもの、当たり前のもの、古くなったもの、AI が書いたようなコメントが該当します。

出力要件

結果を返す際は、以下を含めてください。

• summary：改善した内容。
• key_improvements：可読性、保守性、安全性、テスト容易性に関する主な改善点。
• behavior_changes：振る舞いを維持した場合は none と記載してください。それ以外の場合は、何をなぜ変更したかを正確に説明してください。
• validation：実施したテストやチェックとその結果。
• risks：不足しているテスト、不明確な要件、フレームワーク上の制約、または追加レビューが必要な領域。

レビューのみのタスクでは、重大度の高い順に指摘を示し、可能であればファイル名と行番号も記載してください。

注意点

このスキルの元となった書籍の文章を引用したり、再構成したりしないでください。