frontend-engineering

フロントエンドエンジニアリング

適切なレベルの厳密さで、フロントエンドソフトウェアの計画、設計、構築、保守を支援します。このスキルは、ウェブフロントエンドに適用し、関連する場合はモバイルまたはデスクトップクライアントにも適用します。フレームワークに依存しません。特定のフレームワーク、デザインシステム、状態管理ライブラリ、ビルドツールを前提とせず、実際のスタックに合わせて例を調整してください。

このスキルが担当するのは、フロントエンドの技術的な品質です。ドキュメントのレベル、成果物の整理、要件の発見など、プロセス全般に関する質問では、利用可能であれば solution-design スキルに委ね、ここではフロントエンドに関連する影響のみを扱ってください。

有効化の条件

ユーザーが次のいずれかを行う場合、このスキルを読み込んでください。

• フロントエンドプロジェクトをゼロから開始する。
• UI、ユーザーフロー、コンポーネントシステム、またはフロントエンドアーキテクチャを計画する。
• 複数の画面やコンポーネントにまたがる機能を実装する。
• フロントエンドの保守性、UX、アクセシビリティ、パフォーマンス、またはテストをレビューする。
• フロントエンドの設計ドキュメントを作成または更新する。
• フロントエンドの動作をバックエンド API または製品要件に合わせる。

小規模で単独の変更の場合は読み込まないでください。関連するコンテキストを確認し、実装し、適切なチェックを実行して、残るリスクをまとめてください。完全なワークフローは実施しません。

必須ルール

1. コードを変更する前に理解する。 既存プロジェクトでは、変更を提案する前にリポジトリ、パッケージマニフェスト、ルーティング、コンポーネント、スタイル、テスト、既存ドキュメントを確認してください。何もない状態から始めると決めつけてはいけません。
2. 規模とリスクに応じて調整する。 画面数だけでなく、複雑さ、ユーザーへの影響、アクセシビリティのニーズ、セキュリティとプライバシー、パフォーマンス要件、統合、チーム規模、不確実性に基づいて、軽量、標準、厳密のいずれかを選んでください。
3. ドキュメントを肥大化させない。 重要な決定を記録し、分離によってコラボレーション、レビュー、追跡可能性、保守性が向上する場合にのみ、別ファイルを作成してください。
4. 要件と実装を分ける。 実現に用いる技術的なアプローチとは別に、ユーザーが必要としていることを示してください。
5. 前提を明示する。 確認済みの要件、前提、未解決の質問、推奨事項を区別してください。製品の動作、役割、ブランディング、API を黙って作り出してはいけません。
6. 理想的なケースだけでなく、各状態を設計する。 関連する場合は、読み込み中、空、エラー、成功、無効、権限拒否、オフライン、部分的なデータの各状態を考慮してください。
7. アクセシビリティとレスポンシブな動作は、最初から品質要件です。 最後の仕上げの段階まで先延ばしにしないでください。
8. ドキュメントとコードの整合性を保つ。 影響を受けるドキュメントのみを更新し、信頼できる情報源は一つにして、重複させる代わりにリンクしてください。
9. 段階的に検証する。 大規模で推測に基づく設計フェーズよりも、小さくテスト可能なユーザー向け機能の単位を優先してください。
10. プロジェクトの慣習に従う。 理由と明示的なトレードオフがない限り、新しいライブラリやアーキテクチャパターンを導入しないでください。
11. クライアントは信頼境界ではありません。 クライアントコードにシークレットや特権的な認可ロジックを置いてはいけません。クライアント側の検証は使いやすさを向上させますが、サーバー側の検証に取って代わるものではありません。

判断のゲート

ドキュメントのレベル

