Angular 開発者

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 バージョンがサポートしている場合にのみ Signal Forms を優先してください。詳細はこちらを参照してください。

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.md を参照

フォーム

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

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

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

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

• テンプレート駆動フォーム: 単純なフォームに使用します。template-driven-forms.md を参照

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

依存性注入

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

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

Angular Aria

アコーディオン、リストボックス、コンボボックス、メニュー、タブ、ツールバー、ツリー、グリッドのいずれかのパターンでアクセシブルなカスタムコンポーネントを構築する場合は、以下のリファレンスを参照してください。

• Angular Aria コンポーネント: ヘッドレスでアクセシブルなコンポーネント（アコーディオン、リストボックス、コンボボックス、メニュー、タブ、ツールバー、ツリー、グリッド）の構築と ARIA 属性のスタイリング。angular-aria.md を参照

ルーティング

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

• ルートの定義: URL パス、静的 vs 動的セグメント、ワイルドカード、リダイレクト。define-routes.md を参照
• ルート読み込み戦略: 即時読み込み vs 遅延読み込み、コンテキスト認識読み込み。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 の使用: Angular プロジェクトへの Tailwind CSS の統合。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 バージョンが Signal Forms をサポートしている場合に、古いフォーム 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 アプローチのコンテキストのための一般的なフロントエンドパターン