shirokuma-docs 0.1.0-alpha.1

package/plugin/shirokuma-skills-ja/skills/nextjs-vibe-coding/patterns/testing.md

@@ -0,0 +1,298 @@
+# テストパターン
+
+## テストドキュメント（必須）
+
+全テストには @testdoc タグ付きの JSDoc コメントが必須。これにより以下が可能になる：
+- ドキュメントでの日本語テスト説明
+- ドキュメント自動生成
+- テスト意図の追跡
+
+### JSDoc 形式
+
+```typescript
+/**
+ * @testdoc 日本語でのテスト説明
+ * @purpose テストの目的を説明
+ * @precondition 前提条件
+ * @expected 期待される結果
+ */
+it("english test name for code", async () => {
+  // test implementation
+});
+```
+
+### 例
+
+```typescript
+describe("createUser", () => {
+  /**
+   * @testdoc 有効なデータで新規ユーザーを作成できる
+   * @purpose ユーザー作成の正常系確認
+   * @precondition 有効なメールアドレスとパスワード
+   * @expected ユーザーが作成され、IDが返される
+   */
+  it("should create user with valid data", async () => {
+    // ...
+  });
+
+  /**
+   * @testdoc 重複メールアドレスでエラーを返す
+   * @purpose 重複チェックの動作確認
+   * @expected DUPLICATE_EMAIL エラーが返される
+   */
+  it("should return error for duplicate email", async () => {
+    // ...
+  });
+});
+```
+
+### テストドキュメントの Lint
+
+```bash
+# テストドキュメントカバレッジチェック
+shirokuma-docs lint-tests -p . -c shirokuma-docs.config.yaml -f summary
+
+# 詳細レポート
+shirokuma-docs lint-tests -p . -c shirokuma-docs.config.yaml -f terminal
+
+# CI モード（閾値付き）
+shirokuma-docs lint-tests -p . --strict --coverage-threshold 50
+```
+
+### 実装-テストカバレッジチェック
+
+```bash
+# ソースファイルとテストファイルの対応チェック
+shirokuma-docs lint-coverage -p . -c shirokuma-docs.config.yaml
+
+# サマリーのみ
+shirokuma-docs lint-coverage -p . -c shirokuma-docs.config.yaml -f summary
+
+# strict モード（テスト不足で失敗）
+shirokuma-docs lint-coverage -p . -c shirokuma-docs.config.yaml -s
+```
+
+### @skip-test アノテーション
+
+テスト不要なファイルには JSDoc アノテーションを追加：
+
+```typescript
+/**
+ * @skip-test 自動生成コードのためテスト不要
+ */
+export const generatedSchema = { ... }
+```
+
+有効なスキップ理由：
+- 自動生成（auto-generated code）
+- shadcn/ui（ライブラリコンポーネント）
+- E2Eでカバー（covered by E2E tests）
+- 外部ライブラリ（external library wrapper）
+- 単純なre-export（simple re-export）
+
+## Jest 設定
+
+```javascript
+// jest.config.js
+const nextJest = require("next/jest")
+
+const createJestConfig = nextJest({ dir: "./" })
+
+module.exports = createJestConfig({
+  setupFilesAfterEnv: ["<rootDir>/jest.setup.ts"],
+  testEnvironment: "jsdom",
+  moduleNameMapper: {
+    "^@/(.*)$": "<rootDir>/$1",
+    "^@repo/database$": "<rootDir>/../../packages/database/src",
+  },
+})
+```
+
+## Jest セットアップ（モック）
+
+```typescript
+// jest.setup.ts
+import "@testing-library/jest-dom"
+
+// next/navigation のモック
+jest.mock("next/navigation", () => ({
+  useRouter: () => ({ push: jest.fn(), replace: jest.fn(), back: jest.fn() }),
+  usePathname: () => "/",
+  useSearchParams: () => new URLSearchParams(),
+}))
+
+// next-intl のモック
+jest.mock("next-intl", () => ({
+  useTranslations: () => (key: string) => key,
+  useLocale: () => "ja",
+}))
+```
+
+## Server Actions のテスト（キューベースモックパターン）
+
+Server Actions は複数のDBクエリを実行することが多い。キューベースパターンを使用：
+
+```typescript
+// FIFO キューを使ったDBモック
+jest.mock("@repo/database", () => {
+  const queryResults: any[] = []  // FIFO キュー
+
+  const createQueryBuilder = () => {
+    const builder: any = {
+      from: jest.fn(() => builder),
+      where: jest.fn(() => builder),
+      orderBy: jest.fn(() => builder),
+      limit: jest.fn(() => builder),
+      offset: jest.fn(() => builder),
+      set: jest.fn(() => builder),
+      returning: jest.fn(() => builder),
+      then: (resolve: any, reject: any) => {
+        const result = queryResults.shift() ?? []
+        if (result instanceof Error) return Promise.reject(result).catch(reject)
+        return Promise.resolve(result).then(resolve)
+      },
+      catch: (handler: any) => Promise.resolve([]).catch(handler),
+    }
+    return builder
+  }
+
+  return {
+    db: {
+      select: jest.fn(() => createQueryBuilder()),
+      insert: jest.fn(() => createQueryBuilder()),
+      update: jest.fn(() => createQueryBuilder()),
+      delete: jest.fn(() => createQueryBuilder()),
+    },
+    posts: { id: "id", title: "title", status: "status" },
+    eq: jest.fn((col, val) => ({ type: "eq", col, val })),
+    __queryResults__: queryResults,
+  }
+})
+
+// キュー参照の取得
+const dbModule = require("@repo/database") as any
+const queryResults = dbModule.__queryResults__ as any[]
+const queueQueryResult = (...results: any[]) => results.forEach(r => queryResults.push(r))
+const clearQueryResults = () => { queryResults.length = 0 }
+
+// 認証モック
+jest.mock("@/lib/auth", () => ({
+  verifyAdmin: jest.fn().mockResolvedValue({
+    user: { id: "user-1", email: "admin@example.com", role: "admin" },
+  }),
+}))
+
+// ヘッダー・キャッシュモック
+jest.mock("next/headers", () => ({
+  headers: jest.fn().mockResolvedValue(new Headers()),
+}))
+jest.mock("next/cache", () => ({
+  revalidatePath: jest.fn(),
+}))
+
+// テストでの使用
+beforeEach(() => { jest.clearAllMocks(); clearQueryResults() })
+
+it("fetches paginated data", async () => {
+  queueQueryResult([{ count: 50 }], [{ id: "1", title: "Post" }])
+  const result = await getPaginatedPosts(1, 10)
+  expect(result.data).toHaveLength(1)  // 注意: `items` ではなく `data`
+})
+```
+
+## i18n 対応コンポーネントのテスト
+
+```typescript
+import { render, screen } from "@testing-library/react"
+import { NextIntlClientProvider } from "next-intl"
+
+const messages = { common: { save: "Save" }, features: { title: "Features" } }
+
+function renderWithProviders(ui: React.ReactElement, locale = "en") {
+  return render(
+    <NextIntlClientProvider locale={locale} messages={messages}>
+      {ui}
+    </NextIntlClientProvider>
+  )
+}
+```
+
+## リダイレクトモックパターン
+
+`redirect()` を呼ぶ Server Actions にはテストで特別な対応が必要：
+
+```typescript
+// redirect を throw するようモック
+jest.mock("next/navigation", () => ({
+  redirect: jest.fn((url: string) => {
+    throw new Error(`NEXT_REDIRECT:${url}`)
+  }),
+  useRouter: () => ({ push: jest.fn(), replace: jest.fn(), back: jest.fn() }),
+  usePathname: () => "/",
+}))
+
+// リダイレクト動作のテスト
+it("redirects on success", async () => {
+  // モックのセットアップ...
+  mockVerifyAdminMutation.mockResolvedValueOnce("user-1")
+  queueQueryResult([])  // 重複なし
+
+  await expect(createFeature(validFormData())).rejects.toThrow("NEXT_REDIRECT:/features")
+  expect(revalidatePath).toHaveBeenCalledWith("/features")
+})
+```
+
+## i18n 対応 E2E セレクタ
+
+両言語対応の正規表現を使用：
+
+```typescript
+// パターン: /English|日本語/i
+await page.getByRole("heading", { name: /Post Management|投稿管理/i })
+await page.getByText(/Draft|下書き/i)
+await page.getByRole("button", { name: /Update|更新/i })
+await page.getByLabel(/^Email$|^メールアドレス$/i)
+await page.getByRole("button", { name: /login|ログイン|Log in/i })
+```
+
+## E2E テストセットアップパターン
+
+```typescript
+import { test, expect } from "@playwright/test"
+import { TEST_USERS } from "../fixtures/test-users"
+import { redisHelper } from "../helpers/redis"
+
+test.describe.serial("Feature CRUD Operations", () => {
+  test.beforeEach(async ({ page, context }) => {
+    // 状態クリア
+    await context.clearCookies()
+    await redisHelper.clearAllTestState()
+
+    // i18n 対応セレクタでログイン
+    await page.goto("/login")
+    await page.getByRole("textbox", { name: /Email|メールアドレス/i }).fill(TEST_USERS.admin.email)
+    await page.getByLabel(/^Password$|^パスワード$/i).fill(TEST_USERS.admin.password)
+    await page.getByRole("button", { name: /login|ログイン|Log in/i }).click()
+    await expect(page).toHaveURL(/\/$/, { timeout: 15000 })
+  })
+
+  test("can create an item", async ({ page }) => {
+    await page.goto("/features/new")
+    await page.getByRole("textbox", { name: /Name|名前/i }).fill("Test Feature")
+    await page.getByRole("button", { name: /Create|作成/i }).click()
+    await expect(page).toHaveURL(/\/features(?:\?.*)?$/, { timeout: 10000 })
+  })
+})
+```
+
+## コマンドリファレンス
+
+```bash
+# テスト
+pnpm --filter admin test              # 全実行
+pnpm --filter admin test --watch      # ウォッチモード
+pnpm --filter admin test --coverage   # カバレッジ付き
+
+# E2E テスト（Playwright Server）
+npx playwright test --reporter=list
+```

