AIはコードでパフォーマンス、可読性、単純性をどう両立するか

パフォーマンス、可読性、単純性のバランスが意味するもの

AIが“バランスを取った”かどうかを判断する前に、どの種類のコードについて話しているのか名前を付けると便利です。

アプリケーションロジックは製品のルールやワークフローを表すコードです：適格性チェック、価格決定、注文の状態遷移、権限、次に何をするかの手順など。最も業務に結びつき、変更されやすい部分です。

インフラコードは配管です：データベース接続、HTTPサーバ、メッセージキュー、デプロイ設定、ログパイプライン、外部連携。重要ですが、通常はアプリのコアルールをここに書きません。

3つの目標――それぞれが実際に意味すること

パフォーマンスは、コードが合理的な時間とリソース（CPU・メモリ・ネットワーク・DBクエリ）で仕事をすることを意味します。アプリケーションロジックでは、パフォーマンス問題は遅いループよりも余分なI/O（クエリの多重、API呼び出しの繰り返し）から来ることが多いです。

可読性は、チームメイトがコードが何をしているか、なぜそうしているか、どこを変更すべきかを「1回読んで」正確に理解できることを意味します。長時間“頭の中でデバッグ”する必要があるのは可読性が低いサインです。

単純性は、移動する部品が少ないこと：抽象化が少ない、特例が少ない、隠れた副作用が少ないこと。単純なコードはテストしやすく、変更も安全です。

なぜ現実のプロジェクトではこれらが衝突するか

ある目標を改善すると、他がストレスを受けることがよくあります。

キャッシュは速度を上げますが無効化ルールを増やします。強い抽象化は重複を取り除きますがフローを追いにくくします。マイクロ最適化は実行時間を縮めますが意図を不明瞭にします。

AIも“過剰に解く”ことがあります：単純な関数で済むところに汎用的なパターン（ファクトリ、ストラテジー、複雑なヘルパー）を提案することがあります。

「十分に良い」とは

ほとんどのチームにとって「十分に良い」は：

• 最小限の抽象で制御フローと命名が明確
• 現行のSLAを満たすパフォーマンス、明らかなボトルネック（特に余分なDB/API往復）を回避
• テストしやすいシーム（分離点）があり、安全に変更できること

バランスとは通常、まず保守しやすいコードをデプロイし、測定（あるいは実際のインシデント）がそれを正当化した場合にだけ凝った対策を行うことを意味します。

AIがコード構造を選ぶ典型的な方法

AIはエンジニアのように構造を“決める”わけではありません。プロンプトと学習したパターンに基づき、次に来る最も可能性の高いトークンを予測します。つまりコードの形は、あなたが何を求め、何を示したかに強く影響されます。

要求（と例）に最適化する

「最速の解をくれ」と頼めば、余分なキャッシュ、早期リターン、速度を優先するデータ構造が返ってくることが多く、実際の性能向上が僅かな場合でも複雑さが増します。「きれいで読みやすく」と頼めば、記述的な名前、小さな関数、明確な制御フローが出やすくなります。

例や既存コードスタイルを示すことは、単語だけより強力です。モデルは次を鏡像のように反映します：

• 命名規則と関数の境界
• エラー処理パターン（例外 vs 戻り値）
• 好まれる抽象（ヘルパー、サービス、リポジトリ）

監視すべき一般的な失敗モード

モデルはパターンを組み合わせるのが得意なので、「凝った」解に陥りがちです：

• 過剰設計：単純な機能に対する不必要な層や汎用ヘルパー
• 凝ったコード：密な一行表現、トリッキーな内包、チェーンが意図を隠す
• 早すぎる最適化：測定なしのマイクロ最適化

学習データがスタイルとデフォルトを形作る

モデルはクリーンなライブラリ、急ごしらえのアプリケーションコード、面接用ソリューション、フレームワーク例など混在したコードから学んでいます。だからスタイルの選択が一貫しないことがあり、時に慣用的、時に過度に抽象的、時に冗長なコードが出ます。

最終的なトレードオフは人間が決める

