dev-goraebap/krill

Angular開発者ガイドライン

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

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

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

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

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

1. ユーザーが指定しない限り、Angularの最新安定バージョンを使用してください。
2. 新しいプロジェクトではフォーム管理にシグナルフォーム（Signals Forms）を使用してください（Angular v21以降で利用可能）詳細はこちら。

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): シグナルベースの入力、変換、モデル入力。inputs.md を参照
• 出力 (Outputs): シグナルベースの出力とカスタムイベントのベストプラクティス。outputs.md を参照
• ホスト要素 (Host Elements): ホストバインディングと属性インジェクション。host-elements.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 を参照

フォーム

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

• アプリケーションがv21以降を使用しており、これが新しいフォームである場合、シグナルフォームを優先してください。

• 古いアプリケーション、または既存のフォームを扱う場合は、アプリケーションの現在のフォーム戦略に一致する適切なフォームタイプを使用してください。

• シグナルフォーム: フォーム状態管理にシグナルを使用。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 を参照
• ルート遷移アニメーション: 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サーバー: 利用可能なツール、設定、実験的機能。mcp.md を参照
• 環境設定: ビルド時および実行時設定の戦略。environment-configuration.md を参照