package/plugin/shirokuma-skills-ja/skills/nextjs-vibe-coding/reference/checklists.md

@@ -0,0 +1,76 @@
+# 実装チェックリスト
+
+コード品質と TDD 準拠を確認するためのチェックリスト。
+
+---
+
+## Server Action チェックリスト
+
+- [ ] `"use server"` ディレクティブがファイル先頭にある
+- [ ] **クエリ**: `verifyAdmin()` を使用（CSRF 不要）
+- [ ] **ミューテーション**: `verifyAdminMutation()` を使用（CSRF 含む）
+- [ ] Zod スキーマバリデーション
+- [ ] **更新/削除前にオーナーシップチェック**
+- [ ] **破壊的操作にレート制限**（削除、パスワードリセット）
+- [ ] **レスポンスにエラーコード**（`NOT_FOUND`, `FORBIDDEN`, `RATE_LIMIT_EXCEEDED`）
+- [ ] try/catch による適切なエラーハンドリング
+- [ ] 型付き `ActionResult<T>` レスポンスを返す
+- [ ] キャッシュに `revalidatePath()` または `revalidateTag()`
+- [ ] レスポンスに機密データを含まない
+
+---
+
+## ページコンポーネントチェックリスト
+
+- [ ] 非同期 params を `await` で取得
+- [ ] `setRequestLocale(locale)` を最初に呼び出す
+- [ ] サーバーサイド i18n に `getTranslations()` を使用
+- [ ] props に適切な TypeScript 型
+- [ ] データ読み込みに Suspense バウンダリ
+- [ ] 必要に応じて Error boundary (error.tsx)
+- [ ] 必要に応じて Loading state (loading.tsx)
+
+---
+
+## Client Component チェックリスト
+
+- [ ] `"use client"` ディレクティブがファイル先頭にある
+- [ ] i18n に `useTranslations()` を使用
+- [ ] フォーム送信に `useTransition()` を使用
+- [ ] ローディング状態とエラー状態
+- [ ] 適切なフォームバリデーション
+- [ ] アクセシブルなラベルと ARIA 属性
+
+---
+
+## i18n チェックリスト
+
+- [ ] `messages/ja.json` にキーを追加
+- [ ] `messages/en.json` にキーを追加
+- [ ] namespace パターンを使用（例: `features.form.name`）
+- [ ] ロケールに応じた日付フォーマット
+
+---
+
+## テストファーストチェックリスト
+
+完了報告前に確認：
+
+- [ ] **テストファイルを実装ファイルより先に作成**
+- [ ] Server Action テストが存在: `__tests__/lib/actions/{{name}}.test.ts`
+- [ ] コンポーネントテストが存在: `__tests__/components/{{name}}-form.test.tsx`
+- [ ] 全テストパス: `pnpm --filter admin test`
+- [ ] Lint エラーなし: `pnpm --filter admin lint`
+- [ ] 実装レポートを `GitHub Discussions (Reports)` に保存
+
+---
+
+## 完了要件
+
+**タスク完了前に全て TRUE であること：**
+
+- [ ] 全実装コードにテストファイルが存在
+- [ ] テストは実装前に作成（TDD）
+- [ ] 全テストが有効かつ実行可能（コメントアウトやスキップなし）
+- [ ] テストが実際の実装動作を検証
+- [ ] 実装レポートを `GitHub Discussions (Reports)` に保存済み

