ahmad-00/claude-skills

シニア Next.js / React / TypeScript エンジニア

Next.jsの進化は速く、モデルのメモリは古くなりがちです。バージョンに依存するAPIを使用する前に、references/versions.mdを確認してください。インストールされているnextにバンドルされたドキュメント（node_modules/next/dist/docs/）やNext.jsが生成したAGENTS.mdがある場合は、メモリよりもそれらを優先してください。

ステップ0：バージョンと規約を検出する（常に実行）

bash scripts/detect_versions.sh（読み取り専用）を実行し、次に確認します：

• package.json + ロックファイル（pnpm/npm/yarn/bun）→ next、react、typescript、tailwindcss、テストツール；ロックファイルのパッケージマネージャーを使用
• next.config.* → cacheComponents、partialPrefetching、reactCompiler、experimental.*
• ルーター：app/ vs src/app/、pages/の有無（混在ルーター）、proxy.ts vs レガシー middleware.ts
• データ層：ORM/SDK、既存のlib/dal.tsまたはserver-onlyモジュール、認証ライブラリ
• スタイリングとUIキット（Tailwindバージョン、CSS Modules、shadcn/ui、デザイントークン）、lint/format（ESLint flat config vs Biome）
• テスト：Vitest/Jest、Testing Library、Playwright；既存のCIスクリプト

既存の規約に合わせてください。プロジェクトが古いメジャーバージョンを使用している場合は、そのバージョンで動作するコードを書いてください。

デフォルト（決定ごとに1つ、エスケープハッチ付き）

決定	デフォルト	代替案を使用する場合
コンポーネントタイプ	Server Component	状態、エフェクト、ブラウザAPI、イベントハンドラが必要 → 最小のリーフで "use client"
キャッシュモデル（16.x）	Cache Components（cacheComponents: true、'use cache' + cacheLife/cacheTag）	移行予定のない以前のモデルを使用している既存アプリ。中途半端な移行はしない
ミューテーション	Server Actions + revalidateTag/updateTag/refresh	他のクライアントから利用されるパブリックAPI → ルートハンドラ
データアクセス	すべての読み取り/書き込みを認証・認可する単一のサーバー専用データアクセス層（DAL）	—
リクエストインターセプション	リダイレクト/リライト/ヘッダーのみにproxy.tsを使用	唯一のチェックとしての認証には絶対に使用しない
ランタイム	Node.js（デフォルト）	16.3以降ではなし：runtime = 'edge'は非推奨/未サポート
フォーム	<form action={serverAction}> + useActionState + サーバー側でのスキーマバリデーション（zodまたはプロジェクトのもの）	複雑なクライアント専用ウィザード → プロジェクトに既存のクライアントフォームライブラリ
スタイリング	プロジェクトのシステム；新規プロジェクトではCSSファースト設定のTailwind CSS v4	—
クライアント状態	URL検索パラメータ → サーバー状態 → React状態；グローバルストアは本当に必要な場合のみ	—
メモ化	React Compilerが有効な場合に使用；それ以外は測定済みのホットスポットのみメモ化	—
テスト	ユニットはVitest + Testing Library；E2EクリティカルフローはPlaywright	Jestが既に設定されている

ワークフローA：ルートまたは機能を構築する

- [ ] ステップ0完了
- [ ] ルートセグメント：必要に応じてpage.tsx、layout.tsx、loading.tsx/Suspenseバウンダリ、error.tsx、not-found.tsx
- [ ] DALを介したデータ（サーバー専用）、Server Components内でawait；params/searchParamsはPromise：`const { id } = await params`
- [ ] キャッシュするもの（'use cache' + cacheLife/cacheTag）とリクエスト時（Suspense内）を決定
- [ ] Server Actionsを介したミューテーション：入力を検証、アクション内で認可を再チェック、タグを再検証
- [ ] Client Componentsは最小限に；propsはシリアライズ可能；クライアントバンドルにシークレットを含めない（ブラウザに到達するのはNEXT_PUBLIC_*のみ）
- [ ] アクセシビリティ：セマンティック要素、ラベル、フォーカス管理、キーボードパス、色のコントラスト
- [ ] ロジックのテスト + クリティカルパスのE2Eを1つ
- [ ] 検証ループを通過

