nextjs-standards

Next.js コーディング標準スキル

自動読み込みトリガー： next.config.* または package.json 内の "next" の存在

使用する場面

• 新しい Next.js プロジェクトを開始するとき
• TypeScript／React ファイルを編集する前
• セッションの途中でコンテキストを見失ったとき
• /agent_reset または /vibe-primeAgent の後

---

🛑 検証プロトコル（必須）

TypeScript／TSX ファイルを編集するたびに

npx tsc --noEmit

失敗した場合：

1. 次のファイルに進まないでください
2. 型エラーをすぐに修正してください
3. パスするまで再実行してください
4. パスしてから続行してください

引き継ぎの前に

python scripts/vibe-verify.py

「完了」と宣言する前に、すべてのチェックに合格する必要があります。

---

設計図とビルドのプロトコル

フェーズ 1：設計図（コーディング前）

1. docs/features/ に既存のパターンがないか確認します
2. docs/features/FeatureName.md を作成／更新します
3. コーディングを始める前に承認を待ちます

フェーズ 2：ビルド（実装）

1. 実装する FR-XXX を宣言します
2. docs/issues/ の対応するイシューを参照します
3. 一度に 1 つのステップずつ実装します
4. ファイルを編集するたびに tsc --noEmit を実行します
5. 受け入れ基準を完了としてマークします

フェーズ 3：最終化

1. 全体の検証（vibe-verify.py）を実行します
2. イシューファイルの完了ステータスを更新します
3. 引き継ぎ用の概要を作成します

---

フルスタックの型安全性

AI の信頼性を支える秘訣は、TypeScript が何かを壊したときに知らせてくれることです。

基本原則

バックエンドを変更した場合、フロントエンドの型チェックも必ず通る必要があります。型チェックに失敗した場合：

• 変更によって何かが壊れています
• 先に進む前に修正してください
• 型エラーを決して無視しないでください

スタックの連携

• Server Components がデータを取得し、型がクライアントに渡される
• API ルートが型付きレスポンスを返し、フロントエンドがそれを利用する
• Prisma スキーマを変更したら、クライアントを再生成して型チェックする

---

Next.js App Router のルール

1. Server Components をデフォルトにする — 必要な場合を除き 'use client' は使わない
2. Client Components は必要最小限にする — インタラクティブ機能、フック、ブラウザー API に限る
3. データ取得 — useEffect ではなく、非同期 Server Components で行う
4. Route Handlers — すべての API を app/api/.../route.ts に配置する
5. キャッシュ — { cache: 'no-store' } または revalidate = N を明示する

---

ファイル構成（機能単位の分割）

src/
├── app/                    # Next.js App Router pages
├── features/               # Business domains
│   └── [FeatureName]/
│       ├── components/     # Feature-specific components
│       ├── hooks/          # Feature-specific hooks
│       └── *.service.ts    # Business logic
├── components/
│   ├── ui/                 # Reusable UI (Button, Card)
│   └── layout/             # Layout components
├── lib/                    # Utilities, clients
└── scripts/                # Automation (vibe-verify.py)

---

コンポーネントのルール

1. 200 行制限 — 超えた場合はリファクタリングします
2. 単一責任 — コンポーネントごとに役割を 1 つにします
3. Props インターフェース — 必ず TypeScript のインターフェースを使います
4. カスタムフック — 状態を持つロジックを use* フックに切り出します

---

スタイリング（Tailwind v4）

AI の信頼性を高める Tailwind の理由： Tailwind はスタイルを UI とともに 1 つのファイルにまとめます。個別の .css ファイルとは異なり、AI エージェントはファイル間を行き来せずに、ロジック、スタイル、構造のすべてを含むコンテキストを確認できます。これにより、ハルシネーションとコンテキストの断片化が大幅に減少します。

@import "tailwindcss";

@theme {
  --color-background: #ffffff;
  --color-foreground: #0b1221;
  --color-border: #e5e7eb;
}

@theme .dark {
  --color-background: #0b1221;
  --color-foreground: #e5e7eb;
}

• tailwind.config の拡張ではなく、@theme トークンを使います
• ユーティリティファーストとし、カスタム CSS ファイルは使いません
• <html> の .dark クラスでダークモードを適用します

---

バックエンドのルール

サービスレイヤーパターン

• Route Handlers ＝ コントローラー（リクエストを解析し、レスポンスを返す）
• Services ＝ ビジネスロジック（DB クエリ、計算）

バリデーション

import { z } from 'zod';

const schema = z.object({
  email: z.string().email(),
  password: z.string().min(8),
});

すべての入力を Zod で検証します。例外はありません。

---

利用可能なテンプレート

このスキルには templates/ 内にテンプレートが用意されています：

1. Coding_Guidelines.md — docs/Coding_Guidelines.md にコピーします
2. Issue_Template.md — FR イシューのフォーマット

---

クイックリファレンス

コマンド	実行するタイミング
npx tsc --noEmit	TS／TSX の編集後
python scripts/vibe-verify.py	引き継ぎ前
npm run lint	コードスタイルのチェック
npm run build	本番ビルドの検証

---

復旧プロトコル

何かを壊してしまった場合：

git status                    # See changed files
git diff                      # See what changed
git checkout -- <file>        # Revert specific file
git stash                     # Save and revert all