観察された指標	レベル	成果物
スコープが小さく、リスクが低く、ビューやフローが少ない。開発者が1人、または迅速なプロトタイプである	軽量	docs/frontend/design.md を1つ作成します（templates/frontend-design.md を参照）。必要に応じて README も作成し、要件、フロー、アーキテクチャ、UI ルール、API の前提、アクセシビリティ、テストをまとめます
複数の機能、共有コンポーネント、重要なクライアント状態、連携、またはチームがある	標準	簡潔な設計概要を作成します。個別の担当や頻繁な更新が必要な場合に限り、焦点を絞ったドキュメント（ui-flows.md、design-system.md、frontend-architecture.md、frontend-testing.md、ADR）を追加します
影響の大きい、または規制対象のユーザージャーニー、機密データ、複雑な権限、厳格なアクセシビリティやパフォーマンスの目標、多数のチーム、大規模なアプリケーションがある	厳格	要件のトレーサビリティ、デザインシステムのドキュメント、アーキテクチャ決定記録、テスト戦略、パフォーマンス予算、必要に応じてセキュリティ／プライバシーのレビューを作成します

プロジェクトの規模が小さくても、リスクが高い場合があります。リスクに応じて厳格さを高めてください。スコープが変わったときは、レベルを再評価してください。再評価のきっかけと統合基準については、references/workflow.md を参照してください。

引き継ぎ

質問	担当
横断的なプロセス：要件の発見、ドキュメントのレベル、成果物の整理	利用可能であれば solution-design スキル。そうでなければ、上記の軽量なプロセスを維持します
フロントエンドの実装：コンポーネントの境界、状態、UX、アクセシビリティ、テスト、パフォーマンス	このスキル
API／データベースの契約の詳細	利用可能であれば api-design／database-design スキル

実行手順

1. コンテキストを把握します。 新規プロジェクトの場合：プロダクトの目標、ユーザー、主なタスク、デバイス／ブラウザー、ブランド上の制約、アクセシビリティへの期待、データの機密性、API 依存関係、制約を明確にします。設計に実質的な影響を与える場合に限り、要点を絞って質問し、それ以外は前提として記録します。既存プロジェクトの場合：まずフレームワークのバージョン、ルート、スタイル設定の方針、コンポーネントの規約、状態管理／データ取得、API 契約、テスト、現在のデザインシステムを確認します。
2. 上記の判断基準からドキュメントの詳細度を選び、その理由を簡潔に述べます。
3. ユーザー要件とインターフェース要件を定義します。 ユーザーの種類と目標、主要なユーザージャーニー、ナビゲーション、画面の役割、レスポンシブ動作、受け入れ基準を定めます。ロールによってアクセス権が異なる場合は、許可、非表示、無効化、拒否の対象となる操作と画面を記録します。表示可否は UX 上のルールであり、セキュリティ境界ではありません。曖昧さを減らせる場合にのみワイヤーフレーム／図を作成します。ビジュアルデザインが求められている場合は、形式（画像、編集可能なモックアップ、実装）を選ぶ前に、出力形式を明確にします。
4. フロントエンドアーキテクチャを設計します。 ルート、コンポーネントの責務（共通と機能固有）、状態の所有者とデータフロー、API クライアントの動作、フォームとバリデーション、権限を考慮した表示、必要に応じて設定、ローカライズ、エラーバウンダリーを定めます。現在の要件を満たす最もシンプルなアーキテクチャを優先し、推測に基づくフレームワーク、不要なグローバル状態、時期尚早な抽象化は避けます。references/frontend-architecture.md を参照して検討します。
5. UX とビジュアルの動作を定義します。 情報の階層、インタラクションパターン、デザインシステムが妥当な場合のデザイントークンとコンポーネントのバリエーション、フォーム UX、すべてのインターフェース状態、レスポンシブレイアウト、アクセシビリティのベースラインを定めます。競合するデザインシステムを新たに作らず、既存のデザインシステムを拡張します。ブランドカラーやタイポグラフィを独自に考案せず、明示的なプレースホルダーを置くか、質問します。references/ui-ux-accessibility.md を参照して検討します。
6. API とデータ契約を整合させます。 バックエンドの契約に照らして、エンドポイント、メソッド、スキーマ、ページネーション、バリデーションエラー、認証に関する想定を確認し、既存の OpenAPI または生成済みクライアントを再利用します。契約が不明な場合は前提として明示し、連携済みだと決して主張しません。詳細は references/frontend-architecture.md を参照してください。
7. 品質計画を最初から立てます。 プロジェクトに見合ったチェックを選びます。単体／コンポーネント／統合／E2E テスト、アクセシビリティ（自動チェックに加えてキーボード操作／手動チェック）、サポート対象に応じたレスポンシブ／クロスブラウザ確認、必要に応じたパフォーマンス（バンドル、レンダリング、Core Web Vitals）、正当な理由がある場合に限るビジュアルリグレッションを検討します。受け入れ基準は、観測可能なテストまたは記録された手動確認方法に結び付けます。references/quality-testing.md を参照して計画します。
8. 実装を垂直スライスで計画します。 ユーザーから見て完結した機能を提供する小さな単位で進めます。各単位について、画面／コンポーネント、API 依存関係、状態、受け入れ基準、テストを特定します。リスクの高い不明点は早期に解消します。有用な最初の単位に着手する前に、すべての画面の仕様を完成させる必要はありません。
9. 実装、検証、保守を行います。 大規模な作業では、編集前に予定する範囲を要約します。リポジトリの規約に従って関連するチェックを実行し、実行しなかったチェックとその理由を報告します。重要な決定、インタラクション、契約、アーキテクチャが変更された場合はドキュメントを更新します。レビューでは、正確性、アクセシビリティ、セキュリティ／プライバシー、レスポンシブ動作、保守性、パフォーマンス、回帰リスクを確認し、検証済みの問題と潜在的な懸念を区別します。