モデルは選択肢を提案できますが、チームのスキル、コードベースの慣習、実トラフィック、締め切り、長期的な保守コストなど、あなたの制約を完全には知りません。AIの出力を下書きとして扱い、どのトレードオフを望むか選び、意図が明確になるまで簡素化してください。

日常のアプリケーションロジックにおけるトレードオフ三角形

アプリケーションロジックは三角形の中にあります：パフォーマンス、可読性、単純性。AI生成のコードはその3つを満たそうとするので一見「合理的」に見えますが、実際のプロジェクトでは特定の部分についてどの頂点が最優先かを選ぶ必要があります。

すぐに分かるトレードオフ

典型的な例はキャッシュと明快さです。キャッシュは遅いリクエストを速くしますが、いつキャッシュが期限切れになるか、更新後にどうなるかといった疑問が生じます。ルールが不明瞭なら将来の読者は誤用したり“直した”りしてしまいます。

もう一つは抽象化と直接的なコードの緊張関係です。AIはヘルパーを抽出したり、汎用ユーティリティやレイヤー（service, repository, factory）を追加して“きれい”に見せることがあります。時に可読性が上がりますが、実際の業務ルールを間接化して単純な変更を難しくすることもあります。

マイクロ最適化が理解を損なうとき

配列を事前確保したり、巧妙な一行にまとめたり、一時変数を避けたりする小さな調整はミリ秒を削りますが、人間の理解に数分を要求することがあります。クリティカルでない経路では、それらのマイクロ最適化は通常コスト高です。明確な命名と素直なフローが勝ちます。

単純さがスケールで遅さに変わるとき

逆に、最も単純なアプローチは負荷が増えたときに破綻します：ループ内のクエリ、同じ値の再計算、必要以上に多くのデータ取得など。100ユーザーで読みやすくても100,000ユーザーで高コストになります。

実用的な経験則

まず正しくて最も読みやすいバージョンから始めてください。その上で、ログやプロファイル、実際のレイテンシ測定でボトルネックであることが分かった箇所だけを最適化します。こうするとAI出力の可読性が保たれ、必要な場所でだけ性能向上に投資できます。

適切なロジックを生成するためのAIプロンプト

AIは文字通りにやる傾向があります。プロンプトがあいまい（「速くして」）だと不要な複雑さを作ったり、間違った対象を最適化したりします。出力を制御する最善の方法は、「良い状態がどういうものか」と「やらないこと」を明示することです。

受け入れ基準（と非目標）から始める

チェックしやすい具体的な受け入れ基準を3〜6件書き、非目標を追加して“親切な”寄り道を防ぎます。

例：

• 受け入れ基準：「10kレコードで200ms未満で返すこと。エラーはユーザーフレンドリーであること。関数はだいたい40行以内。」
• 非目標：「キャッシュ無し」「新しい依存関係無し」「DBスキーマ変更無し」

モデルが推測できない制約を指定する

パフォーマンスと単純性は文脈依存なので、既知の制約を入れてください：

• レイテンシ目標（p95, p99など）
• データサイズと成長の見込み
• 同時実行（単一ユーザーか多数の並列リクエストか）
• メモリ制限（サーバレスの上限、モバイルの制約など）

ざっくりした数字でも何もないよりは有用です。

「まずはシンプル版」＋「最適化版」を要求する

2つのバージョンを明示的に要求してください。最初は可読性と素直な制御フローを優先し、2つ目は注意深い最適化を加えますが説明可能であることを条件にします。

Write application logic for X.
Acceptance criteria: ...
Non-goals: ...
Constraints: latency ..., data size ..., concurrency ..., memory ...
Deliver:
1) Simple version (most readable)
2) Optimized version (explain the trade-offs)
Also: explain time/space complexity in plain English and note any edge cases.

（上記コードブロックは翻訳しないでください）

設計判断を平易な言葉で要求する

モデルに「なぜこのデータ構造を選んだか」「なぜこの分岐順か」を説明させ、専門用語を避けた計算量の見積りも書かせてください。これによりレビューやテストで判断しやすくなります。

AI生成ロジックを可読に保つパターン

