CLAUDE.md 設定ガイド

/init

# プロジェクト名

## 概要
プロジェクトの目的と技術スタックを簡潔に説明する。

## 技術スタック

- ランタイム：Node.js 20
- フレームワーク：Next.js 15
- スタイリング：Tailwind CSS
- データベース：PostgreSQL + Prisma

## よく使うコマンド

- 開発サーバーの起動：`npm run dev`
- テストの実行：`npm test`
- プロダクションビルド：`npm run build`
- コードチェック：`npm run lint`

## コーディング規約

- TypeScript を使用し、`any` 型は禁止
- コンポーネントは関数型で記述する
- スタイリングは Tailwind のみ使用し、インライン style は書かない
- コミットメッセージの形式：`feat:` / `fix:` / `docs:` などのプレフィックス

## プロジェクト構造

- `src/app/` — Next.js App Router ページ
- `src/components/` — 再利用可能なコンポーネント
- `src/lib/` — ユーティリティ関数
- `prisma/` — データベーススキーマとマイグレーション

## 注意事項

- `prisma/migrations/` は変更せず、新しいマイグレーションのみ作成する
- すべての API ルートは `src/app/api/` にある
- 画像リソースは `public/images/` に配置する

## パッケージ管理
pnpm を使用し、npm や yarn は使わないこと。
依存関係のインストール：`pnpm install`
依存関係の追加：`pnpm add <パッケージ名>`

## テスト

- ユニットテスト：`vitest`、ファイル名は `.test.ts` で終わる
- E2E テスト：`playwright`、`tests/e2e/` に配置
- ユニットテストの実行：`pnpm test:unit`
- E2E の実行：`pnpm test:e2e`
- 新機能にはテストを必ず含める

## 禁止操作

- `console.log` を使わず、プロジェクトの `logger` モジュールを使用する
- `package-lock.json` を直接変更しない
- `main` ブランチに直接コミットせず、フィーチャーブランチを使用する

## アーキテクチャの説明
このプロジェクトはヘキサゴナルアーキテクチャ（Hexagonal Architecture）を採用しています：

- `domain/` — ビジネスロジック、外部フレームワークに依存しない
- `application/` — ユースケース、domain と infrastructure を調整する
- `infrastructure/` — データベース・HTTP などの外部アダプター
- `interfaces/` — Web コントローラー・CLI などのエントリーポイント
新機能はこの階層構造に従い、domain 層に外部依存を持ち込まないこと。

## 詳細情報

- API ドキュメント：`docs/api.md`
- デプロイ手順：`docs/deploy.md`
- データベーススキーマ：`prisma/schema.prisma`

# MyApp Frontend

## 技術スタック

- React 19 + TypeScript 5.x
- ビルドツール：Vite 6
- スタイリング：Tailwind CSS v4（utility-first、インライン style は書かない）
- 状態管理：Zustand（グローバル）、TanStack Query（サーバー状態）
- ルーティング：React Router v7
- テスト：Vitest + Testing Library + MSW

## コマンド

- 開発：`pnpm dev`（ポート 3000）
- テスト：`pnpm test`（Vitest watch モード）
- 単発テスト：`pnpm test:run`
- ビルド：`pnpm build`
- Lint：`pnpm lint`（ESLint + Prettier）
- 型チェック：`pnpm typecheck`

## コーディング規約

- コンポーネント：関数コンポーネント + Hooks、class コンポーネントは禁止
- Props：`interface` で定義する（`type` は使わない）
- ファイル名：コンポーネントは PascalCase（UserProfile.tsx）、ユーティリティは camelCase（formatDate.ts）
- インポート順：React → サードパーティ → プロジェクト内部 → スタイル
- `any` 型は禁止、明示的な型注釈を必須とする
- 非同期処理は TanStack Query に統一し、`useEffect` + `fetch` を直接書かない

## プロジェクト構造

- src/components/ — 再利用可能な UI コンポーネント
- src/pages/ — ルートページ
- src/hooks/ — カスタム Hooks
- src/api/ — API リクエストのラッパー（TanStack Query の queryFn）
- src/stores/ — Zustand stores
- src/lib/ — ユーティリティ関数
- src/types/ — グローバル型定義

## 注意事項

- パッケージマネージャー：pnpm（npm や yarn ではない）
- Node.js 22+
- すべての API リクエストは src/api/client.ts を経由する（インターセプター付き）
- 画像は public/images/ に置き、/images/ パスで参照する

# MyApp Backend

## 技術スタック

- Python 3.12 + FastAPI
- ORM：SQLAlchemy 2.0（async）+ Alembic マイグレーション
- データベース：PostgreSQL 16
- キャッシュ：Redis 7
- テスト：pytest + httpx + factory_boy

## コマンド

