shirokuma-docs 0.1.0-alpha.1

package/plugin/shirokuma-skills-ja/skills/reviewing-on-issue/patterns/code-quality.md

@@ -0,0 +1,244 @@
+# コード品質パターン
+
+Next.js TDD Blog CMS プロジェクトのコード品質パターンとベストプラクティス。
+
+## フォームデータパースパターン
+
+手動パースの代わりに `parseFormData` ユーティリティを使用:
+
+```typescript
+// GOOD: parseFormData ユーティリティを使用
+import { parseFormData } from "@/lib/utils/form"
+
+const data = parseFormData(formData, schema)
+
+// BAD: 手動パース
+const data = Object.fromEntries(formData) as unknown as T
+```
+
+## トランザクションエラーハンドリング
+
+DB トランザクションは必ず try-catch で囲む:
+
+```typescript
+// GOOD: 適切なエラーハンドリング
+try {
+  await db.transaction(async (tx) => {
+    await tx.insert(table).values(data)
+  })
+} catch (error) {
+  return { success: false, error: "database_error" }
+}
+
+// BAD: エラーハンドリングなし
+await db.transaction(async (tx) => {
+  await tx.insert(table).values(data)
+})
+```
+
+## 型の整理
+
+### 共有パッケージ (`@repo/shared`)
+- 2つ以上のアプリで使用される型
+- 共通ドメインモデル
+
+```typescript
+// packages/shared/src/types/index.ts
+export interface User {
+  id: string
+  email: string
+  name: string
+}
+```
+
+### アプリ固有型
+- 単一アプリ内で使用される型
+- `lib/actions/types.ts` に配置
+
+```typescript
+// apps/admin/lib/actions/types.ts
+export interface CategoryFormState {
+  success: boolean
+  error?: string
+}
+```
+
+**基準**: 2つ以上のアプリで使用 → `@repo/shared`、1つのアプリのみ → アプリの `lib/actions/types.ts`
+
+## 日付の取り扱い
+
+### DB 格納
+```typescript
+// GOOD: DB insert/update には Date オブジェクト
+{
+  createdAt: new Date(),
+  updatedAt: new Date()
+}
+```
+
+### API レスポンス
+```typescript
+// GOOD: API レスポンスには ISO 文字列
+{
+  createdAt: new Date().toISOString(),
+  updatedAt: new Date().toISOString()
+}
+```
+
+## useActionState パターン (React 19)
+
+```typescript
+// GOOD: モダンな React 19 パターン
+import { useActionState } from "react"
+
+const [state, formAction, isPending] = useActionState(
+  serverAction,
+  initialState
+)
+
+<form action={formAction}>
+  {/* form fields */}
+  <button disabled={isPending}>Submit</button>
+</form>
+
+// BAD: 古い useTransition パターン
+import { useTransition } from "react"
+
+const [isPending, startTransition] = useTransition()
+
+const handleSubmit = (formData: FormData) => {
+  startTransition(async () => {
+    await serverAction(formData)
+  })
+}
+```
+
+---
+
+## よくあるアンチパターン
+
+### N+1 クエリ
+
+```typescript
+// BAD: N+1 クエリ
+for (const category of categories) {
+  const posts = await getPostsByCategory(category.id)
+}
+
+// GOOD: バッチクエリ
+const allPosts = await db.select().from(posts).where(inArray(posts.categoryId, categoryIds))
+```
+
+### エラーハンドリング不足
+
+```typescript
+// BAD
+export async function create(formData: FormData) {
+  return await db.insert(features).values({...})
+}
+
+// GOOD
+export async function create(formData: FormData): Promise<ActionResult> {
+  try {
+    const result = await db.insert(features).values({...})
+    return { success: true, data: result }
+  } catch (error) {
+    return { success: false, error: "Operation failed" }
+  }
+}
+```
+
+### ハードコード文字列（i18n 違反）
+
+```typescript
+// BAD
+<button>Save</button>
+
+// GOOD
+const t = useTranslations("common")
+<button>{t("save")}</button>
+```
+
+### 逐次クエリ（並列にすべき）
+
+```typescript
+// BAD
+const posts = await getPosts()
+const categories = await getCategories()
+const tags = await getTags()
+
+// GOOD
+const [posts, categories, tags] = await Promise.all([
+  getPosts(),
+  getCategories(),
+  getTags(),
+])
+```
+
+### setRequestLocale の欠落
+
+```typescript
+// BAD: 静的レンダリングが失敗
+export default async function Page({ params }: Props) {
+  const { locale } = await params
+  const t = await getTranslations("namespace")
+  return <h1>{t("title")}</h1>
+}
+
+// GOOD: 静的レンダリングで動作
+export default async function Page({ params }: Props) {
+  const { locale } = await params
+  setRequestLocale(locale)  // 必須
+  const t = await getTranslations("namespace")
+  return <h1>{t("title")}</h1>
+}
+```
+
+### ログイン後の Router Push
+
+```typescript
+// BAD: リダイレクトループの原因
+const handleLogout = () => {
+  authClient.signOut()
+  router.push("/login")
+}
+
+// GOOD: フルページリロード
+const handleLogout = () => {
+  authClient.signOut()
+  window.location.href = "/login"
+}
+```
+
+### エスケープなしの ILIKE
+
+```typescript
+// BAD: SQL インジェクション脆弱性
+const pattern = `%${userInput}%`
+db.select().from(posts).where(ilike(posts.title, pattern))
+
+// GOOD: 特殊文字のエスケープ
+function escapeLikePattern(query: string): string {
+  return query.replace(/[%_\\]/g, "\\$&")
+}
+const pattern = `%${escapeLikePattern(userInput)}%`
+db.select().from(posts).where(ilike(posts.title, pattern))
+```
+
+---
+
+## レビューチェックリスト
+
+- [ ] フォームデータは `parseFormData` ユーティリティでパース
+- [ ] DB トランザクションは try-catch で囲む
+- [ ] 型が適切な場所（shared vs アプリ固有）にある
+- [ ] 日付が正しい形式（DB には Date、API には ISO 文字列）
+- [ ] フォームは `useTransition` ではなく `useActionState` を使用
+- [ ] すべての Server Actions でエラーハンドリングが統一
+- [ ] コード全体で型安全性が維持
+- [ ] N+1 クエリなし（`inArray()` でバッチクエリ）
+- [ ] ハードコード UI 文字列なし（i18n 使用）
+- [ ] 独立クエリが並列（`Promise.all`）
+- [ ] Server Components で `setRequestLocale()` を呼出
+- [ ] 認証リダイレクトは `window.location.href` を使用
+- [ ] ILIKE パターンが適切にエスケープ