可読なアプリケーションロジックは凝った構文ではなく、「次の人（多くは未来の自分）が1回で理解できる」ことに関係します。AIを使うとき、いくつかのパターンが一貫して読みやすさを保ちます。

関数は小さく単一責務に保つ

AIは検証、変換、永続化、ロギングを1つの大きな関数にまとめがちです。検証用の関数、結果計算用の関数、保存用の関数、と分けるよう促してください。

簡便な目安：関数の仕事を「and」を使わず短い一文で説明できないなら、それは多くの場合やりすぎです。

単純な制御フローを優先する

重要な条件はネストした三項演算子や複雑な真偽チェーンではなく、明確な if ブロックとして書く方が可読です。

AI出力が「一式を一つの式でやる」場合は「早期リターン」や「ガード節」を求めてください。これはネストを減らし、ハッピーパスを見つけやすくします。

チームが保守できる名前を付ける

意味のある名前は汎用ヘルパーに勝ります。processData() や handleThing() よりも意図を表す名前を：

• calculateInvoiceTotal()
• isPaymentMethodSupported()
• buildCustomerSummary()

また mapAndFilterAndSort() のような過度に一般的なユーティリティは業務ルールを隠すので注意してください。

意図をコメントする（機械的な説明は避ける）

AIはコードをそのまま説明する冗長なコメントを出しがちです。コメントはルールの理由、守るべき前提、保護しているエッジケースに限定してください。

もし多くのコメントが必要なら、それは構造を単純化するか命名を改善すべき信号です。コメントを増やすことで隠蔽するのは避けましょう。

単純性を保つ設計選択

単純性は「コードを減らす」ことだけが目的ではありません。将来のチームメンバーが自信を持って変更できる形にすることです。AIはそれを助けられますが、形を単純に保つ選択に誘導する必要があります。

最初は最も単純なデータ構造から始める

AIは整然として見えるために賢い構造（ネストしたマップ、カスタムクラス）に飛びがちです。多くのアプリケーションロジックでは単純な配列／オブジェクトが最も理解しやすいです。

少数アイテムを扱うなら、索引を作るよりフィルタ/findで済ませる方が読みやすいことが多いです。繰り返し参照が中心になると分かったときだけmap/dictionaryを導入してください。

繰り返しニーズが出るまで抽象化を控える

抽象化はきれいに見えますが、多すぎると実際の挙動を隠します。AIにコードを求めるときは「一段の間接化」：小さな関数、明確なモジュール、直接呼び出し、を優先してください。

経験則：単一ユースケースを解決するために汎用インターフェースやプラグインシステムを作らない。二つ目か三つ目の変種が現れてから自信を持ってリファクタリングする。

深い継承ではなく合成を優先する

継承ツリーは「この振る舞いはどこから来るのか？」の答えを難しくします。class A extends B extends C よりも、小さなコンポーネントを明示的に組み合わせる方が依存関係が見えます。

プロンプトで「安定した共有契約がない限り継承を避け、ヘルパー／サービスはパラメータで渡す」と明示できます。

チームが既に理解しているパターンを使う

AIは技術的には問題ないが文化的に馴染みのないパターンを提案することがあります。慣れ親しんだパターンは機能です。スタックや規約（命名、フォルダ構成、エラー処理）に合わせるよう要求すると、結果がレビューと保守に自然に馴染みます。

可読性を損なわないパフォーマンス

性能作業はしばしば的外れなところを最適化してしまいます。最良の「速い」コードは、問題に対して適切なアルゴリズムを選ぶことです。

チューニングの前に正しいアルゴリズムを選ぶ

ループや一行の最適化を試す前に、妥当なアプローチか確かめてください：繰り返し線形探索の代わりにハッシュマップ、メンバーシップチェックにセット、複数パスの代わりに単一パスなど。AIに助けを求める際は、期待する入力サイズ、データがソート済みかどうか、どの程度「十分に速い」かを明確にしてください。

計算量が間違っている（例：大きなリストに対してO(n²)）場合、マイクロ最適化は救いになりません。