- 開発：`uvicorn app.main:app --reload --port 8000`
- テスト：`pytest -xvs`
- マイグレーション：`alembic upgrade head`
- 新規マイグレーション：`alembic revision --autogenerate -m "説明"`
- Lint：`ruff check .`
- フォーマット：`ruff format .`
- 型チェック：`mypy app/`

## コーディング規約

- 型注釈：すべての関数の引数と戻り値に型ヒントを付ける
- async/await：すべての I/O 操作は async を使用する
- Pydantic v2：リクエスト／レスポンスの schema は Pydantic BaseModel に統一する
- 依存性注入：データベース接続・認証などは FastAPI Depends() で注入する
- エラー処理：業務例外は app.exceptions.AppError を継承する

## プロジェクト構造

- app/main.py — アプリケーションのエントリーポイント
- app/api/ — ルート（リソースごとにファイル分割）
- app/models/ — SQLAlchemy モデル
- app/schemas/ — Pydantic schemas
- app/services/ — ビジネスロジック
- app/core/ — 設定・データベース・セキュリティなどのコアモジュール
- tests/ — テストファイル（app/ の構造をミラーする）
- alembic/ — データベースマイグレーション

## 注意事項

- alembic/versions/ にある既存のマイグレーションファイルは変更しない
- .env ファイルは Git にコミットせず、app/core/config.py の Settings クラスで読み込む
- 仮想環境：`python -m venv venv && source venv/bin/activate`

# MyService

## 技術スタック

- Go 1.23
- HTTP フレームワーク：Echo v4
- データベース：PostgreSQL + sqlc（型安全な SQL）
- メッセージキュー：NATS JetStream
- コンテナ化：Docker + docker-compose

## コマンド

- 実行：`go run ./cmd/server`
- テスト：`go test ./...`
- ビルド：`go build -o bin/server ./cmd/server`
- sqlc 生成：`sqlc generate`
- Lint：`golangci-lint run`

## コーディング規約

- エラー処理：必ず err をチェックし、_ で無視しない
- インターフェース命名：単一メソッドのインターフェースには -er 接尾辞を付ける（Reader, Writer）
- パッケージ命名：小文字の単語、アンダースコアは使わない
- ロギング：slog による構造化ログを使用する
- コンテキスト：すべての関数の第一引数に context.Context を渡す

## プロジェクト構造（標準 Go レイアウト）

- cmd/server/ — メインプログラムのエントリーポイント
- internal/handler/ — HTTP handler
- internal/service/ — ビジネスロジック
- internal/repository/ — データアクセス層
- internal/model/ — データモデル
- sql/ — SQL クエリファイル（sqlc が使用）

# MyPlatform Monorepo

## 技術スタック

- パッケージ管理：pnpm workspace
- ビルドシステム：Turborepo
- 言語：TypeScript でフルスタック

## コマンド

- 全体の開発：`pnpm dev`
- 全体のテスト：`pnpm test`
- 全体のビルド：`pnpm build`
- 単一パッケージの開発：`pnpm --filter @myplatform/web dev`
- 依存関係の追加：`pnpm --filter @myplatform/api add express`

## パッケージ構造

- apps/web/ — Next.js フロントエンド
- apps/api/ — Express バックエンド
- apps/admin/ — 管理ダッシュボード
- packages/ui/ — 共有 UI コンポーネントライブラリ
- packages/config/ — 共有設定（eslint, tsconfig）
- packages/types/ — 共有型定義

## 注意事項

- 共有コードは packages/ に置き、apps 同士で直接参照しない
- 新しいパッケージを作成する際は packages/ui/package.json の形式を参考にする
- Turborepo キャッシュ：ビルド成果物は node_modules/.cache/turbo にキャッシュされる

# ML Pipeline

## 技術スタック

- Python 3.12
- フレームワーク：PyTorch 2.5 + Lightning
- データ処理：Polars（Pandas は使わない）
- 実験トラッキング：MLflow
- 依存管理：uv

## コマンド

- 訓練：`python -m src.train --config configs/experiment.yaml`
- 評価：`python -m src.evaluate --checkpoint runs/latest`
- データ前処理：`python -m src.preprocess --data-dir data/raw`
- Jupyter：`jupyter lab`
- テスト：`pytest tests/`

## コーディング規約

- 設定は YAML を使う（ハイパーパラメータをハードコードしない）
- データ処理は Polars を使う（Pandas より速く、型安全）
- すべての実験は MLflow に記録する
- Notebook は探索専用、プロダクションコードは必ず src/ に置く

## プロジェクト構造

- configs/ — 実験設定 YAML
- data/raw/ — 生データ（Git にコミットせず、DVC で管理）
- data/processed/ — 処理済みデータ
- src/ — コアコード（model, data, train, evaluate）
- notebooks/ — 探索的分析
- runs/ — 訓練の出力（checkpoints, logs）

# プロジェクトルール

@AGENTS.md

## Claude Code 固有

- 大規模リファクタリングでは /model で Opus 4.8 に切り替える
- docs/architecture.md は貼り付けず、パスで参照する