ai-development-guide

AI Developer Guide - 技術的な判断基準とアンチパターン集

価値優先のエンジニアリング

証拠によって、システムの正確性と保守性を保ちながら、ユーザー、運用担当者、またはメンテナーに必要な価値を提供する、総合的な複雑さが最も低い解決策が特定されるまで調査します。

• 検証済みの問題は、確認済みの範囲内、または成果に必要な依存関係の範囲内で解決します。それ以外の指摘事項は、担当する境界と根拠を示して報告し、現在の変更範囲を広げないでください。
• 現在の成果、検証済みの制約、または証拠に裏付けられた重大なリスクが必要とする場合に、機能、インフラストラクチャ、抽象化、または推測に基づくエッジケースへの対処を導入します。
• リポジトリの証拠から、変更時の曖昧さ、重複する責任、欠陥のリスク、または今後の実装や検証のコストを減らすことが示されており、観測可能な製品範囲を広げない場合、確認済みの責任範囲内での動作を維持するメンテナンスは、現時点でメンテナーに価値をもたらすものとして扱います。

有効化されるすべての領域、つまりユーザーの判断、設定、モード、概念、出力、永続状態、実装経路に加え、それらに伴う UX、実行時、実装、テスト、ドキュメント、メンテナンスのコストを含めて、総合的な複雑さを評価します。実現可能なアプローチ間で異なる要素のみを比較してください。同じ確認済みの価値を、より少ない総合的な複雑さで実現できる場合は、既存の仕組みの再利用、または新たな仕組みを導入しないことを優先します。

技術的なアンチパターン（危険信号となるパターン）

以下のパターンを検出した場合は、該当する判断をいったん止め、設計を見直します。

コード品質に関するアンチパターン

1. 独立して保守される複数の場所で、同じ責任を重複させる - 重複したロジックの変更理由が共通しており、単一の所有者に集約すべきかを確認します
2. 1つのファイルに複数の責任を混在させる - 単一責任の原則（SRP）に違反します
3. 同じ内容を複数のファイルで定義する - DRY 原則に違反します
4. 依存関係を確認せずに変更する - 予期しない影響が生じる可能性があります
5. コメントでコードを無効化する - バージョン管理を使用してください
6. エラーの抑制 - 問題を隠すと技術的負債が生じます
7. 安全機構（型システム、検証、契約）を回避する - 言語が提供する正確性の保証を損ないます

設計に関するアンチパターン

• 「とりあえず動けばよい」という考え方 - 技術的負債の蓄積につながります
• つぎはぎの実装 - 既存コードに計画なく変更を加えます
• 不確かな技術を楽観的に実装する - 未知の要素が「おそらく動くだろう」と想定して設計します
• 症状への対処 - 根本原因を解決しない表面的な修正です
• 計画のない大規模な変更 - 段階的なアプローチが欠けています

フェイルファストなフォールバック設計の原則

基本原則

すべてのエラーを、完全なコンテキストとともに可視化し、追跡可能にします。フォールバックの実装よりも、主たるコードの信頼性を優先します。過剰なフォールバック機構はエラーを覆い隠し、デバッグを困難にします。

実装ガイドライン

デフォルトの方針

• すべての失敗に明示的な結果を設ける：伝播させる、境界のエラー契約に合わせて変換する、または承認済みのフォールバックで復旧する、のいずれかとします
• 失敗を明示する：エラーを可視化し、追跡可能にします
• エラーのコンテキストを保持する：再スローする際は、元のエラー情報を含めます

フォールバックが許容される場合

• 承認された復旧契約：要件、Design Doc、既存の境界契約、またはプロジェクトポリシーによって、失敗するよりも機能を縮退させるほうが望ましい理由が定義されている場合
• ビジネス上重要な継続性：部分的な機能が、何も使えない状態より望ましい場合
• 適切な縮退経路：サービスの縮退レベルが明確に定義されている場合

レイヤーの責務

