kiss

KISS — シンプルに保つ

適用する前に

.agents/stack-context.md が存在する場合は、まずそれを読んでください。この原則は、検出されたスタックに適した慣用的なパターンを使って適用してください。フレームワーク固有の詳細については、context7 MCP またはウェブ検索を利用してください。推測しないでください。

原則

同じ結果が得られる2つの解決策がある場合は、読みやすく、理解しやすく、変更しやすい方を選んでください。

本番環境でこれが重要な理由

シンプルなコードは、本番環境でも持ちこたえます。複雑なコードは、診断や修正が難しく、修正によって別の箇所が壊れていないか確認するのも難しい形で問題を引き起こします。インシデント対応は、誰かがプレッシャーのかかる状況でコードを読むところから始まります。すぐに理解できなければ、障害は長引きます。

複雑さは積み重なります。今日の「少し気の利いた」解決策は、3人の異なる開発者が6か月にわたってパッチを重ねるうちに、「理解不能な」解決策になります。

最も危険なバグは、ひとりの人が頭の中だけで把握できないほど複雑なコードに潜んでいます。

ルール

1. 書きやすさではなく、読みやすさを最適化してください。 コードは書かれる頻度より10倍多く読まれます。説明コメントが必要な一行のコードより、数行多くても明快なコードの方が優れています。
2. 枯れた技術を使ってください。 新奇なツール、パターン、ライブラリより、十分に理解されているものを優先してください。新奇な解決策には、デバッグ、採用、ドキュメント作成における隠れたコストが伴います。
3. ネストの深さを制限してください。 関数のネストが3階層を超える場合は、早期リターン、ガード節、またはヘルパー関数への切り出しでフラットにしてください。
4. 1つの関数には1つの役割を持たせてください。 関数の処理内容を説明するのに「そして」という言葉が必要なら、分割してください。
5. 実装方法ではなく、役割を表す名前を付けてください。 query_db_filter_status_map_results() ではなく get_active_users() とします。
6. 気の利いた小技は避けてください。 ビット演算によるハック、複雑な解析を行う正規表現の一行コード、直感的でない操作のための演算子オーバーロードなどは、読み手の理解ではなく書き手の自己満足を優先します。
7. 暗黙的なものより明示的なものを優先してください。 マジック値、隠れた状態、暗黙の型変換、遠隔作用は、コードの予測を難しくします。

アンチパターン

• 時期尚早な最適化： 効果があることを示すプロファイリングデータがないのに、パフォーマンスのために可読性を犠牲にすること
• 抽象化のやりすぎ： ファクトリーを作るファクトリーパターン、深くネストしたジェネリック、単純なタスクのためのフレームワーク
• 気の利いた一行コード： ロジックを不明瞭になるほど圧縮した密な式
• 神関数： 複数の関心事を扱う200行以上の関数
• 文字列に依存した型システム： 列挙型、型、定数を使えば明確になるところで、生の文字列を使うこと
• 隠れた制御フロー： リクエスト到着後に何が起きるかを追跡できなくするデコレーター、ミドルウェアチェーン、イベントシステム

例

-- Overly clever
users = {u.id: u for u in db.query(User) if u.active and u.role in roles and not u.banned}

-- Simple and scannable
active_users = db.query(User).where(active=true, banned=false)
users = filter_by_role(active_users, roles)
users_by_id = index_by(users, key="id")

-- Deeply nested
def process(data):
    if data:
        if data.valid:
            if data.type == "order":
                if data.items:
                    # actual logic buried 4 levels deep

-- Flattened with guard clauses
def process(data):
    if not data:
        return
    if not data.valid:
        return
    if data.type != "order":
        return
    if not data.items:
        return
    # actual logic at top level

適用範囲

• シンプルとは、単純でよいという意味ではありません。 エラー処理、入力検証、適切なデータ構造は「複雑さ」ではなく、正しさを支えるものです。シンプルさを理由に安全性を取り除かないでください。
• シンプルとは、原始的でよいという意味ではありません。 適切に選んだライブラリやパターン（複雑な状態遷移のためのステートマシンなど）を使う方が、同等のロジックを自作するよりシンプルな場合があります。
• 本質的に複雑な分野もあります。 暗号技術、分散合意、金融計算には、避けられない複雑さがあります。KISS とは、その上に不要な複雑さを加えないことです。
• DRY との兼ね合い： 抽象化を導入するより、数行を重複させる方がシンプルな場合もあります。新しいチームメンバーが30秒で理解できる方を選んでください。

コードレビューのチェックリスト

• 新しいチームメンバーが、作者に尋ねずにこのコードを理解できますか？
• 行数は減っても明快さを損なう「気の利いた」近道はありませんか？
• 全体を通してネストの深さは3階層以下ですか？
• すべての関数に、明確で単一の責務がありますか？
• 複雑なロジックを、名前の付いたヘルパー関数に置き換えられませんか？
• 「何を」説明するコメントはありませんか？（ある場合、コード自体が十分に明確ではありません。）

関連するスキル

• yagni：まだ必要のないものを構築していることが複雑さの原因である場合
• separation-of-concerns：責務が混在していることが複雑さの原因である場合
• solid：モジュール設計の不備が複雑さの原因である場合