ソフトウェアアーキテクチャ開発スキル

このスキルは、品質を重視したソフトウェア開発とアーキテクチャのガイダンスを提供します。Clean Architecture と Domain Driven Design の原則に基づいています。

コードスタイルルール

一般原則

• 早期リターンパターン: ネストされた条件分岐よりも、可読性を向上させるため常に早期リターンを使用してください
• 再利用可能な関数とモジュールの作成を通じてコードの重複を避ける
• 長い (80行以上の) コンポーネントと関数は、複数の小さなコンポーネントと関数に分解してください。他の場所で使用できない場合は、同じファイルに保つことができます。ただし、ファイルが200行以上の場合は、複数のファイルに分割する必要があります。
• 可能な限り関数宣言の代わりにアロー関数を使用する

ベストプラクティス

ライブラリファースト・アプローチ

• カスタムコードを書く前に既存のソリューションを常に検索してください
  • 問題を解決する既存ライブラリを npm で確認する
  • 既存のサービス/SaaS ソリューションを評価する
  • 一般的な機能については、サードパーティ API の使用を検討する
• 独自の utils や helpers を書く代わりにライブラリを使用してください。例えば、独自のリトライロジックを書く代わりに cockatiel を使用してください。
• カスタムコードが正当化される場合:
  • ドメインに固有のビジネスロジック
  • 特別な要件を持つパフォーマンスクリティカルパス
  • 外部依存関係がやり過ぎになる場合
  • 完全な制御が必要なセキュリティ関連コード
  • 徹底的な評価後に既存のソリューションが要件を満たさない場合

アーキテクチャと設計

• Clean Architecture & DDD 原則:
  • ドメイン駆動設計とユビキタス言語に従う
  • ドメインエンティティをインフラストラクチャの関心事から分離する
  • ビジネスロジックをフレームワークから独立させる
  • ユースケースを明確に定義し、分離した状態に保つ
• 命名規則:
  • 避ける 一般的な名前: utils, helpers, common, shared
  • 使用する ドメイン固有の名前: OrderCalculator, UserAuthenticator, InvoiceGenerator
  • 境界付きコンテキストの命名パターンに従う
  • 各モジュールは単一で明確な目的を持つべき
• 関心の分離:
  • ビジネスロジックを UI コンポーネントと混在させない
  • データベースクエリをコントローラーの外に保つ
  • コンテキスト間に明確な境界を維持する
  • 責任の適切な分離を確保する

避けるべきアンチパターン

• NIH (Not Invented Here) シンドローム:
  • Auth0/Supabase が存在する場合、カスタム認証を構築しない
  • Redux/Zustand を使用する代わりにカスタム状態管理を書かない
  • 確立されたライブラリを使用する代わりにカスタムフォーム検証を作成しない
• 不適切なアーキテクチャ選択:
  • ビジネスロジックを UI コンポーネントと混在させる
  • コントローラー内で直接データベースクエリを実行する
  • 関心の明確な分離がない
• 一般的な命名アンチパターン:
  • 50個の無関係な関数を含む utils.js
  • ダンプ場として機能する helpers/misc.js
  • 目的が不明確な common/shared.js
• 忘れずに: カスタムコードの1行ごとは、保守、テスト、ドキュメント作成が必要な負債です

コード品質

• 型付きキャッチブロックを使用した適切なエラーハンドリング
• 複雑なロジックを小さく再利用可能な関数に分解する
• 深いネストを避ける (最大3レベル)
• 関数を焦点を絞ったものに保ち、可能な限り50行以下に保つ
• ファイルを焦点を絞ったものに保ち、可能な限り200行以下に保つ

いつ使用するか

このスキルは、概要で説明されているワークフローまたはアクションを実行する場合に適用可能です。

制限事項

• このスキルは、タスクが上記で説明されたスコープに明確に一致する場合にのみ使用してください。
• 出力を環境固有の検証、テスト、または専門家レビューの代替と見なさないでください。
• 必要な入力、権限、安全境界、または成功基準が不足している場合は、立ち止まって明確化を求めてください。