検証 → 修正 → 繰り返し：

pnpm exec tsc --noEmit            # または npm/yarn/bun の同等コマンド
pnpm lint                          # ESLint または Biome（プロジェクトに応じて；next lint は16で削除されました）
pnpm test -- --run                 # Vitest
pnpm build                         # Cache Components / プリレンダリングエラーをキャッチ
pnpm exec playwright test          # E2Eが存在する場合

next buildで<Suspense>外のキャッシュされていないデータに関するエラーは、ノイズではなくシグナルです。'use cache'を追加するか、アクセスをSuspenseバウンダリ内に移動するか、リクエスト時としてマークすることで修正してください。

ワークフローB：Next.jsのアップグレード（自由度は低い）

- [ ] `references/versions.md`の「古いパターン」とセキュリティフロアを読む
- [ ] クリーンなツリーをコミット；ブランチを作成
- [ ] 公式アップグレードツールを実行：`npx next@canary upgrade --agent=latest`
      （エージェントフローが利用不可の場合は `npx @next/codemod@canary upgrade latest`）
- [ ] nextと一緒にreact、react-dom、@types/reactをアップグレード
- [ ] `runtime = 'edge'`のエクスポートを削除；middleware.tsをproxy.tsにリネーム（Nodeランタイム）
- [ ] 検証ループ；その後、認証、リダイレクト、キャッシュ、再検証を手動でスモークテスト

セキュリティを最優先：インストールバージョンがversions.mdのパッチ適用済みフロアより低い場合は、next自体をアップグレードしてください（Reactパッケージのみのパッチでは不十分です）。

ワークフローC：既存アプリにCache Componentsを導入する

ルートごとに移行します。ブランチでcacheComponents（16.4以降ではpartialPrefetching）を有効にし、next buildを実行し、報告された各バウンダリを修正します。references/caching.mdを参照してください。インストールされている場合、Next.jsのnext-cache-components-adoptionスキルがその仕組みを詳細にカバーしているので、このスキルと併用してください。

認証とセキュリティルール

• DAL、およびすべてのServer Actionsとルートハンドラで認可を行ってください。プロキシ/ミドルウェアのチェックは楽観的なリダイレクトにすぎません。CVE-2025-29927は、ヘッダーベースのミドルウェアバイパスが可能であることを示しました。
• Server ActionsはパブリックHTTPエンドポイントです：入力を検証し、セッションを確認し、所有権を確認してください。
• シークレットやDBアクセスを含むモジュールではserver-onlyをインポートし、Client ComponentsにはDTO（必要なフィールドのみ）を返してください。
• 詳細：references/data-and-auth.md。

設計またはモックアップからの実装

1. 設計を棚卸しする：トークン（色、タイプスケール、スペーシング、半径）、コンポーネント、状態（ホバー、フォーカス、無効、ローディング、空、エラー）、ブレークポイント。
2. まずプロジェクトの既存トークンとコンポーネントにマッピングし、新しいトークンは一時的な値ではなくテーマに追加します。
3. まず静的なServer Componentのマークアップを構築し、リーフでインタラクティビティを追加します。
4. 320px、タブレット、デスクトップの幅で確認します。キーボードとスクリーンリーダーのラベルを確認します。prefers-reduced-motionを尊重します。
5. ブラウザツールまたはPlaywrightが利用可能な場合は、スクリーンショットを撮ってモックアップと比較し、スペーシングとタイポグラフィが一致するまで繰り返します。

レビューモード

references/review-checklist.mdを使用します。各指摘事項をブロッカー / 修正すべき / 細かい点として、ファイル:行、問題、具体的なコード修正とともに報告します。指摘事項を重大度順に並べてください。ブロッカーには、プロキシのみの認証、クライアントバンドルに漏洩したシークレット、未検証のServer Action入力、脆弱なnextバージョン、共有'use cache'スコープ内のユーザー固有データなどが含まれます。

リファレンスマップ

• references/versions.md：バージョン、セキュリティフロア、古いパターン、確認メモ
• references/data-and-auth.md：DALパターン、Server Actionテンプレート、セッション処理
• references/caching.md：Cache Componentsルール、ensureStatic、navigation()/prefetch()
• references/review-checklist.md：影響度順のルール