まず測定する（実データサイズで）

推測しないでください。基本的なプロファイリング、軽量ベンチマーク、そして現実的なデータ量で測定すること。AI生成コードは効率的に見えて、実は繰り返しパースや余計なクエリなど高コストな作業を隠していることがあります。

何を測ったかとその重要性を短くコメントとして残すと、次の人が元に戻さないようになります（例：「50kアイテム向けに最適化；以前は約2sでタイムアウトした」）。

ホットパスだけ最適化する

大半のコードは退屈で可読なままにしておきます。性能努力は実際に時間を費やしている箇所：タイトなループ、シリアライズ、DB/ネットワーク境界に集中させます。他は明快さを優先してください。

キャッシュ、バッチ、インデックスは慎重に使う

これらは大きな勝ちを生みますが思考負荷を増やします。

• キャッシュ： 無効化ルールとTTLをコードコメントに書く。
• バッチ： バッチサイズと失敗時の扱いを説明する。
• インデックス： どのクエリが恩恵を受けるか、書き込みコストは何かを記す。

AIがこれらを提案したら「なぜ」「トレードオフ」「いつ外すか」を含めるよう求めてください。

AI生成ロジックの安全性と信頼性

AIは“ハッピーパス”の明瞭化を優先することが多く、セキュリティや信頼性は盲点になりがちです：エッジケース、障害モード、便利だが危険なデフォルトなどです。

秘密情報を漏らさない（プロンプトやログに）

プロンプトは公開リポジトリのコメントのように扱ってください。APIキー、プロダクショントークン、顧客データ、内部URLを貼り付けないでください。出力も監視してください：AIは全リクエストやヘッダ、例外オブジェクトをログするよう勧めることがあり、そこに資格情報が含まれる場合があります。

簡便な規則：ペイロードではなく識別子をログする。デバッグのためにペイロードをログする必要がある場合はデフォルトでマスクし、環境フラグでのみ有効にしてください。

入力を検証し予測可能に失敗させる

AIが書いたコードは入力が正しい前提で進めることがあります。境界（HTTPハンドラ、メッセージコンシューマ、CLI）で検証を明示し、予期しない入力は一貫したエラー（例：400 vs 500）に変換してください。リトライが安全になるよう冪等性を考慮することも重要です。

信頼性は時間にも関係します：タイムアウトを設定し、nullを扱い、構造化されたエラーを返すことで曖昧な文字列を避けてください。

危険なデフォルトに注意する

生成コードは便利さのために短絡的なデフォルトを含めることがあります：

• 広範な権限（ワイルドカードIAM、adminスコープ）
• 弱い暗号（自家製ハッシュ、古いアルゴリズム、ソルトなし）
• 認可チェックの欠如（クライアント送信のユーザーIDを信頼）

最小権限を要求し、認可チェックは保護すべきデータアクセスの近くに置くようにしてください。

セキュリティ前提と障害モードを明示させる

実用的なプロンプトパターン：「あなたのセキュリティ前提、脅威モデル、依存が失敗した場合の挙動を説明してください。」

AIに「このエンドポイントは認証が必要」「トークンはローテーションされる」「DBのタイムアウトは503を返す」といった仮定を書かせると、その想定が現実と合わない場合にコードが誤りであることが明確になります。

維持可能性――いつリファクタするか、いつ止めるか

AIは短時間できれいなロジックを生成できますが、維持可能性は数か月をかけて得るものです。目標はコードを永遠に完璧にすることではなく、理解しやすさを保ちながら現実の要件を満たし続けることです。

フラストレーションが測定できるときにリファクタする

リファクタは次のように具体的なコストが指摘できるときに正当化されます：

• ロジックが絡まり重複しており、新機能の実装が明らかに遅い
• 同じモジュールでバグが集中する
• コードが時間のかかる箇所を隠しており、性能作業が止まる

これらが起きていなければ「掃除のための掃除」を避けてください。ある程度の重複は、理解不能な抽象を導入するコストより安いことがあります。

「なぜ」を文書化する

