Frontend Conventions
Next.js 16 + React 19 + TanStack Query v5 + FSDアーキテクチャにおいて 「良いコードであり、一貫性のあるコード」 を生成するための規約。
このスキルを使用するタイミング
- 新しいエンティティ、フィーチャー、ウィジェットを作成するとき
- CRUDフォームやデータテーブルを実装するとき
- 既存コードをリファクタリングするとき
- プロジェクトが規約を遵守しているか検証するとき
- APIレイヤー、状態管理、エラーハンドリングパターンを適用するとき
テクノロジースタック
- Next.js 16.1.6 (App Router) + React 19.2.3 + TypeScript 5.9.2
- @tanstack/react-query ^5 + @tanstack/react-table ^8.21.3
- react-hook-form ^7.71.2 + zod ^3.25.76
- nuqs ^2.8.9 (URL状態管理)
- Tailwind CSS ^4 + shadcn/ui (radix-nova) + sonner ^2.0.7 (トースト通知)
- Turborepo ^2.8.12 + pnpm 9.0+ (内部パッケージ:
@workspace/ui、@workspace/api)
ルールカテゴリ
11カテゴリ、67ルール。作業内容に応じて適切なファイルを参照:
| 領域 | ファイル | いつ参照するか |
|---|---|---|
| アーキテクチャ | rules/architecture.md | FSDレイヤー、インポート方向、エンティティスライス、バレルエクスポート |
| Next.jsパターン | rules/nextjs-patterns.md | Page thin shell、Providers、'use client'、特殊ファイル |
| コード品質 | rules/code-quality.md | Dynamic import、条件付きレンダリング、早期リターン、forwardRef |
| クエリ | rules/queries.md | queryOptionsファクトリ、クエリキー、staleTime、プリフェッチ、useQueries |
| ミューテーション | rules/mutations.md | invalidate、useApiMutation、楽観的更新 |
| APIレイヤー | rules/api-layer.md | APIオブジェクト、レスポンス型、SSRプリフェッチ |
| フォーム | rules/forms.md | zodスキーマ、useForm、FormDialog、編集パターン |
| テーブル | rules/tables.md | DataTable、columns、サーバーサイドページネーション |
| 状態管理 | rules/state-management.md | nuqs、useState、グローバル状態の禁止 |
| エラーハンドリング | rules/error-handling.md | ApiError、トースト、Error Boundary |
| 命名規則 | rules/naming.md | ファイル/フック/型/定数の命名 |
完全なインデックスは INDEX.md を参照。
厳格度レベル
各ルールは次の3つの厳格度のいずれか:
| レベル | 意味 | AIの行動 |
|---|---|---|
| 🚫 MUST | 絶対に違反不可 | 常にこのパターンに従う |
| ⚠️ SHOULD | 特別な理由がなければ従う | デフォルトで適用、例外時はコメントで理由を明記 |
| ✅ MAY | 推奨するが柔軟に対応 | 状況に応じて判断 |
検証ワークフロー
「このプロジェクトを規約に基づいて検証して」と依頼された場合、次の順序で実行:
- テクノロジースタックの確認 — package.jsonでNext.js/React/TanStack Queryのバージョンを確認
- FSD構造の確認 (PS-01~05) — apps/*/entities、features、widgets、sharedが存在するか
- インポート方向の検証 (PS-02) — entityがfeatures/widgetsをインポートしている箇所を検索
- エンティティの完全性 (PS-03) — 各entityにapi.ts、queries.ts、hooks.ts、types.ts、index.tsが存在するか
- ミューテーションパターン (DF-06、DF-07) — useApiMutationの使用率、生のuseMutation違反を検索
- フォームパターン (FM-01~07) — zodスキーマの位置、useForm+zodResolver、フォームフックの抽出有無
- テーブルパターン (TB-01~05) — useReactTableインスタンスの方法、サーバーサイド手動モード
- 状態管理 (SM-01) — Context/zustandの使用有無（禁止）
- ファイル名ルール (NM-01) — kebab-caseの遵守率
出力形式:
- 違反リスト (ルールID +
file:line+ 修正提案) - 遵守率サマリー (カテゴリ別)
- 優先順位別の推奨事項 (🚫 を先に、⚠️ を次に)
タスク別クイックスタート
新しいエンティティの追加: architecture → api-layer → queries → mutations → naming CRUDフォームの実装: forms → mutations (DF-06、DF-07) → naming テーブルページの実装: tables → state-management → queries 新しいページ/ルートの追加: nextjs-patterns → architecture (PS-02、PS-05) エラー処理: error-handling パフォーマンス最適化: code-quality → queries (DF-10~12) 既存コードのリファクタリング: 該当領域のルールファイル全体
参考資料
- Anthropic Skill オーサリングのベストプラクティス: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices
- TanStack Query v5 ドキュメント: https://tanstack.com/query/latest
- Feature-Sliced Design: https://feature-sliced.design