bencium-code-conventions

コード規約

中核となる技術

• フロントエンド： ReactJS、Next.js（App Router 構成）、TypeScript
• スタイリング： TailwindCSS v3.x（v4 は使用しない）、Shadcn UI
• ビルドツール： Vite（該当する場合）
• バックエンド： convex.dev または Supabase と互換性のある Postgres（必ず確認し、ローカルの postgres は使用しない）
• デプロイ： Netlify、Vercel、または Fly を提案する
• 環境： Mac M2、仮想環境を使用する Python3、CUDA なし、Docker なし
• 代替言語： 可能であれば python は避け、RUST の使用を試みる

コードスタイルと構成

• ES modules（import/export）構文を使用する
• 可能な場合はインポートを分割代入する
• 新しいコードはすべて TypeScript を使用する
• Promise チェーンではなく async/await を使用する
• var より const/let を優先し、早期リターンを使用する
• 関数ではなく const を使用する：const toggle = () =>。型を定義する
• 補助動詞を含む、説明的な変数名を使用する（例：isLoading、hasError）
• ディレクトリ名は小文字とハイフンを使用する（例：components/auth-wizard）

フレームワーク規約

• Next.js： App Router（app ディレクトリ）構成と page.tsx ファイルを使用する
• React： 関数型かつ宣言的なパターンを使用し、クラスは避ける
• 状態管理： Zustand、TanStack React Query
• バリデーション： スキーマ検証には Zod を使用する

コンポーネントライブラリとスタイリング

• コンポーネントライブラリ： @/components/ui の shadcn コンポーネントを優先する
• スタイリング： Tailwind のユーティリティクラス
• レイアウト： 間隔には gap を使った Grid／flex ラッパーを使用する
• アイコン： @phosphor-icons/react
• トースト： 通知には sonner を使用する
• ローディング状態、スピナー、プレースホルダーアニメーションを必ず追加する

品質保証とテスト

• TDD： まず失敗するテストを書いてコミットし、テストスイートが通るまで反復する
• テストをモックしない。テストスクリプトがある場合は、すべて完了するまで実行する
• SQL はチャンクごとに記述し、各チャンクの後にテスト手順を実施する
• コード変更後は型チェックを行う
• コミット前にテストを実行する
• パフォーマンスを優先し、スイート全体ではなく単一のテストを実行する

エラー処理

• 適切なエラー処理とユーザー入力の検証を実装する
• エラーメッセージは技術に詳しくない人にも理解できるものにする
• エラー条件では早期リターンを使用する
• まず curl コマンドで API をテストしてから、コードに実装する

パフォーマンスとアーキテクチャ

• 'use client'、useEffect、setState を最小限にし、RSC と Next.js SSR を優先する
• コード分割のために動的インポートを実装する
• 画像を最適化する：WebP 形式、サイズデータ、遅延読み込み
• 小さく、シンプルで、わかりやすい名前のモジュールを優先する

開発ワークフロー

プロセス： 調査 → 計画 → コーディング → コミット

• 関連ファイルを読む
• 計画をよく考える
• 実装する
• その後コミットする
• ローカルのバックエンドは使用せず、必ず確認する（通常は Supabase、Neon）
• 依存関係は最小限にし、docker は使用しない

環境とデプロイ

• API キー用に .env ファイルを追加する。キーを Vercel/Netlify の環境変数に保存するよう注意を促す
• Netlify または Vercel にデプロイ可能なコードを記述し、まずローカルでビルドできるよう準備する
• progress.md に進捗を記録し、実装計画を確認する