AI生成コードは合理的に見えますが、未来のあなたは文脈を必要とします。重要な決定について短いメモを残してください：

• なぜその部分を最適化したか（何が遅かったか）
• なぜ抽象化したか（何が何度も変わったか）
• なぜ単純なアプローチを残したか（複雑さが見合わなかった）

これらはdocstring、README、/docsの短いノート、あるいはチケットへのリンクでコード近くに置いてください。

重要なフローには軽い図を追加する

コアな経路については小さな図が誤解を防ぎます：

Request → Validation → Rules/Policy → Storage → Response
                 ↘ Audit/Events ↗

（上記図は翻訳しないでください）

これらは保守が速く、レビュアーが新しいロジックの置き場所を見つけやすくします。

「既知の限界」とリファクタ計画を残す

運用期待を書き留めてください：スケールの閾値、予想されるボトルネック、次にやること。例：「1インスタンスで秒間約50リクエストまで動作；ボトルネックはルール評価；次はキャッシュ検討」。

これによりリファクタは使用状況に対する計画的対応になり、可読性や単純性を損なう早すぎる最適化を防げます。

AI出力を速く、理解しやすく保つ実践的ワークフロー

良いワークフローはAI出力を下書き扱いにして取り扱います。目標は正しく読みやすいものを迅速に得て、実際に重要な箇所だけ性能を詰めることです。

ツールも重要です。もし Koder.ai のようなvibe-codingプラットフォーム（チャット→アプリ、計画モード、ソースのエクスポート、スナップショット/ロールバック）を使うなら同じ原則が当てはまります：まずシンプルで読みやすい実装を得て、小さくレビュー可能な変更で反復します。プラットフォームは下書きと足場作りを速めますが、トレードオフの最終判断はチームが行います。

チーム標準（プロンプト前に決める）

いくつかのデフォルトを書き下ろしておくと、AI生成の変更が一貫した期待から始まります：

• 複雑さの限界： 関数は概ね40–60行以内、深いネストを避ける、サイクロマティック複雑度は低く（例：正当化がない限り10を超えない）
• 命名規則： ドメイン用語を優先（例：invoiceTotal）、省略は使わない
• テストカバレッジ： 新しいロジックはユニットテスト（ハッピーパス＋主要エッジケース）を含める
• パフォーマンス境界： 証拠がある場合のみ最適化（遅いエンドポイント、ホットループ、測定された回帰）

生成 → レビュー → 測定 → 洗練

1. 機能と制約を記述する（入力、出力、不変条件、エラー）

2. AIに素直な実装とテストを要求する

3. 巧妙さより明快さを先にレビューする。 1文で説明できないなら複雑すぎる可能性があります。

4. 該当箇所のみ測定する。 軽いベンチや時間計測を行う。

5. 狭く具体的なプロンプトで洗練する。 「速くして」ではなく「このループの割り当てを減らしつつ関数構造を保って」といった具合に。

実用的なDo/Don't

• Do 小さく合成可能な関数と明確な命名を要求する。
• Do 例示入力/出力とテストを同じレスポンスで要求する。
• Do 意図が明らかでない場所にのみコメントを求める。
• Don't 測定なしにマイクロ最適化を受け入れない。
• Don't 他で使われない“魔法の”ヘルパーや抽象を許容しない。
• Don't チーム内で誰も変更できないAIコードをマージしない。

再利用可能なプロンプトテンプレート（コピペ用）

You are generating application logic for our codebase.

Feature:
- Goal:
- Inputs:
- Outputs:
- Business rules / invariants:
- Error cases:
- Expected scale (typical and worst-case):

Constraints:
- Keep functions small and readable; avoid deep nesting.
- Naming: use domain terms; no abbreviations.
- Performance: prioritize clarity; optimize only if you can justify with a measurable reason.
- Tests: include unit tests for happy path + edge cases.

Deliverables:
1) Implementation code
2) Tests
3) Brief explanation of trade-offs and any performance notes

（上記テンプレートは翻訳しないでください）

このループ――生成、レビュー、測定、洗練――を守れば、可読性を保ちながら性能要件も満たすコードが得られます。