angular-developer

Angular 開発者向けガイドライン

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

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

3. コードの生成が完了したら、ng build を実行してビルドエラーがないことを確認してください。エラーがある場合は、エラーメッセージを分析し、次に進む前に修正してください。生成したコードが正しく動作することを確かめるうえで重要な手順のため、省略しないでください。

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

ユーザーからガイドラインが示されていない場合、新しい Angular プロジェクトを作成する際は、以下のデフォルトルールに従ってください。

1. ユーザーから別の指定がない限り、最新の安定版 Angular を使用してください。
2. 新しいプロジェクトのフォーム管理には Signal Forms を使用してください（Angular v22 以降で安定版です）詳細はこちら。

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

ステップ 1：ユーザーがバージョンを明示しているか確認します。

• IF ユーザーが特定のバージョン（例：Angular 15）を指定している場合は、ローカルのインストールを使わず、必ず npx を使用してください。
• コマンド： npx @angular/cli@<requested_version> new <project-name>

ステップ 2：Angular がすでにインストールされているか確認します。

• IF 特定のバージョンが指定されていない場合は、ターミナルで ng version を実行し、Angular CLI がシステムにすでにインストールされているか確認してください。
• IF コマンドが成功し、インストール済みのバージョンが返された場合は、ローカルまたはグローバルのインストールをそのまま使用してください。
• コマンド： ng new <project-name>

ステップ 3：最新バージョンにフォールバックします。

• IF 特定のバージョンが指定されておらず、かつ ng version コマンドが失敗した場合（Angular がインストールされていないことを示します）、npx を使用して最新バージョンを取得する必要があります。
• コマンド： npx @angular/cli@latest new <project-name>

コンポーネント

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

• 基礎：構造、メタデータ、基本概念、自己終了タグ、テンプレートの制御フロー（@if、@for、@switch）。components.md をお読みください。
• 入力：シグナルベースの入力、変換、モデル入力。inputs.md をお読みください。
• 出力：シグナルベースの出力とカスタムイベントのベストプラクティス。outputs.md をお読みください。
• ホスト要素：ホストバインディングと属性の注入。host-elements.md をお読みください。
• 命名規則：ファイル、コンポーネント、サービス、ディレクティブ、パイプ、モデルにおける、Angular v20 以降の最新の命名スタイル（「役割より意図」）。naming-conventions.md をお読みください。
• クエリとコンテンツ投影：シグナルベースのビューおよびコンテンツクエリ（viewChild、viewChildren、contentChild、contentChildren）、ならびに <ng-content> スロットとフォールバックコンテンツを使ったコンテンツ投影。queries-and-projection.md をお読みください。
• 遅延可能ビュー：@defer による遅延読み込み、コード分割、トリガー、事前読み込み、読み込み状態、SSR、レイアウトの安定性。deferrable-views.md をお読みください。

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

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

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

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

HTTP 通信

バックエンドサービスと通信する場合は、Angular の HTTP API を使用し、以下のリファレンスを参照してください。

• HTTP クライアントとリソース：provideHttpClient、HttpClient、インターセプター、httpResource。http-client.md を参照してください。

フォーム

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

• アプリケーションが v22 以降を使用していて、新しいフォームを作成する場合は、Signal Forms を優先してください。

• 古いアプリケーションの場合、または既存のフォームを扱う場合は、アプリケーションの現在のフォーム戦略に合ったフォームの種類を使用してください。

• Signal Forms：フォームの状態管理にシグナルを使用します。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 を参照してください。

パイプ

テンプレート内で値をフォーマットする場合、カスタムパイプを作成する場合、または TypeScript でパイプに似たロジックを再利用する場合は、以下のリファレンスを参照してください。テンプレートではパイプを優先し、テンプレート外では transform() を呼び出すだけのためにパイプクラスを注入することは避けてください。

• パイプ：組み込みパイプのインポート、カスタムパイプの命名と実装、純粋パイプと不純粋パイプ、スタンドアロンのフォーマット関数または抽出したプレーン関数を使用した TypeScript での再利用パターン。pipes.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を参照してください。
• サーバーレンダリングとハイブリッドレンダリング：SSR 設定済みアプリにおける、サーバールート、事前レンダリング、ハイドレーション、サーバー互換コード、リクエストデータの実装について説明します。server-side-rendering.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を参照してください。

テスト

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

• 基礎：ユニットテスト（Vitest）、非同期パターン、TestBed のベストプラクティスについて説明します。testing-fundamentals.mdを参照してください。
• コンポーネントハーネス：堅牢なコンポーネント操作の標準的なパターンについて説明します。component-harnesses.mdを参照してください。
• ルーターのテスト：信頼性の高いナビゲーションテストに RouterTestingHarness を使う方法について説明します。router-testing.mdを参照してください。
• エンドツーエンド（E2E）テスト：E2E テストの設定と実行について説明します。e2e-testing.mdを参照してください。

ツール

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

• Angular CLI：アプリケーションの作成、コード（コンポーネント、ルート、サービス）の生成、サーバーの起動、ビルドについて説明します。cli.mdを参照してください。
• コードのモダナイゼーション：マイグレーションを使って、最新の標準に合わせてコードを自動的にリファクタリングする方法について説明します。migrations.mdを参照してください。
• Angular MCP Server：利用可能なツール、設定、実験的な機能について説明します。mcp.mdを参照してください。
• 環境設定：ビルド時と実行時の設定戦略について説明します。environment-configuration.mdを参照してください。