• インフラストラクチャ層：

  • 元の原因と運用上の状況を保持します
  • 呼び出し元の境界契約で求められる形式で、失敗を伝播、変換、または返します
  • インフラストラクチャが所有するクリーンアップやリトライは、その境界が責任を持つ場合にのみ実行します。ビジネス上の復旧判断はアプリケーション層に委ねます

• アプリケーション層：

  • ビジネスに基づくエラー処理の判断を行います
  • 受け入れられた復旧契約で縮退時の結果が定義されている場合にのみ、フォールバックを実装します
  • 診断や復旧に必要な場合、プロジェクトで確立されているログ、メトリクス、またはユーザーに表示される状態を通じて、フォールバックの有効化を観測可能にします

エラーの隠蔽の検出

レビューのきっかけ（設計レビューが必要です）：

• 既存の復旧責務を重複させたり、分断したりするエラーハンドラーを追加する
• 単一の復旧責任者がいないまま、同じ失敗が複数のレイヤーで捕捉される
• ネストされたハンドラーによって、どの状態がコミット、ロールバック、または公開されるのかが不明瞭になる
• 縮退状態に関する観測可能な契約がないまま、ハンドラーが失敗を成功やデフォルト出力に変換する
• ログを記録せずにデフォルト値を返すエラーハンドラー

別のハンドラーであっても、文書化された復旧責任者、状態の結果、観測可能なシグナルを伴う別個の失敗モードに対応する場合は、残すことができます。

フォールバックを実装する前に：

1. このフォールバックを定義する、受け入れ済みの要件、境界契約、プロジェクトポリシー、または設計ドキュメントの記載を特定します
2. ビジネス上の正当性を文書化します
3. 診断または復旧を担う境界で、既存の UI、ログ、またはメトリクスのいずれかを通じて有効化を観測可能にします。ログを使用する場合は、機密データをマスキングしたうえで一度だけ記録します
4. 運用上の要件またはプロジェクトポリシーで必要とされる場合にのみ、新たな監視やアラートを追加します

実装パターン

AVOID: Silent fallback that hides errors
    <handle error>:
        return DEFAULT_VALUE  // Error hidden, debugging impossible

PREFERRED: Explicit failure with context
    <handle error>:
        <attach operation context>
        IF this boundary owns diagnosis: <log once>
        <propagate error>  // Re-throw exception, return Error, return error tuple

適用：言語に適したエラー処理（例外、Result 型、エラータプルなど）を使用します

コードの重複に関する基準

見かけ上の類似性が偶然によるもの、または変更理由が異なる間は、具体的な実装を分けておきます。リポジトリの証拠から、同じビジネスルール、アルゴリズム、検証契約、または連携した変更責務が複数箇所で維持されていると分かる場合は、統合します。

共通化の基準

共通化するケース

• ビジネスロジックの重複
• 複雑な処理アルゴリズム
• 一括変更が必要になる可能性が高い領域
• 検証ルール

共通化を避けるケース

• 偶然の一致（コードがたまたま同じ）
• 異なる方向に進化する可能性がある
• 共通化によって可読性が大幅に低下する
• テストコード内の単純なヘルパー

よくある失敗パターンと回避方法

パターン 1：エラー修正の連鎖

症状：あるエラーを修正すると、新たなエラーが発生する 原因：根本原因を理解せず、表面的な修正を行う 回避方法：修正の前に、なぜなぜ分析を 5 回行って根本原因を特定します

パターン 2：正しさの保証を回避する

症状：安全機構（型システム、検証、契約）を迂回する 原因：正しさに関するエラーを避けようとする衝動 回避方法：言語に適した安全機構（静的チェック、実行時検証、契約、アサーション）を使用します

パターン 3：十分なテストを行わずに実装する

症状：実装後に多くのバグが発生する 原因：Red-Green-Refactor のプロセスを無視する 回避方法：意図した動作を証明する失敗するテストから実装を始めます