package/plugin/shirokuma-skills-ja/skills/reviewing-on-issue/patterns/docs-management.md

@@ -0,0 +1,95 @@
+# ドキュメント管理パターン
+
+## プロジェクトドキュメント構造
+
+| パス | 用途 |
+|------|------|
+| `docs/portal/index.html` | メインポータルページ |
+| `docs/portal/viewer.html` | Markdown ビューア |
+| `docs/portal/*.html` | ガイドページ |
+| `docs/generated/api-html/` | TypeDoc API ドキュメント |
+| `docs/generated/test-cases.md` | テストケース Markdown |
+| `docs/generated/deps/` | 依存関係グラフ |
+| `docs/*.md` | 手書きナレッジドキュメント |
+| `docs/phase*/` | フェーズ実装ドキュメント |
+
+## ドキュメント種別
+
+### 手書きナレッジドキュメント
+
+配置: `docs/*.md`（ルートレベル）
+
+| ドキュメント種別 | 用途 | 更新頻度 |
+|-----------------|------|---------|
+| パターンドキュメント | 開発パターン、ベストプラクティス | パターン変更時 |
+| 実装記録 | 機能実装履歴 | 1回限り |
+| ガイドドキュメント | ハウツーガイド | 必要に応じて |
+| トラブルシューティング | 既知の問題と修正 | 問題発見時 |
+
+### 自動生成ドキュメント
+
+配置: `docs/generated/`
+
+| ドキュメント種別 | 生成コマンド | 更新トリガー |
+|-----------------|------------|-------------|
+| API ドキュメント | `pnpm docs:api` | Server Action 変更後 |
+| テストケース | `pnpm docs:tests` | テスト変更後 |
+| 依存関係グラフ | `pnpm docs:deps` | 依存関係変更後 |
+| DB スキーマ | `pnpm docs:dbml` | スキーマ変更後 |
+
+## ドキュメントレビューチェックリスト
+
+### 内容の正確性
+
+- [ ] 技術情報が現在のコードベースと一致
+- [ ] コード例が実行可能で正しい
+- [ ] バージョン番号が最新
+- [ ] コマンド例が現在のセットアップで動作
+
+### ステータス追跡
+
+- [ ] 実装状況が実態を反映
+- [ ] 「最終更新日」が最新
+- [ ] 「次のステップ」がまだ有効
+- [ ] 完了項目にマークあり
+
+### 構造の品質
+
+- [ ] 明確なタイトルと要約あり
+- [ ] 適切なセクションで整理
+- [ ] コード例にシンタックスハイライトあり
+- [ ] テーブルが適切にフォーマット済み
+
+## よくあるドキュメントの問題
+
+### 古いステータス
+
+```markdown
+## Implementation Status
+
+- 完了: ユーティリティ作成
+- 完了: テスト追加
+- 進行中: Server Actions のリファクタ  ← 完了しているか確認
+```
+
+**修正**: 実装完了時にステータスを更新。
+
+### バージョン不一致
+
+```markdown
+**Next.js Version**: 16.0.4  ← package.json と確認
+```
+
+**修正**: `package.json` とバージョン番号を同期。
+
+### デッドリンク
+
+**修正**: すべての内部リンクが既存ファイルを指しているか検証。
+
+## ベストプラクティス
+
+1. **即座に更新**: 実装変更後すぐにドキュメント更新
+2. **唯一の真実の源**: 正式バージョンは CLAUDE.md を参照
+3. **ステータス追跡**: 一貫したステータスマーカーを使用
+4. **日付スタンプ**: 実装ドキュメントに「最終更新日」を含む
+5. **ナレッジへのリンク**: 複雑なパターンはナレッジファイルに記載

