angular-developer

Angular開発者ガイドライン

アクティブ化のタイミング

• Angularプロジェクトまたはコードベースで作業している場合
• 新しいAngularプロジェクト、アプリケーション、またはライブラリを作成またはスキャフォールディングしている場合
• コンポーネント、サービス、ディレクティブ、パイプ、ガード、またはリゾルバを生成している場合
• Angular Signals、linkedSignal、またはresourceを使用してリアクティビティを実装している場合
• Angularフォーム（シグナルフォーム、リアクティブフォーム、テンプレート駆動フォーム）を扱っている場合
• 依存性注入、ルーティング、遅延ロード、またはルートガードを設定している場合
• アクセシビリティ（ARIA）、アニメーション、またはコンポーネントのスタイリングを追加している場合
• Angular固有のテスト（単体テスト、コンポーネントハーネス、E2E）を作成またはデバッグしている場合
• Angular CLIツールまたはAngular MCPサーバーを設定している場合

1. ガイダンスを提供する前に、常にプロジェクトのAngularバージョンを分析してください。ベストプラクティスや利用可能な機能はバージョンによって大きく異なる可能性があります。Angular CLIで新しいプロジェクトを作成する場合、ユーザーから指定がない限りバージョンを指定しないでください。

2. コードを生成する際は、保守性とパフォーマンスのためにAngularのスタイルガイドとベストプラクティスに従ってください。コンポーネント、サービス、ディレクティブ、パイプ、ルートをスキャフォールディングするには、Angular CLIを使用して一貫性を確保します。

3. コードの生成が完了したら、ng buildを実行してビルドエラーがないことを確認します。エラーがある場合は、エラーメッセージを分析して修正してから先に進みます。生成されたコードが正しく機能することを確認するために、この手順は重要です。スキップしないでください。

新しいプロジェクトの作成

ユーザーからガイドラインが提供されない場合、新しいAngularプロジェクトを作成する際は以下のデフォルトを使用します。

1. ユーザーが別途指定しない限り、Angularの最新安定バージョンを使用します。
2. ターゲットのAngularバージョンがシグナルフォームをサポートしている場合に限り、新しいプロジェクトではシグナルフォームを優先します。詳細については、シグナルフォームを参照してください。

ng newの実行ルール: 新しいAngularプロジェクトの作成を求められた場合、以下の厳格な手順に従って正しい実行コマンドを決定する必要があります。

ステップ1: 明示的なユーザーバージョンの確認

• もしユーザーが特定のバージョン（例：Angular 15）を要求した場合、ローカルインストールをバイパスし、厳密にnpxを使用します。
• コマンド: npx @angular/cli@<要求されたバージョン> new <プロジェクト名>

ステップ2: 既存のAngularインストールの確認

• もし特定のバージョンが要求されていない場合、ターミナルでng versionを実行し、Angular CLIがシステムに既にインストールされているか確認します。
• もしコマンドが成功し、インストールされたバージョンが返された場合、ローカル/グローバルインストールを直接使用します。
• コマンド: ng new <プロジェクト名>

ステップ3: 最新バージョンへのフォールバック

• もし特定のバージョンが要求されておらず、かつng versionコマンドが失敗した場合（Angularインストールが存在しないことを示す）、npxを使用して最新バージョンを取得します。
• コマンド: npx @angular/cli@latest new <プロジェクト名>

コンポーネント

Angularコンポーネントを扱う際は、タスクに応じて以下のリファレンスを参照してください。

• 基礎: 構造、メタデータ、コアコンセプト、テンプレート制御フロー（@if、@for、@switch）。components.mdを参照してください。
• 入力: シグナルベースの入力、変換、モデル入力。inputs.mdを参照してください。
• 出力: シグナルベースの出力とカスタムイベントのベストプラクティス。outputs.mdを参照してください。
• ホスト要素: ホストバインディングと属性注入。host-elements.mdを参照してください。

上記のリファレンスにない詳細なドキュメントが必要な場合は、https://angular.dev/guide/componentsのドキュメントを参照してください。

リアクティビティとデータ管理

状態とデータのリアクティビティを管理する際は、Angular Signalsを使用し、以下のリファレンスを参照してください。

• シグナル概要: コアシグナルコンセプト（signal、computed）、リアクティブコンテキスト、untracked。signals-overview.mdを参照してください。
• 依存状態（linkedSignal）: ソースシグナルにリンクされた書き込み可能な状態の作成。linked-signal.mdを参照してください。
• 非同期リアクティビティ（resource）: 非同期データをシグナル状態に直接取得。resource.mdを参照してください。
• 副作用（effect）: ログ記録、サードパーティ製DOM操作（afterRenderEffect）、effectsを使用すべきでない場合。effects.mdを参照してください。

フォーム

新しいアプリのほとんどの場合、シグナルフォームを優先します。フォームを決定する際は、プロジェクトを分析し、以下のガイドラインを考慮してください。

• アプリケーションバージョンがシグナルフォームをサポートしており、これが新しいフォームである場合、シグナルフォームを優先します。

• 古いアプリケーションまたは既存のフォームの場合、アプリケーションの現在のフォーム戦略に合わせてください。

• シグナルフォーム: フォーム状態管理にシグナルを使用します。signal-forms.mdを参照してください。

• テンプレート駆動フォーム: シンプルなフォームに使用します。template-driven-forms.mdを参照してください。

• リアクティブフォーム: 複雑なフォームに使用します。reactive-forms.mdを参照してください。

依存性注入

Angularで依存性注入を実装する際は、以下のガイドラインに従ってください。

