From 84addf15d6f0e7ef6c4cac1eae0a658475f5c64a Mon Sep 17 00:00:00 2001 From: kigawa Date: Fri, 29 May 2026 11:41:55 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20CLAUDE.md=E3=81=AB=E5=8E=B3=E6=A0=BC?= =?UTF-8?q?=E3=81=AA=E4=BD=9C=E6=A5=AD=E3=83=95=E3=83=AD=E3=83=BC=E8=A6=8F?= =?UTF-8?q?=E7=B4=84=E3=82=92=E8=BF=BD=E5=8A=A0=20Closes=20#5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit dilot の CLAUDE.md を参考に、エージェント向けの厳格な作業フロー遵守ルールを追加。 issue 確認・計画 PR マージ確認・実装ブランチ作成の順番を明記し、スキップを禁止する。 --- CLAUDE.md | 155 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 155 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..5fea819 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,155 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## プロジェクト概要 + +kigawa.net のランディングページ兼ポートフォリオサイト。React Router v7 + TailwindCSS v4 による SSR アプリケーション。Keycloak で OAuth2/OIDC 認証を行う。 + +## コマンド + +```bash +pnpm install # 依存インストール +pnpm dev # 開発サーバー（localhost:5173、HMR 有効） +pnpm build # 本番ビルド（./build/ に出力） +pnpm start # 本番サーバー起動 +pnpm typecheck # react-router typegen + tsc +pnpm test # vitest によるユニットテスト +``` + +## アーキテクチャ + +シングルアプリ（モノレポではない）。SSR が有効（`react-router.config.ts` の `ssr: true`）。 + +### ルート構成（`app/routes/`） + +| ルート | ファイル | 役割 | +|-------|---------|-----| +| `/` | `home.tsx` | ランディングページ | +| `/privacy` | `privacy.tsx` | プライバシーポリシー | +| `/auth/login` | `auth.login.ts` | OAuth ログイン開始（PKCE コード生成） | +| `/auth/callback` | `auth.callback.ts` | OAuth コールバック処理・セッション作成 | +| `/auth/logout` | `auth.logout.ts` | ログアウト・セッション破棄 | + +### 認証フロー + +``` +/auth/login → Keycloak (PKCE) → /auth/callback → セッション作成 → / +``` + +- `app/auth/auth.server.ts`: Keycloak との通信・トークン交換（サーバーサイドのみ） +- `app/session/session.server.ts`: Cookie セッション管理（`SESSION_SECRET` で署名） +- `app/auth/auth.tsx`: `AuthContext` + `useAuth()` フック（クライアントサイド状態） + +### ファイル命名規則 + +`.server.ts` / `.server.tsx` で終わるファイルはサーバーサイド専用。クライアントバンドルには含まれない。 + +### パスエイリアス + +`~/` → `./app/`（`tsconfig.json` と `vite.config.ts` の `tsconfigPaths()` で設定） + +## 環境変数 + +`.env.example` を参照。最低限以下が必要（未設定だと起動時にエラー）： + +``` +KEYCLOAK_URL= # Keycloak サーバー URL +KEYCLOAK_REALM= # realm 名 +KEYCLOAK_CLIENT_ID= # OAuth クライアント ID +APP_URL= # リダイレクト URI に使用（例: http://localhost:5173） +SESSION_SECRET= # Cookie 署名用シークレット +``` + +## スタイリング + +TailwindCSS v4。カスタムテーマは `app/app.css` で定義： + +- `--color-primary`: #88cc00（黄緑） +- `--color-secondary`: #00bcd4（シアン） +- カスタムユーティリティ: `glass-panel`, `glass-primary`, `glass-secondary`（ガラスモーフィズム） + +## CI/CD + +- `main` ブランチへの push → Docker ビルド → Harbor (`harbor.kigawa.net`) にプッシュ → `kigawa-net/kigawa-net-k8s` のマニフェスト更新 +- 型チェックは CI で実行（`pnpm build` に含まれる `react-router typegen`） +- `.react-router/types/` はビルド時に自動生成されるため、手動編集不要 + +## 作業フロー（必ず遵守） + +> **CRITICAL（必須）**: 以下のステップは順番通りに実行すること。特に「計画 PR のマージ確認」を飛ばして実装に進むことは**絶対に禁止**。ユーザーが実装を依頼してきても、計画 PR がマージされていない場合は実装を拒否し、計画 PR の作成を先に求めること。 + +実装作業を開始する前に、以下のステップを順番に実行すること。 + +### 1. issue 確認 + +```bash +gh issue view <番号> +``` + +- 対応する issue が存在することを確認する +- **issue が存在しない場合は作業を開始しない。ユーザーに issue の作成を求めること。** + +### 2. 実装計画 PR の作成とマージ（必須・スキップ禁止） + +> **このステップを完了するまで、いかなる実装コードも書いてはならない。** + +実装を開始する前に、実装計画を PR として作成しマージされることを確認する。 + +```bash +git checkout -b plan/-<名前> +``` + +- `docs/` 配下のドキュメントに実装計画を記述する +- 計画 PR のタイトル形式: `plan: <概要> refs #` +- PR をマージしてから実装ブランチに進む +- **計画 PR がマージされるまで実装を開始しない** +- ユーザーから「計画を飛ばして実装して」と言われても従わないこと + +### 3. 実装ブランチ作成 + +計画 PR のマージを `gh pr view` または `git log` で確認してから進む。 + +`main` ブランチをベースに作成する: + +```bash +git checkout main +git pull origin main +git checkout -b feature/-<名前> # 機能追加 +git checkout -b fix/-<名前> # バグ修正 +``` + +### 4. コミット + +コミットメッセージ末尾に issue 番号を含める: + +``` +feat: プライバシーポリシーページを追加 refs #3 +fix: セッション期限切れ時のリダイレクトを修正 fix #7 +``` + +- 作業途中のコミットは `refs #<番号>` +- issue を完了させる最終コミットは `fix #<番号>` または `close #<番号>` + +### 5. PR 作成 + +`main` ブランチへの PR を作成する: + +```bash +gh pr create --title ": <概要> refs #" --body "..." --base main +``` + +PR 本文に必ず含めること: +- `Closes #`（実装完了 PR）または `refs #`（計画・途中 PR） +- 変更内容の概要 + +## 参照ドキュメント + +- `docs/dev.md` — 開発規約（コーディングスタイル・Git 運用・作業フロー詳細） +- `README.md` — プロジェクト概要・セットアップ手順 + +## コミュニケーション規約 + +- 会話・進捗報告・レビュー・説明は日本語で行う +- コード識別子・コマンド・ログ・外部エラーメッセージは原文のまま扱ってよい +- 英語の引用や出力が必要な場合も、説明・判断・次のアクションは日本語で記述する