ドキュメント作成ルール

• まずは役立つ最小限のドキュメントから始め、別の成果物が必要な場合は、その理由を簡潔に説明します。
• 軽量な構成：templates/frontend-design.md をベースに、単一の docs/frontend/design.md を作成します。
• 標準／厳密な構成：分割によって利用や保守がしやすくなる場合にのみ、セクションを分割します。API 定義、製品要件、バックエンド／データベース仕様を完全な形で重複させず、正規のドキュメントへのリンクを記載し、フロントエンドに関係する影響のみを記録します。
• 省略理由の説明が必要な場合にのみ、セクションに Not applicable と記載します。それ以外の場合は省略します。
• ステータスが重要な決定には、Confirmed、Proposed、Open question のラベルを付けます。

リファレンスガイド

現在のタスクに関連するリファレンスのみを参照します。

• references/workflow.md：プロジェクトのライフサイクル、再評価のきっかけ、統合の基準。
• references/frontend-architecture.md：アーキテクチャ、コンポーネントの境界、状態、ルーティング、API 連携。
• references/ui-ux-accessibility.md：ユーザーフロー、インターフェースの状態、レスポンシブデザイン、アクセシビリティ、デザインシステム。
• references/quality-testing.md：テスト、パフォーマンス、セキュリティ／プライバシー、リリース時の確認。
• references/document-templates.md：軽量なドキュメントと特化型ドキュメントの推奨セクション。
• templates/frontend-design.md：小規模プロジェクト向けの簡潔なオールインワン設計ドキュメントのテンプレート。

成果物の要件

設計または実装タスクの最後に、以下を報告します。

1. 作成または変更したファイル（成果物を統合した場合は、各責務がどこに記載されているかも含めます）。
2. 選択したドキュメントのレベルと、その理由。
3. 最も重要な前提。
4. 未解決の質問、ブロッカー、保留中の影響の大きい決定。
5. 実施した確認と、未実施の確認およびその理由。
6. 推奨する次の作業単位。

完了チェックリスト

設計または実装タスクを完了とする前に、該当する項目を確認します。

• ユーザーの目標とスコープを理解している。
• 主要なフローと受け入れ基準が明確である。
• コンポーネントと状態の責務に一貫性がある。
• API の依存関係と不明点が明示されている。
• 該当する場合、読み込み中、空、エラー、成功、権限に関する状態を検討している。
• レスポンシブ動作とアクセシビリティに対応している。
• セキュリティ上重要な動作をクライアントだけに委ねていない。
• 適切なテスト／確認を実施するか、残る課題を報告している。
• ドキュメントが簡潔かつ最新で、不必要に重複していない。