package/plugin/shirokuma-skills-ja/skills/reviewing-on-issue/patterns/drizzle-orm.md

@@ -0,0 +1,314 @@
+# Drizzle ORM パターン
+
+## スキーマファイルの整理（大規模プロジェクト）
+
+大規模プロジェクトではドメイン別にファイルを分割する：
+
+| ファイル | 用途 |
+|---------|------|
+| `schema/index.ts` | バレルエクスポート + 全リレーション |
+| `schema/common.ts` | 共通カラム定義 |
+| `schema/auth.ts` | users, sessions, accounts, verifications |
+| `schema/content.ts` | posts, categories, tags, post_tags |
+| `schema/comments.ts` | comments |
+| `index.ts` | DBクライアント + スキーマ再エクスポート |
+| `constants.ts` | 共通定数 |
+
+### common.ts - 再利用可能なカラム
+
+```typescript
+import { timestamp } from "drizzle-orm/pg-core"
+
+export const timestamps = {
+  createdAt: timestamp("created_at").notNull().defaultNow(),
+  updatedAt: timestamp("updated_at").notNull().defaultNow(),
+}
+```
+
+### auth.ts - ドメインテーブル
+
+```typescript
+import { pgTable, uuid, varchar, timestamp, text, boolean } from "drizzle-orm/pg-core"
+import { timestamps } from "./common"
+
+export const users = pgTable("user", {
+  id: uuid("id").defaultRandom().primaryKey(),
+  email: varchar("email", { length: 255 }).notNull().unique(),
+  name: varchar("name", { length: 255 }),
+  role: varchar("role", { length: 20 }).notNull().default("user"),
+  emailVerified: timestamp("email_verified"),
+  ...timestamps,
+})
+
+export const sessions = pgTable("session", {
+  id: uuid("id").defaultRandom().primaryKey(),
+  userId: uuid("user_id").notNull().references(() => users.id, { onDelete: "cascade" }),
+  token: varchar("token", { length: 255 }).notNull().unique(),
+  expiresAt: timestamp("expires_at").notNull(),
+  ...timestamps,
+})
+
+// accounts, verifications テーブル...
+```
+
+### schema/index.ts - バレル + リレーション
+
+```typescript
+// 全テーブルを再エクスポート
+export * from "./common"
+export * from "./auth"
+export * from "./content"
+export * from "./comments"
+
+// 循環依存を避けるためリレーションは1箇所で定義
+import { relations } from "drizzle-orm"
+import { users, sessions, accounts } from "./auth"
+import { posts, categories, tags, postTags } from "./content"
+import { comments } from "./comments"
+
+export const usersRelations = relations(users, ({ many }) => ({
+  posts: many(posts),
+  comments: many(comments),
+  sessions: many(sessions),
+}))
+
+export const postsRelations = relations(posts, ({ one, many }) => ({
+  author: one(users, { fields: [posts.authorId], references: [users.id] }),
+  category: one(categories, { fields: [posts.categoryId], references: [categories.id] }),
+  comments: many(comments),
+  postTags: many(postTags),
+}))
+
+// ... その他のリレーション
+```
+
+### drizzle.config.ts
+
+```typescript
+export default defineConfig({
+  dialect: "postgresql",
+  schema: "./src/schema",  // 全ファイルを含むディレクトリパス
+  out: "./drizzle",
+})
+```
+
+### ファイル分割の理由
+
+- ドメイン境界が明確（Auth / Content / Comments）
+- チーム開発でのマージコンフリクト軽減
+- 関連テーブルの検索・修正が容易
+- プロジェクト成長時のスケーラビリティ（20テーブル以上）
+
+### 重要ルール
+
+1. リレーションは `schema/index.ts` でのみ定義（循環 import 回避）
+2. バレルファイル経由で全エクスポート
+3. 共通パターン（timestamps, soft delete）は `common.ts` に
+4. 20テーブル / 500行未満のプロジェクトは単一ファイルで可
+
+## リレーション付きクエリ
+
+```typescript
+const postsWithAuthor = await db
+  .select({
+    id: posts.id,
+    title: posts.title,
+    authorName: users.name,
+  })
+  .from(posts)
+  .leftJoin(users, eq(posts.authorId, users.id))
+  .where(eq(posts.status, "published"))
+```
+
+## ページネーション
+
+```typescript
+const PAGE_SIZE = 20
+
+export async function getPaginated(page: number = 1) {
+  const offset = (page - 1) * PAGE_SIZE
+
+  const [items, countResult] = await Promise.all([
+    db.select().from(features).orderBy(desc(features.createdAt)).limit(PAGE_SIZE).offset(offset),
+    db.select({ count: count() }).from(features),
+  ])
+
+  return {
+    items,
+    pagination: {
+      page,
+      pageSize: PAGE_SIZE,
+      total: countResult[0]?.count ?? 0,
+      totalPages: Math.ceil((countResult[0]?.count ?? 0) / PAGE_SIZE),
+    },
+  }
+}
+```
+
+## ILIKE 検索（ワイルドカードエスケープ）
+
+```typescript
+function escapeLikePattern(query: string): string {
+  return query.replace(/[%_\\]/g, "\\$&")
+}
+
+const pattern = `%${escapeLikePattern(userInput)}%`
+db.select().from(posts).where(ilike(posts.title, pattern))
+```
+
+## アンチパターン
+
+### N+1 クエリ
+
+```typescript
+// Bad: N+1 クエリ（アイテムごとに1クエリ）
+for (const category of categories) {
+  const posts = await getPostsByCategory(category.id)
+}
+
+// Good: inArray() でバッチクエリ
+const allPosts = await db
+  .select()
+  .from(posts)
+  .where(inArray(posts.categoryId, categoryIds))
+
+const postsByCategory = allPosts.reduce((acc, post) => {
+  (acc[post.categoryId] ||= []).push(post)
+  return acc
+}, {})
+```
+
+### マスアサインメント
+
+```typescript
+// Bad: スプレッドで意図しないフィールドを許可
+await db.update(posts).set({ ...formData })
+
+// Good: バリデーション済みフィールドのみ明示的に指定
+const validated = Schema.parse(formData)
+await db.update(posts).set({
+  title: validated.title,
+  content: validated.content,
+})
+```
+
+## マイグレーション戦略
+
+- **開発**: `drizzle-kit push` で高速イテレーション
+- **本番**: `drizzle-kit generate` + `migrate` でバージョン管理されたマイグレーション
+
+## 非推奨 API
+
+- `InferModel` -> `InferSelectModel` と `InferInsertModel` を使用
+
+## v1.0 (beta) 破壊的変更
+
+### マイグレーションフォルダ構造
+
+`journal.json` が廃止され、SQL ファイルとスナップショットが個別フォルダにグループ化された。`drizzle-kit drop` コマンドも廃止。
+
+```bash
+# 既存フォルダを新フォーマットに変換
+npx drizzle-kit up
+```
+
+### バリデータパッケージの統合
+
+| 旧 import | 新 import |
+|-----------|-----------|
+| `drizzle-zod` | `drizzle-orm/zod` |
+| `drizzle-valibot` | `drizzle-orm/valibot` |
+| `drizzle-typebox` | `drizzle-orm/typebox` |
+| `drizzle-arktype` | `drizzle-orm/arktype` |
+
+### PostgreSQL Array
+
+`.array()` はチェーン不可に。多次元配列は `.array('[][]')` を使用。
+
+### Relational Query Builder v2 (RQBv2)
+
+RQBv1 から RQBv2 への移行が必要。`drizzle()` 初期化時に全テーブルとリレーションを提供し、`db.query` API を使用する。
+
+```typescript
+// v1: relations() で定義
+import { relations } from "drizzle-orm"
+
+// v2: defineRelations() で定義（推奨）
+// 詳細: orm.drizzle.team/docs/relations-v1-v2
+```
+
+## 型安全性
+
+```typescript
+// スキーマから型を定義
+type Post = InferSelectModel<typeof posts>
+type NewPost = InferInsertModel<typeof posts>
+
+// 関数で使用
+async function createPost(data: NewPost): Promise<Post> {
+  const [result] = await db.insert(posts).values(data).returning()
+  return result
+}
+```
+
+## スキーマドキュメント（shirokuma-docs）
+
+カラムとインデックスの説明はインラインJSDocコメントで記述する。shirokuma-docsが自動抽出してドキュメント化。
+
+### カラムコメント
+
+カラム定義の直前にJSDocコメントを配置：
+
+```typescript
+export const organizations = pgTable("organizations", {
+  /** 組織ID（UUID） */
+  id,
+  /** 組織名（表示名） */
+  name: text("name").notNull(),
+  /** 組織スラッグ（URLに使用、一意制約あり） */
+  slug: text("slug").notNull().unique(),
+  /** 組織の説明文 */
+  description: text("description"),
+  ...timestamps,
+})
+```
+
+### インデックスコメント
+
+インデックス定義の直前にJSDocコメントを配置：
+
+```typescript
+export const organizationMembers = pgTable(
+  "organization_members",
+  {
+    /** メンバーシップID */
+    id,
+    /** 組織ID */
+    organizationId: uuid("organization_id").notNull(),
+    /** ユーザーID */
+    userId: text("user_id").notNull(),
+    ...timestamps,
+  },
+  (table) => [
+    /** 組織とユーザーの組み合わせで一意制約（重複メンバーシップを防止） */
+    uniqueIndex("org_members_org_user_idx").on(table.organizationId, table.userId),
+  ]
+)
+```
+
+### 使用しないこと
+
+`@columns` や `@indexes` JSDocタグは使用しない（インラインコメントと重複するため）：
+
+```typescript
+// NG - これらのタグは使わない
+/**
+ * @columns
+ *   - id: 組織ID
+ *   - name: 組織名
+ * @indexes
+ *   - org_slug_idx: スラッグの一意インデックス
+ */
+
+// OK - 上記のようにインラインコメントを使用
+```