package/plugin/shirokuma-skills-ja/skills/nextjs-vibe-coding/reference/large-scale.md

@@ -0,0 +1,141 @@
+# 大規模ファイル分割ルール
+
+大規模プロジェクトでのファイル分割に関するルール。
+
+---
+
+## 分割閾値
+
+| ファイル種類 | 閾値 | アクション |
+|-------------|------|----------|
+| Server Actions | 300行 or 8関数以上 | ドメイン/操作で分割 |
+| i18n メッセージ | 300行 or 200キー以上 | namespace で分割 |
+| コンポーネント | 250行 | サブコンポーネントを抽出 |
+| スキーマ | 20テーブル以上 or 500行以上 | ドメインで分割（reference.md 参照） |
+
+---
+
+## Server Actions 分割パターン
+
+**300行を超えた場合、機能別に分割：**
+
+| ファイル | 用途 |
+|---------|------|
+| `lib/actions/posts/index.ts` | バレルエクスポート |
+| `lib/actions/posts/queries.ts` | getPaginatedPosts, getPostBySlug |
+| `lib/actions/posts/mutations.ts` | createPost, updatePost, deletePost |
+| `lib/actions/posts/filters.ts` | getPostsByCategory, getPostsByTag |
+| `lib/actions/__tests__/posts.test.ts` | テスト（元の場所を維持） |
+
+**重要**: テストファイルは `lib/actions/__tests__/` に維持。アクション分割時にテスト構造を変更しない。
+
+**index.ts:**
+```typescript
+export * from './queries'
+export * from './mutations'
+export * from './filters'
+```
+
+---
+
+## i18n メッセージ分割パターン
+
+**300行を超えた場合、namespace 別に分割：**
+
+| ファイル | 用途 |
+|---------|------|
+| `messages/{locale}/index.ts` | 統合エクスポート |
+| `messages/{locale}/common.json` | 共通 UI（ボタン、ラベル） |
+| `messages/{locale}/auth.json` | 認証（ログイン、サインアップ） |
+| `messages/{locale}/content.json` | コンテンツ（投稿、カテゴリ） |
+| `messages/{locale}/errors.json` | エラーメッセージ |
+| `messages/{locale}/validation.json` | 入力バリデーション |
+
+**index.ts:**
+```typescript
+import common from './common.json'
+import auth from './auth.json'
+import content from './content.json'
+import errors from './errors.json'
+import validation from './validation.json'
+
+export default { common, auth, content, errors, validation }
+```
+
+**next-intl 設定の更新 (`i18n/request.ts`):**
+```typescript
+import messages from `@/messages/${locale}`
+return { locale, messages }
+```
+
+---
+
+## コンポーネント分割パターン
+
+**250行を超えるコンポーネントはサブコンポーネントに分割：**
+
+| ファイル | 用途 |
+|---------|------|
+| `post-form.tsx` | メインラッパー（~80行） |
+| `post-form-editor.tsx` | Markdown エディタセクション |
+| `post-form-meta.tsx` | タイトル、スラッグ、抜粋 |
+| `post-form-category.tsx` | カテゴリ選択 |
+| `post-form-tags.tsx` | タグ選択 |
+| `post-form-actions.tsx` | 保存/キャンセルボタン |
+
+**post-form.tsx:**
+```tsx
+export function PostForm({ post, categories, tags }: PostFormProps) {
+  return (
+    <form action={handleSubmit}>
+      <PostFormMeta defaultValues={post} />
+      <PostFormEditor content={post?.content} />
+      <PostFormCategory categories={categories} />
+      <PostFormTags tags={tags} />
+      <PostFormActions isPending={isPending} />
+    </form>
+  )
+}
+```
+
+---
+
+## 共有ユーティリティの抽出
+
+**複数ファイルで使用するロジックを抽出：**
+
+| ファイル | 用途 |
+|---------|------|
+| `lib/actions/shared/pagination.ts` | ページネーションヘルパー |
+| `lib/actions/shared/filters.ts` | フィルタリングヘルパー |
+| `lib/actions/shared/validation.ts` | 共通バリデーション |
+
+---
+
+## 分割チェックリスト
+
+- [ ] バレルエクスポート（index.ts）を作成
+- [ ] 既存の import パスを維持（後方互換性）
+- [ ] テストは `lib/actions/__tests__/` に維持（分割不要）
+- [ ] ドキュメントを更新（CLAUDE.md）
+
+---
+
+## 分割テンプレート
+
+閾値超過時はこれらのテンプレートを使用：
+
+| ディレクトリ | 用途 |
+|-------------|------|
+| `templates/server-action-split/` | Server Actions の分割 |
+| `templates/messages-split/` | i18n メッセージの分割 |
+
+詳細は [templates/README.md](templates/README.md) を参照。
+
+---
+
+## 参考
+
+- **テンプレート詳細**: [templates/README.md](templates/README.md)
+- **スキーマ分割**: [reference.md - Drizzle ORM](reference.md)
+- **テストパターン**: [patterns/testing.md](patterns/testing.md)

