nestjs-professional-software-engineering

プロフェッショナルなソフトウェアエンジニアリング

既存のプロジェクトを尊重しながら、正確で慣用的、安全で読みやすく、保守・テスト・拡張しやすい NestJS ソフトウェアを開発します。

実行前の競合ガード

ファイルを編集したり、状態を変更するコマンドを実行したりする前に、有効な指示を照合してください。読み取り専用の調査は続行できます。

前提条件

リポジトリの指示、作業ツリー、マニフェスト、インストール済みバージョン、ソースと呼び出し元、コントラクト、規約、チェック項目を確認してください。無関係な変更は保持してください。不確かな構文やバージョン依存の構文は、インストール済みの型やソース、公式ドキュメントで検証してください。API をでっち上げてはいけません。判断が重複する場合に限り、ほかの有効なスキルを確認してください。

主な担当範囲

このスキルは、プロジェクトの調査、最小限の実装、バージョン互換性のある構文、API の使いやすさ、テスト、検証を担当します。インストール済みで関連性がある場合は、以下と連携してください。

• nestjs-architecture-principles：モジュール、依存関係、データ、トランザクションの境界。
• nestjs-oop-design-patterns：オブジェクトの責務、不変条件、パターン。
• nestjs-features-performance：ライフサイクル、API／セキュリティ、テスト、ランタイム、パフォーマンス。
• nestjs-code-audit：品質を示す読み取り専用の証拠と、重複を排除した報告。
• nestjs-feature-audit：ブランチ固有のロードマップ上のゲートと機能報告。
• nestjs-git-commit-pr-message：承認された Git 公開と CI のフォローアップ。

これらは判断の境界であり、必須の依存関係ではありません。作業を別のワークフローに引き継ぐ場合も、ドメイン上の担当範囲を維持してください。

競合の確認

編集やコントラクトの不整合、コマンドの順序や副作用、担当者の競合、バージョン、証拠、承認、リポジトリの前提条件の未達を確認してください。明示されたユーザーの意図、リポジトリのコントラクト、検証済みのランタイム制約、そして最も範囲の狭い担当者の順に従って解決してください。各判断の主担当は一人にし、互いに両立しない助言に合わせるために複数の設計を並行して作成してはいけません。重大な競合が残る場合は、変更を加える前に停止し、必要最小限の判断をユーザーに確認してください。監査は読み取り専用のまま実施してください。修正の明示的な承認は、独立した実装フェーズで適用してください。

必須のワークフロー

足場を作成したり、新しい境界を導入したりする前に、プロジェクトプロファイルを記録してください。健全なローカル規約に従い、インストール済みのジェネレーターとバージョンのコントラクトを検証してください。

実装の依頼では、変更と検証までワークフローを完了してください。レビューや診断の依頼では、ユーザーが実装も承認していない限り、ファイルを変更せず、証拠を調査して報告してください。

1. 調査

1. リポジトリの範囲と適用される指示を確認します。
2. 言語、フレームワーク、ランタイム、パッケージマネージャー、および関連する正確なバージョンを特定します。
3. 関連する実装、呼び出し元、テスト、設定、マニフェスト、公開コントラクトを読みます。
4. 類似機能の命名、エラー処理、テスト、API の規約を検索します。
5. 対象を絞ったテストと、より広範なテスト、型チェック、リンター、フォーマット、ビルド、スモークテストのコマンドを特定します。

最初から広範囲な書き換えを始めないでください。変更前に現在の動作を把握してください。

2. 理解

以下を定義します。

• 要求された成果と、観測可能な受け入れ基準。
• 影響を受ける境界と利用者。
• 互換性、セキュリティ、データ、パフォーマンス、デプロイ、移行への影響。
• 解決策を大きく左右する前提。

不足している判断がアーキテクチャ、公開動作、セキュリティ、データ、コスト、互換性に重大な影響を与える場合に限り、確認してください。

3. 最も明確で有効な構文を選択する

次の順序で根拠を確認します。

1. 既存リポジトリの規約と、互換性のある公開動作。
2. インストール済みのコンパイラー、ランタイム、パッケージのバージョン、型、ソースコード。
3. 使用バージョンに対応する、言語またはフレームワークの公式ドキュメント。
4. ドキュメントで不明点が残る場合は、最小限のローカル実験または型チェック。
5. コミュニティの例は調査の手がかりとしてのみ使用し、API の仕様とは見なさないでください。

便利な構文があれば、直接的で明示的な形式と比較してください。プロジェクトでサポートされ、なじみがあり、呼び出し側と実装側の双方で明確になる場合は、現代的なイディオムを優先します。