パターン 4：技術的な不確実性を無視する

症状：新しい技術の導入時に予期しないエラーが頻発する 原因：事前に調査せず、「公式ドキュメントに従えば動くはず」と思い込む 回避方法：

• 実装や検証に関する判断を左右する場合は、確実性を記録します

  Certainty: low (Reason: no working examples found for this integration)
  Exploratory implementation: true
  Fallback: use established alternative approach
  

• 確実性が低い場合は、まず最小限の検証コードを作成します

パターン 5: 既存コードの調査不足

症状: 実装の重複、アーキテクチャの不整合、統合の失敗、古いパターンの採用 原因: 実装前の既存コードへの理解不足、代表的なものであるかを検証せずに近くのファイルのみを参照している 回避方法:

• 実装前に、必ず類似の機能を検索する（ドメイン、責務、設定パターンをキーワードとして使用する）
• 類似の機能が見つかった場合 → そのコントラクト、ライフサイクル、リポジトリの使用法が代表的であることを検証する。互換性がある場合は再利用または拡張し、そうでない場合は有効なモデルとならない理由を記録する
• 類似の機能が技術的負債である場合 → 現在の成果を妨げている場合、現在の変更によって引き起こされた場合、または確認済みのスコープ内にある場合は修復する。それ以外の場合は別途報告する。修復にアーキテクチャ上の決定が必要な場合は ADR を作成する
• 類似の機能が存在しない場合 → 既存の設計思想に従って新機能を実装する
• 各々の再利用、拡張、分離、修復の決定について、該当する実装記録または設計記録に根拠を保存する
• 参照の代表性チェック: 近くのコードからパターンや依存関係を採用する場合、採用前にそれがリポジトリ全体で代表的であることを検証する — 近くのファイルだけでは根拠として不十分です

品質保証メカニズムの認識

品質チェックを実行する前に、変更領域に対してどのような品質メカニズムが存在するかを特定します:

• 主要な検出: 変更領域のファイル種別、プロジェクトマニフェスト、設定を調査して、該当する品質ツールを特定します
  • CI パイプライン定義を確認し、影響を受けるパスをカバーするチェックがあるか調べます
  • ドメイン固有のリンターまたはバリデータの設定（例: スキーマバリデータ、API 仕様バリデータ、設定ファイルリンター）があるか確認します
  • プロジェクト設定にドメイン固有の制約（命名規則、長さ制限、フォーマット要件）があるか確認します
• 統括する作業成果物が提供する検証方法を、変更固有のチェックとして実行します
• 発見したドメイン固有のチェックを、以下の標準的な品質フェーズと併せて含めます

品質チェックワークフロー

リポジトリに設定されている品質エントリポイントと、それらがカバーするカテゴリを把握します。以下のカテゴリを、該当するエビデンスチェックリストとして使用します:

• 静的チェック: フォーマット、リンティング、未使用コードの検出、型チェック、および設定済みの静的解析
• ビルドチェック: コンパイルまたは本番ビルド、依存関係の解決、および設定済みのリソース検証
• 動作チェック: 変更された動作を検証する最小の設定済みテスト。加えて、変更がその境界を越える場合、生成されたスケルトンがそれを必要とする場合、またはリポジトリのゲートに含まれている場合は、統合テストまたは E2E スイート

リポジトリで宣言されたコマンドの構成や順序が存在する場合はそれに従います。存在しない場合は、コマンドの依存関係を尊重し、有用なフィードバックが得られる順序を選択します。完了には、該当する設定済みのチェックがすべて成功することが必要です。

技術的な決定を要する状況

抽象化のタイミング

• リポジトリのエビデンスによって共有の責務と協調的な変更パターンが確立された後に、共有の抽象化を抽出する
• YAGNI を意識し、現在必要な機能のみを実装する
• 将来の拡張性よりも、現在のシンプルさを優先する

パフォーマンスと可読性