• 基礎: 依存性注入、サービス、inject()関数の概要。di-fundamentals.mdを参照してください。
• サービスの作成と使用: サービスの作成、providedIn: 'root'オプション、コンポーネントや他のサービスへの注入。creating-services.mdを参照してください。
• 依存プロバイダーの定義: 自動プロビジョニングと手動プロビジョニング、InjectionToken、useClass、useValue、useFactory、およびスコープ。defining-providers.mdを参照してください。
• 注入コンテキスト: inject()が許可される場所、runInInjectionContext、assertInInjectionContext。injection-context.mdを参照してください。
• 階層インジェクター: EnvironmentInjectorとElementInjector、解決ルール、修飾子（optional、skipSelf）、providersとviewProviders。hierarchical-injectors.mdを参照してください。

Angular ARIA

以下のパターンのいずれかに対してアクセシブルなカスタムコンポーネントを構築する場合：Accordion、Listbox、Combobox、Menu、Tabs、Toolbar、Tree、Grid、以下のリファレンスを参照してください。

• Angular ARIA コンポーネント: ヘッドレスでアクセシブルなコンポーネント（Accordion、Listbox、Combobox、Menu、Tabs、Toolbar、Tree、Grid）の構築とARIA属性のスタイリング。angular-aria.mdを参照してください。

ルーティング

Angularでナビゲーションを実装する際は、以下のリファレンスを参照してください。

• ルートの定義: URLパス、静的セグメントと動的セグメント、ワイルドカード、リダイレクト。define-routes.mdを参照してください。
• ルート読み込み戦略: イーガーローディングと遅延ローディング、コンテキストアウェアローディング。loading-strategies.mdを参照してください。
• アウトレットを使用したルートの表示: <router-outlet>、ネストされたアウトレット、名前付きアウトレットの使用。show-routes-with-outlets.mdを参照してください。
• ルートへのナビゲーション: RouterLinkを使用した宣言的ナビゲーションとRouterを使用したプログラムによるナビゲーション。navigate-to-routes.mdを参照してください。
• ガードによるルートアクセスの制御: セキュリティのためのCanActivate、CanMatch、およびその他のガードの実装。route-guards.mdを参照してください。
• データリゾルバ: ResolveFnを使用したルートアクティベーション前のデータプリフェッチ。data-resolvers.mdを参照してください。
• ルーターライフサイクルとイベント: ナビゲーションイベントの時系列順とデバッグ。router-lifecycle.mdを参照してください。
• レンダリング戦略: CSR、SSG（プリレンダリング）、SSR（ハイドレーション付き）。rendering-strategies.mdを参照してください。
• ルート遷移アニメーション: View Transitions APIの有効化とカスタマイズ。route-animations.mdを参照してください。

より深いドキュメントや詳細なコンテキストが必要な場合は、公式Angularルーティングガイドを参照してください。

スタイリングとアニメーション

Angularでスタイリングとアニメーションを実装する際は、以下のリファレンスを参照してください。

• AngularでTailwind CSSを使用する: Tailwind CSSをAngularプロジェクトに統合する。tailwind-css.mdを参照してください。
• Angularアニメーション: ネイティブCSS（推奨）または動的エフェクト用のレガシーDSLの使用。angular-animations.mdを参照してください。
• コンポーネントのスタイリング: コンポーネントスタイルとカプセル化のベストプラクティス。component-styling.mdを参照してください。

テスト

テストを作成または更新する際は、タスクに応じて以下のリファレンスを参照してください。

• 基礎: 単体テスト、非同期パターン、TestBedのベストプラクティス。testing-fundamentals.mdを参照してください。
• コンポーネントハーネス: 堅牢なコンポーネントインタラクションのための標準パターン。component-harnesses.mdを参照してください。
• ルーターテスト: 信頼性の高いナビゲーションテストのためのRouterTestingHarnessの使用。router-testing.mdを参照してください。
• エンドツーエンド（E2E）テスト: CypressまたはPlaywrightを使用したE2Eテストのベストプラクティス。e2e-testing.mdを参照してください。

ツール

Angularツールを扱う際は、以下のリファレンスを参照してください。

• Angular CLI: アプリケーションの作成、コードの生成（コンポーネント、ルート、サービス）、サーブ、ビルド。cli.mdを参照してください。
• Angular MCPサーバー: 利用可能なツール、設定、実験的機能。mcp.mdを参照してください。

アンチパターン

• シグナルフォームフィールドの初期値としてnullやundefinedを使用する — 代わりに''、0、[]を使用します
• フィールドを呼び出さずにフォームフィールドの状態フラグにアクセスする: form.field.valid() — 代わりにform.field().valid()を使用します
• ターゲットのAngularバージョンがシグナルフォームをサポートしている場合でも、古いフォームAPIで新しいフォームを開始する
• [formField]入力にmin、max、value、disabled、またはreadonly HTML属性を設定する — 代わりにスキーマルールとして定義します
• 注入コンテキスト外でinject()を呼び出す — 必要に応じてrunInInjectionContextを使用します
• computed()を使用すべき派生状態にeffect()を使用する
• ネストされた@forループ内で$parent.$indexを参照する — Angularは$parentをサポートしていません。代わりにlet outerIdx = $indexを使用します

関連スキル

• tdd-workflow — Angularコンポーネントとサービスに適用可能なテスト駆動開発ワークフロー
• security-review — Angular固有の懸念事項を含むWebアプリケーション向けセキュリティチェックリスト
• frontend-patterns — React/Next.jsアプローチのコンテキストのための一般的なフロントエンドパターン