言語またはフレームワークの構文を選ぶ際は、syntax-and-idioms.md を読み込んでください。

4. 一貫性のある最小限の変更を設計する

設計では、次の点を満たす必要があります。

• 検出された言語およびフレームワークに適した慣用的なものであること。
• 既存のアーキテクチャと規約に沿っていること。
• 一貫性があり、テスト可能で、デフォルトで安全であり、破壊的変更が許可されていない限り後方互換性があること。
• 意味のある状態変更、作用、失敗の仕方、コスト、制御について明確であること。

公開 API では、一般的な操作が分かりやすく、不正な使用が起こりにくいようにしてください。段階的な開示を優先し、一般的なケースには便利な方法を用意し、呼び出し側に意味のある制御が必要な場合にのみ、より低レベルな方法を提供してください。

判断基準と API の例については、syntactic-sugar.md を読み込んでください。

5. 実装する

• 検出されたツールチェーンでサポートされる、有効で現代的な構文を使用してください。
• 関数、クラス、モジュール、コンポーネント、サービスの役割を明確にしてください。
• 確立された命名、書式、構成、検証、エラー処理の規約に従ってください。
• 信頼できない入力は境界で検証し、機密情報を保護してください。
• 対応可能な、情報を漏らさないエラーで、失敗を明示的に処理してください。
• 関連する場合は、並行処理、トランザクション、冪等性、再試行、タイムアウト、キャンセル、クリーンアップ、可観測性を考慮してください。
• 不要な依存関係、推測に基づく抽象化、巧妙なワンライナー、隠れたグローバル状態、暗黙的な副作用、無関係な整理は避けてください。
• コメントでは、自明な構文ではなく、意図や制約を説明してください。

6. テストと検証を行う

観測可能な動作、関連するエッジケース、不正な入力、失敗経路、セキュリティ上重要な動作、回帰、公開 API の互換性を対象とする、決定論的なテストを追加または更新してください。

変更に応じて適切なチェックを実行してください。

1. 対象を絞ったテスト。
2. リスクに応じた、より広範なテスト。
3. 型チェックまたはコンパイル。
4. リントと書式の検証。
5. ビルドまたはパッケージ化。
6. 実行時、生成されたコントラクト、またはマイグレーションのスモークチェック（実施可能な場合）。

合格させるためにテストや制御を弱めてはいけません。チェックが正常に実行されていない限り、合格したと報告してはいけません。

リスクに基づく検証については、implementation-verification.md を読み込んでください。

7. 報告する

まず完了した内容を述べ、その後、次の点を説明してください。

• 重要な設計上および構文上の判断。
• 変更したファイルまたは領域。
• 実施したチェックとその結果。
• 残っている制限、リスク、マイグレーション、または追加対応。

報告は簡潔にし、検証済みの事実と仮定、未実施のチェックを区別してください。

シンタックスシュガーのルール

次の条件を満たす場合にのみ、シンタックスシュガーを使用してください。

• 意味のある手間や、繰り返し起きる誤用を減らすこと。
• 実際にそのリポジトリを保守する人にとって、読みやすさが向上すること。
• 予測可能な動作、型付け、デバッグ、合成可能性を保つこと。
• 意味のあるコスト、I/O、状態変更、ネットワーク通信、認可、トランザクション、エラー処理、ライフサイクルを隠さないこと。
• 高度な呼び出し側に制御が必要な場合、明示的な方法を残すこと。
• 現実的な例を使って、ドキュメント化とテストができること。

単にコードを短くするだけの糖衣、独自の小さな言語を作るもの、曖昧な入力を多義的に扱うもの、意外な型変換に依存するもの、スタックトレースやエラーを理解しにくくするものは採用しないでください。

期待する回答

実装作業では、実現した動作と検証内容を報告してください。構文の選択が重要な場合は、次の点も述べてください。

• 確認された慣例： 関連するリポジトリのパターン。
• 検討した選択肢： 明示的な形式と簡潔な形式。
• 選択した構文： その構文がサポートされており、最も明確である理由。
• 隠れた動作の確認： 影響、コスト、失敗、制御のうち、引き続き明示されるもの。
• 互換性： 影響を受ける呼び出し元と、必要に応じて移行方法。

実装を求められた場合、提案するコードスニペットだけを返さないでください。

参照先の案内

タスク	読み込む資料
慣用的で、バージョン互換性のある構文を選ぶ	syntax-and-idioms.md
シンタックスシュガーや公開 API の使いやすさを設計またはレビューする	syntactic-sugar.md
実装範囲を定め、検証の深さを選ぶ	implementation-verification.md