• プロファイリングによって測定可能なボトルネック（例: SLA を超える応答時間、割り当てを超えるメモリ）が特定されない限り、可読性を優先する
• 最適化の前に測定する
• 最適化する場合は、理由をコメントで記録する

コントラクトとインターフェースの粒度

• 過度に詳細なコントラクトは保守性を低下させる
• 各メソッドが単一のドメイン操作に対応し、パラメータの型がドメインの語彙を使用するようにインターフェースを設計する
• 抽象化メカニズムを使用して重複を減らす

スコープの拡大

• 実装・編集の指示は、受け入れられた成果とその適用範囲に適用します。
• 適用範囲を定める依頼または確認済みの成果、望ましい将来要件、非目標に含まれる明示的な制限や数量（「1つ」、「このファイル」、「Xのみ」）は厳格な境界として扱います。リポジトリの証拠によって技術的成果物の How が無効だと判明した場合は、これらの境界を変えずに、修正可能なベースラインとして扱います
• 参照されているパスや想定されるパスは、適用範囲を定める元の情報で明示的に限定されていない限り、調査の出発点として扱います
• コピー／移動／ミラーの依頼では、内容をそのまま保持します。内容を編集するのは依頼された場合のみです
• 移植／翻訳の依頼では、意図と動作を維持します。移植先の状況に必要な範囲でのみ調整します
• 同じ受け入れられた成果または一貫性の契約に必要であることが証拠から明らかな場合は、関連ファイル、対称的な箇所、隣接する動作も含めます。無関係な改善は別途報告します

実装の完全性を確保する

影響分析：リスクに応じた3段階のプロセス

実装前に、以下の段階を順に完了してください。公開契約、データフロー、統合、設定に影響しない独立した変更では、簡潔なメモまたは検索結果で十分です。境界をまたぐ変更、リスクの高い変更、複数の利用者に影響する変更では、構造化されたレポートを使用してください。

1. 調査 - 影響を受けるコードを特定します：

• 実装の参照箇所（インポート、呼び出し、インスタンス化）
• インターフェースの依存関係（契約、型、データ構造）
• 動作に関係するテストの証拠
• 設定（ビルド設定、環境設定、機能フラグ）
• ドキュメント（コメント、ドキュメント、図）

2. 理解 - 特定した各箇所を分析します：

• システム内での役割と目的
• 依存関係の方向（利用側または提供側）
• データフロー（起点 → 変換 → 出力先）
• 結合の強さ

3. 特定 - 変更に必要な深さで、影響を受ける単位、リスク、実装順序を記録します。詳細な分析には、以下を使用します：

## Impact Analysis
### Direct Impact
- [Unit]: [Reason and modification needed]

### Indirect Impact
- [System]: [Integration path → reason]

### Data Flow
[Source] → [Transformation] → [Consumer]

### Risk Assessment
- High: [Complex dependencies, fragile areas]
- Medium: [Moderate coupling, test gaps]
- Low: [Isolated, well-tested areas]

### Implementation Order
1. [Start with lowest risk or deepest dependency]
2. [...]

調査と理解によって、受け入れられた成果、適用範囲を定める境界、必要な隣接依存関係が網羅され、重要な各リスクに対して実装、検証、または未解決の判断事項が割り当てられたら、次に進みます。

未使用コードの削除

依頼された変更によって不要になった成果物が見つかった場合：

• 呼び出し元と生成時・運用時の使用箇所を確認したうえで、同じ変更内で削除します
• 不要になったか不確かな場合、または削除によって受け入れられた成果や適用範囲を定める境界を超える場合は、保持してその旨を報告します
• 実装範囲外の、無関係な休眠コードはそのままにします

既存コードの変更

Required by the requested change? No → Preserve unless the change proves it obsolete
                               Yes → Working and compatible? Yes → Fix/Extend
                                                             No → Repair or replace with migration/rollback evidence

原則：壊れたコードへのパッチ適用より、適切な実装を優先します