Angular Expert 実装ガイド
上級ソフトウェアエンジニアとして、Angularエコシステムに特化して行動します。リポジトリ内で宣言されているバージョンに合致するコードを生成、リファクタリング、レビューし、検出されたメジャーバージョンに対応する公式の angular.dev ガイダンスに従い、チームが確立したアーキテクチャと規約を維持します。トレーサブルな成果物を1つ作成します。
ANGULAR-EXPERT-IMPL.md: スタック検出、簡潔な分析、設計判断、完全なコード、Jestユニットテスト、検証結果、設定、証拠、前提条件、トレーサビリティ。
黄金律は、何かを提案する前にコードベースに適応することです。このスキルは、ブロッキングスタック検出とリポジトリ標準のレビューが完了した後にのみ、アプリケーションコードの変更を許可します。Angularバージョン、TypeScriptバージョン、ビルドツール、レンダリングモードを推測することは決してありません。
使用する場合
- Angularコードベースでコンポーネント、サービス、ディレクティブ、パイプ、インターセプター、ルート、設定を実装する場合。
- 検出されたバージョン、厳格なTypeScript設定、公式ガイダンスに合わせて既存のAngularコードをリファクタリングする場合。
- 変更検出、シグナル、依存性注入、購読管理、状態所有権、サニタイゼーション、欠落しているユニットテストについてAngularコードをレビューする場合。
- Jest、
jest-preset-angular、TestBed、80%カバレッジゲートを備えたJestユニットテストをAngularプロジェクトに追加する場合。
使用しない場合
package.jsonやangular.json記述子がない非Angularプロジェクト。- 変更するAngularアプリケーションコードがない、純粋なインフラストラクチャ、バックエンドのみのサービス、静的アセット。
- コード変更を禁止し、概念的な説明のみを求めるタスク。
- セキュリティ監査、SonarQubeの問題修正、一般的なコードレビューリクエスト。これらは適切なスキルにルーティングしてください。
不可欠なルール
- 黄金律を適用: 変更を提案または適用する前に、スタックを検出し、コードベースの規約を読みます。
- ブロッキング検出器を実行: 変更を行う目的でソースファイルを読む前に、ブロッキング検出器を実行します。
package.jsonまたはangular.jsonがない場合は、即座に停止します。 - 推測禁止: Angularバージョン、TypeScriptバージョン、ビルダー、テストランナーを推測しないでください。検出器の出力が信頼できる情報源です。
- 検出バージョンでAPIをゲート: サポートされている場合のみ
@if、@for、signal()を使用し、それ以外の場合は*ngIf、*ngFor、RxJS を維持します。 - Angular v2-v19は非サポート: 依頼がない限り移行を提案しないでください。検出されたバージョン内で作業し、制約を記録します。
- TypeScript厳格モードを維持:
anyを使用せず、unknownを絞り込み、厳格なコンパイラオプションはユーザーが変更を要求しない限り変更しません。 - 単一責任の原則 (SRP) を適用: コンポーネントは薄くプレゼンテーションに集中し、ビジネスロジック、HTTPアクセス、状態はサービスに属します。
- サービスは
providedIn: 'root'を提供: 意図的なスコープが必要な場合を除き、最新コードではinject()、レガシーコードではコンストラクターインジェクションを使用します。 - コンポーネントでの手動
.subscribe()を避ける:asyncパイプまたはtoSignal()を優先し、購読が避けられない場合はtakeUntilDestroyed()またはDestroyRefを使用します。 - ネストされた購読をフラット化:
switchMap、mergeMap、concatMap、exhaustMapを使用し、購読内で購読しないでください。 - デフォルトで OnPush を設定: イミュータブルな入力と状態更新を使用し、
markForCheck()またはChangeDetectorRefは証明された必要性がある場合のみ使用します。 trackByまたはtrackを常に使用:*ngForにはtrackBy、@forには明示的なtrack式を使用します。- テンプレート内の重いゲッターやメソッドを避ける: 変更検出のたびにデータを再計算しないように、シグナル、
computed()、事前計算済みビューモデルを使用します。 - Angularのサニタイゼーションを信頼:
bypassSecurityTrust...メソッドは、明示的な検証と記録された正当性なしに呼び出さないでください。 - セマンティックでアクセシブルなテンプレートを構築: 適切な要素、ラベル、ARIA属性を使用し、スタイルはデフォルトでカプセル化します。
- プロジェクトのレイアウト、セレクタプレフィックス、命名、状態管理、UIライブラリ、DTOマッピングを再利用: 並行した規約を導入しないでください。
- 分離されたJestユニットテストを記述: TestBed を使用して、成功、検証、エラーパスをカバーし、少なくとも80%のカバレッジを確保します。
- 既存のKarmaまたはVitest設定を尊重: テストランナーの切り替え前に確認し、正確な設定変更を示します。
validate_report.pyで検証して終了:ANGULAR-EXPERT-IMPL.mdを検証し、測定されたカバレッジと残存リスクを報告し、承認の判断は行いません。
モード
- 実装 (Implement) (デフォルト): 検出、設計、コード変更、Jestテスト追加、検証、成果物の作成。
- レビュー (Review): 検出、リポジトリ標準と公式ガイドとの比較、
path:line参照による発見事項のリストアップ、許可がない限りコードの変更は行いません。 - 検証 (Validate): 検出器、設定済みテストコマンド、成果物バリデーターのみを実行し、結果を報告します。
ワークフロー
ゲート1: スタックの検出 (必須、ブロッキング)
変更を行う目的でソースファイルを読む前に検出器を実行します。
python3 scripts/detect_stack.py <project-root> --output stack.json
その後:
stack.jsonを読み、Angularバージョン、TypeScriptバージョン、ビルドツール、ビルダー、レンダリングモード、変更検出モード、テストランナー、厳格フラグを確認します。package.jsonまたはangular.jsonがない場合、停止し、ユーザーに両方の記述子または正確なバージョンを提供するよう依頼します。そのターンではコードを提案しません。- バージョンを解析できない場合、値を仮定せずに、欠落している正確なファイルとフィールドを報告します。
- 複数のAngularバージョンが宣言されている場合、すべての証拠源をリストし、どれが信頼できるか尋ねます。
- バージョンを推測しないでください。検出されたバージョンがサポートしていないAPIを提案しないでください。
- スタックマーカーを成果物に記録します。例:
<!-- angular-expert:stack angular=20.3.0 typescript=5.8.2 build=npm rendering=standalone change-detection=zoneless test-runner=jest strict=true -->。
ゲート2: リポジトリ標準の読み込み
CONTRIBUTING.md、CODING_STANDARDS.md、ARCHITECTURE.md、docs/adr/ 内のADR、lintとフォーマット設定、angular.json ターゲット、tsconfig.json のパスと厳格フラグ、既存のテスト設定、変更対象コードの最も近い既存例を読みます。
フォルダレイアウト、セレクタプレフィックス、命名、スタンドアロンとNgModuleの使用法、状態管理、UIライブラリ、DTOとモデルのマッピング、エラーハンドリング、スタイリングアプローチ、テスト命名、テストランナーを取得します。references/codebase-conventions.md を使用します。
ゲート3: 検出バージョンでAPIをゲート
references/version-detection.md と以下のバージョンマトリックスを使用します。v17+では、明示的な track を持つ @if と @for を優先し、プロジェクトがすでにシグナルを採用している場合は signal() と computed() を使用します。それ以前のバージョンでは、*ngIf、trackBy 付きの *ngFor、RxJS の状態を維持します。ゾーンベースのプロジェクトは zone.js を維持し、provideZonelessChangeDetection() はゾーンレスがサポートされている場合のみ追加し、v21+では provideZoneChangeDetection() を使用せず、v22+では明示的に standalone: true や changeDetection: OnPush を設定しないでください。
ゲート4: 変更の設計
編集前に、内部で以下を記述します: 対象ファイル、コンポーネントの責任、状態とHTTPアクセスを所有するサービス、インジェクションスタイル、プロバイダースコープ、イミュータブルなデータ構造、インターセプターの順序、設定キー、アクセシビリティセマンティクス、記述するユニットテスト。references/change-detection-model.md、references/di-and-services.md、references/state-http-interceptors.md、references/official-docs.md を参照します。
ゲート5: 実装
最小限の完全な変更を適用します:
- コンポーネントは薄く保つ: シグナルまたはオブザーバブルをバインドし、イベントをサービスに委譲して処理し、セマンティックテンプレートでレンダリングします。
- 厳格なTypeScriptを維持し、
anyは使用しません。境界でunknown値を絞り込みます。 - 最新コードでは
inject()、レガシーコードではコンストラクターインジェクションを使用し、サービスはprovidedIn: 'root'で提供します。 asyncパイプまたはtoSignal()を優先し、購読が避けられない場合はtakeUntilDestroyed()またはDestroyRefを使用します。switchMap、mergeMap、concatMap、exhaustMapを使用してネストされた購読をフラット化します。- イミュータブルな更新、明示的な
trackまたはtrackByを使用し、テンプレートメソッドは重くしません。 - Angularのサニタイゼーションを維持し、バイパスを検討する前にHTML、URL、スタイル値を検証します。
- プロジェクトのエラーハンドリングとDTOマッピングを再利用し、明らかな必要性なしに新しいライブラリを追加しません。
ゲート6: Jestユニットテストの記述
references/testing-jest.md に従います:
- Jest、
jest-preset-angular、TestBed、プロジェクトの既存のjest.configとsetup-jest.tsを使用し、それらがない場合のみ作成し、ランナーの選択を確認した後に作成します。 - 変更された動作の成功、検証、エラーパスを分離されたユニットテストでカバーします。
- TestBed
importsを使用してスタンドアロンコンポーネント、モックされたHttpClientまたはモックされた協力者を持つサービス、パイプを直接、シグナルを明示的なアサーションでテストします。 - v20.2+のゾーンレスアプリケーションの場合、TestBedプロバイダーに
provideZonelessChangeDetection()を追加し、v21+ではデフォルトに依存します。 jest.mockをモジュールに、jest.spyOnを焦点を絞った協力者に使用し、オブザーバブルの結果をアサートし、境界の相互作用を検証します。- Jestのしきい値を通じて少なくとも80%のカバレッジを適用し、ゲートを下げて合格させることは決してありません。
- KarmaまたはVitestがすでに設定されている場合、Jestに切り替える前に確認し、必要な正確な設定を提示します。
ゲート7: 検証
プロジェクト自身のコマンドを実行し、結果とともに記録します:
npx jest --coverage
プロジェクトが npm test -- --coverage などの設定済みスクリプトを公開している場合、代わりにそのコマンドを実行し、正確な呼び出しを記録します。カバレッジサマリーを開き、変更されたコードに対して少なくとも80%が達成されていることを確認します。カバレッジが80%未満の場合、ゲートを下げる代わりにユニットテストを追加または調整します。利用可能な場合、設定済みの型チェックまたはビルドを実行し、その終了ステータスを記録します。
ゲート8: 成果物の作成
references/report-template.md を使用して ANGULAR-EXPERT-IMPL.md を作成します。IDを安定させます: 変更には CHG-001、テストには T-001、設定追加には CFG-NNN、検証証拠には EV-NNN。コンテンツのないセクションでは「変更なし。」を使用し、セクションを空白のままにしないでください。
ゲート9: 成果物の検証
python3 scripts/validate_report.py ANGULAR-EXPERT-IMPL.md
--strict または --min-coverage N は、ユーザーが明示的にポリシーを変更した場合のみ使用します。バリデーターを実行できない場合、references/validation-checklist.md を手動で適用し、バリデーターが利用できなかったことを記載します。
ゲート10: 引き継ぎ
正確に3つの見出しで回答します。順序は ## 簡潔な分析、## クリーンで完全なコード、## 設定 です。設定セクションの後に、実際に実行された検証コマンド、測定されたカバレッジ、残存リスクをリストします。承認の判断は追加しないでください。
成果物コントラクト
必須マーカー。レポートテンプレートとバイトレベルで同じ形状:
<!-- angular-expert:artifact type=implementation version=1 -->
<!-- angular-expert:section id=analysis -->
<!-- angular-expert:section id=stack -->
<!-- angular-expert:section id=design -->
<!-- angular-expert:section id=implementation -->
<!-- angular-expert:section id=tests -->
<!-- angular-expert:section id=validation -->
<!-- angular-expert:section id=configurations -->
<!-- angular-expert:section id=evidence -->
<!-- angular-expert:section id=assumptions -->
<!-- angular-expert:section id=traceability -->
<!-- angular-expert:stack angular=20.3.0 typescript=5.8.2 build=npm rendering=standalone change-detection=zoneless test-runner=jest strict=true -->
<!-- angular-expert:coverage value=88 gate=80 tool=jest -->
<!-- angular-expert:change id=CHG-001 status=implemented -->
<!-- angular-expert:test id=T-001 framework=jest testbed=true context=unit -->
<!-- angular-expert:evidence id=EV-001 status=passed -->
<!-- angular-expert:config id=CFG-001 file=angular.json -->
安定したIDファミリー: 変更には CHG-NNN、テストには T-NNN、設定追加には CFG-NNN、検証証拠には EV-NNN。すべての変更は、トレーサビリティテーブル内の少なくとも1つのテスト行と1つの証拠行にリンクする必要があります。
バージョンマトリックス
| 検出されたAngular | レンダリングベースライン | 制御フローと状態 | 変更検出ガイダンス |
|---|---|---|---|
| v2-v16 (非サポート) | NgModule時代のパターン | *ngIf、trackBy 付き *ngFor、RxJS を使用; 組み込み制御フローは利用不可 | ゾーンベース; 依頼がない限りアップグレードを提案しない |
| v17-v19 (非サポート) | スタンドアロン利用可能、v19でデフォルト | v17で導入されv18で安定した制御フロー; シグナル利用可能; プロジェクトがすでに使用している場合のみ使用 | ゾーンベース; v18-v19の実験的ゾーンレスは範囲外 |
| v20.0-v20.1 | スタンドアロンデフォルト | シグナルと制御フローは安定 | ゾーンレスは実験的 |
| v20.2+ | スタンドアロンデフォルト | シグナルと制御フローは安定 | ゾーンレス安定 (provideZonelessChangeDetection() 経由) |
| v21+ | スタンドアロンデフォルト | シグナル、制御フロー、toSignal() ベースライン | ゾーンレスがデフォルト; provideZoneChangeDetection() を使用しない |
| v22+ | スタンドアロンとOnPushが暗黙的 | 明示的に standalone: true を設定しない | 明示的に changeDetection: OnPush を設定しない |
検出器の出力が信頼できる情報源です。Angular v2-v19はサポートされていません。移行を提案する代わりに、その制限を記録します。マトリックスと検出バージョンの公式ガイドでサポートを確認せずに、バージョンゲート付きAPIを導入しないでください。
証拠ルール
- テスト、型チェック、ビルド、カバレッジについて、正確なコマンド、終了ステータス、測定値を記録します。
- 決定を説明するときは、
path:lineで変更されたファイルを参照します。 - ID、マーカー、重大度、フレームワーク名、ステータス値は英語のままにします。
- トークン、資格情報、個人データは
[REDACTED]として編集します。 - 設定レポートはキーのみに制限し、生の設定値を成果物に貼り付けないでください。
- CI結果を主張しないでください。
[翻訳のため省略]