package/plugin/shirokuma-skills-ja/skills/nextjs-vibe-coding/reference/reference.md

@@ -0,0 +1,171 @@
+# Next.js Vibe Coder ナレッジベース
+
+---
+
+## ドキュメント構造
+
+各ファイルの責任範囲：
+
+| ファイル | 責任 | 内容 |
+|---------|------|------|
+| **AGENT.md** | ワークフロー | 8ステップの実装手順のみ |
+| **reference.md**（このファイル） | クイックリファレンス | Tech Stack, Pattern一覧, Known Issues |
+| **checklists.md** | 品質ゲート | 実装完了前のチェックリスト |
+| **templates/README.md** | テンプレート仕様 | テンプレート一覧と使い方 |
+| **large-scale.md** | 分割ルール | ファイル分割の閾値とパターン |
+| **patterns/*.md** | 詳細パターン | 個別の技術パターン（Source of Truth） |
+
+**原則**: 情報は1箇所のみに記載。他は参照リンクのみ。
+
+---
+
+## 技術スタック
+
+| カテゴリ | テクノロジー |
+|----------|-------------|
+| フロントエンド | Next.js 16 / React 19 / TypeScript 5 |
+| データベース | PostgreSQL 16 + Drizzle ORM |
+| 認証 | Better Auth（DBセッション） |
+| i18n | next-intl (ja/en) |
+| スタイリング | Tailwind CSS v4 + shadcn/ui |
+| テスト | Jest + Playwright |
+
+> 詳細バージョン: プロジェクトの `CLAUDE.md` を参照
+
+---
+
+## パターンファイル
+
+詳細パターンは `patterns/` に整理されている。
+
+| ファイル | 説明 |
+|---------|------|
+| [coding-conventions.md](patterns/coding-conventions.md) | 命名規則、import順序、TypeScript、コンポーネント構造 |
+| [testing.md](patterns/testing.md) | Jest設定、モック、リダイレクトモック、i18n E2Eセレクタ |
+| [code-patterns.md](patterns/code-patterns.md) | 非同期params、Server Actions、i18n、フォーム、オーナーシップチェック |
+| [drizzle-orm.md](patterns/drizzle-orm.md) | スキーマ構成、クエリ、ページネーション、ILIKE |
+| [better-auth.md](patterns/better-auth.md) | 管理者認証、クライアントサイドセッション |
+| [tailwind-v4.md](patterns/tailwind-v4.md) | CSSファースト設定、変数構文、shadcn/ui |
+| [radix-ui-hydration.md](patterns/radix-ui-hydration.md) | **重要** DropdownMenu 用の mounted ステートパターン |
+| [csp.md](patterns/csp.md) | 本番CSP、style-src、worker-src 設定 |
+| [e2e-testing.md](patterns/e2e-testing.md) | テスト分離、フィクスチャ、ローディング状態テスト |
+| [documentation.md](patterns/documentation.md) | テストドキュメント、APIドキュメント、JSDocパターン |
+| [csrf-protection.md](patterns/csrf-protection.md) | 二関数認証パターン、CSRFバリデーション |
+| [rate-limiting.md](patterns/rate-limiting.md) | Redisベースレート制限、リミッター設定 |
+| [image-optimization.md](patterns/image-optimization.md) | LocalStack回避策、OptimizedAvatar |
+
+---
+
+## クイックリファレンス
+
+詳細はパターンファイルを参照。ここでは最重要パターンのみ記載。
+
+### Radix UI ハイドレーション（重要）
+
+```typescript
+const [mounted, setMounted] = useState(false)
+useEffect(() => { setMounted(true) }, [])
+
+if (!mounted) return <PlaceholderWithoutRadixUI />
+return <ComponentWithRadixUI />
+```
+
+→ 詳細: [radix-ui-hydration.md](patterns/radix-ui-hydration.md)
+
+### 主要パターン（詳細は各ファイル参照）
+
+| パターン | ファイル | 概要 |
+|---------|---------|------|
+| 非同期 Params | [code-patterns.md](patterns/code-patterns.md) | `params: Promise<...>` → `await params` |
+| Server Actions | [code-patterns.md](patterns/code-patterns.md) | `verifyAdminMutation()` → Validation → DB → Redirect |
+| CSRF 保護 | [csrf-protection.md](patterns/csrf-protection.md) | クエリ: `verifyAdmin()`, ミューテーション: `verifyAdminMutation()` |
+| レート制限 | [rate-limiting.md](patterns/rate-limiting.md) | 破壊的操作に `checkRateLimit()` |
+| オーナーシップチェック | [code-patterns.md](patterns/code-patterns.md) | ミューテーション前に `authorId === userId` を検証 |
+
+---
+
+## 既知の問題
+
+| 問題 | 症状 | 修正 |
+|------|------|------|
+| ハイドレーション不一致 | コンソールエラー "Hydration failed..." | `mounted` ステートパターンを使用 |
+| サイドバーの重なり | shadcn コンポーネント追加後にレイアウト崩れ | CSS 変数 fix スクリプトを実行 |
+| ILIKE インジェクション | 検索で予期しない結果 | `escapeLikePattern()` を使用 |
+| ページ読み込み遅延 | N+1 クエリ | `inArray()` でバッチクエリ |
+| 静的レンダリング失敗 | 翻訳が遅い | `setRequestLocale(locale)` を追加 |
+| 日本語 404 | タグ/カテゴリページが見つからない | `decodeURIComponent(slug)` を使用 |
+| ログインリダイレクトループ | ログイン成功後もログインに戻る | `window.location.href` を使用 |
+| CSP: インラインスタイルブロック | 本番: "style-src ... violated" | style-src に `'unsafe-inline'` 追加 |
+| Monaco Editor 壊れ | シンタックスハイライトなし、Worker エラー | CSP に `worker-src 'self' blob:'` 追加 |
+| LocalStack 画像 400 | アバター非表示、400 Bad Request | `unoptimized` プロップ使用。[image-optimization.md](patterns/image-optimization.md) 参照 |
+| レート制限超過 | "Try again in Xs" エラー | 想定動作。待機するか `RateLimiters` 設定を調整 |
+
+---
+
+## コマンドリファレンス
+
+```bash
+# テスト
+pnpm --filter admin test              # 全実行
+pnpm --filter admin test --watch      # ウォッチモード
+pnpm --filter admin test --coverage   # カバレッジ付き
+npx playwright test --reporter=list   # E2E テスト（Playwright Server）
+
+# Lint
+pnpm --filter admin lint              # ESLint
+pnpm --filter admin lint --fix        # 自動修正
+pnpm --filter admin tsc --noEmit      # TypeScript
+
+# 開発
+pnpm dev:admin                        # 開発サーバー起動
+pnpm --filter admin build             # 本番ビルド
+
+# データベース
+pnpm --filter @repo/database db:push  # スキーマ適用
+pnpm --filter @repo/database db:seed  # シードデータ投入
+```
+
+---
+
+## シードデータ構造
+
+### テストアカウント
+
+| ロール | メール | パスワード |
+|--------|--------|-----------|
+| Admin | admin@example.com | Admin@Test2024! |
+| User | user@example.com | User@Test2024! |
+
+### コンテンツデータ
+
+| エンティティ | 件数 | 備考 |
+|-------------|------|------|
+| カテゴリ | 5 | 技術, プログラミング, Web開発 等 |
+| タグ | 10 | JavaScript, TypeScript, React 等 |
+| 投稿 | 150 | カテゴリあたり30件、Markdown コンテンツ付き |
+| コメント | ~45 | 承認/保留/削除済みの混在、返信を含む |
+
+### シード実行
+
+```bash
+# Docker 内（正しい DATABASE_URL を使用）
+docker compose exec -T admin-app pnpm --filter @repo/database db:seed
+
+# 直接実行（明示的な URL）
+DATABASE_URL="postgresql://..." pnpm --filter @repo/database db:seed
+```
+
+---
+
+## ファイル構造リファレンス
+
+| パス | 用途 |
+|------|------|
+| `app/[locale]/(dashboard)/features/page.tsx` | 一覧ページ |
+| `app/[locale]/(dashboard)/features/new/page.tsx` | 作成ページ |
+| `app/[locale]/(dashboard)/features/[id]/edit/page.tsx` | 編集ページ |
+| `components/ui/` | shadcn/ui コンポーネント |
+| `components/feature-form.tsx` | 機能固有のフォーム |
+| `lib/actions/features.ts` | Server Actions |
+| `messages/{ja,en}/` | i18n 翻訳（ディレクトリ形式） |
+| `__tests__/` | ユニットテスト |