shirokuma-docs 0.1.0-alpha.1

package/plugin/shirokuma-skills-ja/rules/github/branch-workflow.md

@@ -0,0 +1,64 @@
+<!-- managed-by: shirokuma-docs@0.1.0 -->
+
+# ブランチワークフロー
+
+## ブランチモデル
+
+| ブランチ | 役割 | 分岐元 | マージ先 |
+|----------|------|--------|----------|
+| `main` | 本番リリース（タグ付け） | — | — |
+| `develop` | 統合（PR デフォルト） | `main`（初期） | `main`（リリース PR） |
+| `feat/*`, `fix/*`, `chore/*`, `docs/*` | 日常作業 | `develop` | `develop`（PR） |
+| `hotfix/*` | 緊急本番修正 | `main` | `main`（PR）→ `develop` にチェリーピック |
+
+- `develop` = デフォルトブランチ（PR ターゲット）
+- `develop` や `main` への直接コミット禁止
+
+## ブランチ命名
+
+```
+{type}/{issue-number}-{slug}
+```
+
+- **type**: Issue の Type から決定（Feature→`feat`, Bug→`fix`, Chore/Research→`chore`, Docs→`docs`）
+- **slug**: Issue タイトルから生成、小文字ケバブケース、最大40文字、英語のみ
+
+## 日常ワークフロー
+
+1. `develop` から分岐: `git checkout develop && git pull && git checkout -b {type}/{n}-{slug}`
+2. コミット（`git-commit-style` ルール参照）
+3. プッシュ + PR 作成: `git push -u origin {branch}` → `gh pr create --base develop`
+4. レビュー → スカッシュマージ → ブランチ削除
+
+## ホットフィックス
+
+`main` から分岐、`main` への PR、マージ後に `develop` へチェリーピック。
+
+## リリース
+
+`develop` → `main` への PR → マージ後にタグ: `v{major}.{minor}.{patch}`
+
+## ルール
+
+1. 常に `develop` から分岐（最新化してから）
+2. 1 Issue 1ブランチ
+3. セッション終了前にプッシュ
+4. マージには PR が必要（直接プッシュ禁止）
+5. **ユーザー承認なしにマージしない**（PreToolUse フックで強制）
+6. マージ後にブランチ削除
+
+## 破壊的コマンド保護
+
+PreToolUse フックが以下をブロック: `gh pr merge`, `git push --force`, `git reset --hard`, `git checkout .`, `git restore .`, `git clean -f`, `git branch -D`
+
+- ブロック時はユーザーに承認を求めること
+- プロジェクトオーバーライド: `.claude/shirokuma-hooks.json` で `{"disabled": ["rule-id"]}`
+
+## エッジケース
+
+| 状況 | アクション |
+|------|----------|
+| すでにフィーチャーブランチ | 続行 |
+| Issue のブランチが既存 | 切り替え |
+| develop に未コミット変更 | スタッシュ後にブランチ作成 |
+| develop とコンフリクト | PR 前にリベース |

package/plugin/shirokuma-skills-ja/rules/github/discussions-usage.md

@@ -0,0 +1,129 @@
+# GitHub Discussions 活用ガイド
+
+## 目的
+
+Discussions は人間向けの知識を蓄積し、Rules は AI 向けの抽出情報を格納します。
+
+| レイヤー | 対象 | 言語 | 内容 |
+|---------|------|------|------|
+| Discussions | 人間 | 日本語 | コンテキスト、根拠、詳細 |
+| Rules/Skills | AI | 英語 | 簡潔なパターン、コマンド |
+
+## カテゴリ
+
+| カテゴリ | 用途 |
+|---------|------|
+| Handovers | セッション終了時 - `/ending-session` で作成 |
+| ADR | 確定したアーキテクチャ決定 |
+| Knowledge | 確認されたパターン・解決策 |
+| Research | 調査が必要な事項 |
+
+## ワークフロー
+
+```
+Research → ADR（決定の場合）→ Knowledge → Rule 抽出
+```
+
+### Discussion → Issue フロー
+
+アイデアや提案は、実装が決定されるまで Discussions に置きます。
+
+```
+Discussion（アイデア）→ 実装決定 → Issue（Backlog）→ Ready → In Progress
+```
+
+| アクション | タイミング |
+|-----------|-----------|
+| Discussion を作成 | 新しいアイデア、提案、調査トピック |
+| Issue に変換 | チームが実装を決定 |
+| Discussion のまま | アイデアが却下、延期、または情報提供のみ |
+
+未決定のアイデアで Issue を作成しないでください。まず Discussions で探索と意思決定を行います。
+
+## Knowledge → Rule 抽出ワークフロー
+
+パターンや解決策が実践で確認されたら、AI 向けの Rule として抽出する。
+
+```
+1. 発見: 作業中にパターンを発見（コードレビュー、デバッグ、実装）
+2. Knowledge Discussion: Knowledge カテゴリにコンテキストと根拠を記録
+3. 検証: 2回以上のセッションでパターンの有効性を確認
+4. Rule 提案: Knowledge Discussion から簡潔で実行可能なルールを抽出
+5. Rule 作成: managing-rules スキルでルールファイルを作成
+6. 相互参照: ルール内に Discussion # リンクをコメントで追加
+```
+
+| ステップ | アクション | 出力 |
+|---------|----------|------|
+| 発見 | 繰り返しパターンを特定 | メモまたはコメント |
+| 記録 | Knowledge Discussion を作成 | Discussion #{N} |
+| 検証 | 異なるコンテキストでの有効性を確認 | Discussion 更新 |
+| 抽出 | AI が読める形式のルールに蒸留 | Rule `.md` ファイル |
+| リンク | ルール内にソース Discussion を参照 | `<!-- Source: Discussion #{N} -->` |
+
+**Discussion ステップをスキップしてよい場合**: 自明なパターンのみ（例: タイポ修正、明白な命名規約）。「なぜ」が重要なら先に Discussion を書く。
+
+## 既存 Discussion の検索
+
+新規 Discussion 作成前に、既存のものを検索して重複を避ける。
+
+```bash
+# キーワード検索
+shirokuma-docs discussions search "{keyword}"
+
+# カテゴリでフィルタ
+shirokuma-docs discussions list --category Knowledge
+shirokuma-docs discussions list --category Research
+shirokuma-docs discussions list --category ADR
+
+# 最近の引き継ぎ（セッションコンテキスト用）
+shirokuma-docs discussions list --category Handovers --limit 5
+```
+
+**検索するタイミング**:
+- 新しいセッション開始時（最近の Handovers を確認）
+- Knowledge Discussion 作成前（既存のカバレッジを確認）
+- 調査開始前（Research カテゴリの先行作業を確認）
+- パターン調査時（Knowledge で関連する知見を検索）
+
+## 相互参照
+
+- Discussions は Issues と番号空間を共有（#1, #2, ...）
+- コミットで参照: "See Discussion #30"
+- トラッキングのため Projects に追加
+
+## Auto Memory との使い分け
+
+Claude Code の auto memory に詳細情報を書かない。memory はポインタのみ、詳細は Discussion に記録する。`memory-operations` ルール参照。
+
+## AI の行動指針
+
+1. **検索**: 新規作成前に既存の Discussions を確認
+2. **読む**: リサーチ時にコンテキストとして Discussions を確認
+3. **書く**: 重要な知見について Discussions を作成
+4. **抽出**: パターンが確認されたら Rule を提案
+5. **参照**: Rule コメントに Discussion # をリンク
+
+## 本文メンテナンス
+
+Discussion 本文は常に最新の統合版を維持する（`project-items` ルールの「アイテム本文メンテナンス」参照）。
+
+- コメントで追加調査・訂正・新知見を投稿した場合、**本文も即座に統合版として更新する**
+- コメントは議論の経緯・履歴として残す
+- 本文が「この Discussion の結論を知りたければここだけ読めばいい」状態を維持する
+
+```bash
+shirokuma-docs discussions update {number} --body "$(cat <<'EOF'
+{更新内容}
+EOF
+)"
+```
+
+## タイトル形式
+
+| カテゴリ | 形式 |
+|---------|------|
+| Handovers | `YYYY-MM-DD - {サマリー}` |
+| ADR | `ADR-{NNN}: {タイトル}` |
+| Knowledge | `{トピック名}` |
+| Research | `[Research] {トピック}` |

package/plugin/shirokuma-skills-ja/rules/github/output-language.md

@@ -0,0 +1,14 @@
+# GitHub 出力言語
+
+## ルール
+
+GitHub に書き込む全てのコンテンツ（Issues, PR, Discussions のコメント・本文）は**日本語**で記述する。
+
+| 要素 | 言語 |
+|------|------|
+| Issue / PR / Discussion の本文・コメント | 日本語 |
+| PR タイトル（プレフィックス後） | 日本語 |
+| コミットメッセージ（プレフィックス後） | 日本語 |
+| Conventional commit プレフィックス (`feat:`, `fix:` 等) | English |
+| コード / 変数名 | English |
+| ラベル名 | English |

package/plugin/shirokuma-skills-ja/rules/github/pr-review-response.md

@@ -0,0 +1,37 @@
+# PR レビューレスポンス
+
+## レビューコメント受領時
+
+1. すべてのレビュースレッドを取得: `shirokuma-docs issues pr-comments <PR#>`
+2. 各**未解決**スレッドについて、レスポンスタイプを判断：
+
+### コード修正が必要
+
+1. コードを修正
+2. コミットしてプッシュ
+3. コミットを参照して返信: `shirokuma-docs issues pr-reply <PR#> --reply-to <database_id> --body "Fixed in <hash>"`
+4. 解決: `shirokuma-docs issues resolve <PR#> --thread-id <PRRT_id>`
+
+### 質問またはディスカッション
+
+1. 説明を返信
+2. スレッドを解決
+
+### 意見の相違
+
+1. 懸念事項とトレードオフを説明して返信
+2. 解決**しない** — レビュアーに判断を委ねる
+
+## ルール
+
+1. **返信と解決はセット** - すべての返信には解決が続くべき（レビュアーの入力待ちの場合を除く）
+2. **全スレッドを処理してからユーザーに報告** - スレッド間でユーザーに質問しない
+3. **正しい ID を使用** - `--reply-to` は数値の `database_id`、`--thread-id` は GraphQL の `PRRT_` ID（どちらも `pr-comments` の出力から取得）
+
+## エッジケース
+
+| 状況 | アクション |
+|------|----------|
+| スレッドがすでに解決済み | スキップ |
+| 古いコメント（コードが変更済み） | フィードバックがまだ有効なら返信、関連コミットを参照 |
+| レビュアーが再レビューを要求 | 返信するがスレッドは開いたまま |

package/plugin/shirokuma-skills-ja/rules/github/project-items.md

@@ -0,0 +1,164 @@
+# プロジェクトアイテムルール
+
+## 必須フィールド
+
+| フィールド | 必須 | オプション |
+|-----------|------|-----------|
+| Status | はい | 下記ワークフロー参照 |
+| Priority | はい | Critical / High / Medium / Low |
+| Type | はい | Feature / Bug / Chore / Docs / Research |
+| Size | 推奨 | XS / S / M / L / XL |
+
+## ステータスワークフロー
+
+```mermaid
+graph LR
+  Icebox --> Backlog --> Planning --> SpecReview[Spec Review]
+  SpecReview --> InProgress[In Progress] --> Review --> Testing --> Done --> Released
+  InProgress <--> Pending["Pending（ブロック中）"]
+  Review <--> Pending
+  Backlog <--> Pending
+  Done -.-> NotPlanned["Not Planned（見送り）"]
+```
+
+アイデアは Issue ではなく **Discussions** から始める。実装決定後に Issue (Backlog) へ。
+
+## ステータス更新トリガー
+
+| トリガー | アクション | 責任者 | コマンド |
+|---------|----------|--------|---------|
+| 計画策定開始 | → Planning | `planning-on-issue` | `issues update {n} --field-status "Planning"` |
+| 計画策定完了 | → Spec Review | `planning-on-issue` | `issues update {n} --field-status "Spec Review"` |
+| ユーザーが計画承認、実装開始 | → In Progress + ブランチ | `working-on-issue` | `issues update {n} --field-status "In Progress"` |
+| PR作成 | → Review | `creating-pr-on-issue` | `issues update {n} --field-status "Review"` |
+| マージ | → Done | `committing-on-issue` (via `issues merge`) | 自動更新 |
+| ブロック | → Pending | 手動 | `issues update {n} --field-status "Pending"` + 理由 |
+| 完了（PR不要） | → Done | `ending-session` | `session end --done {n}` |
+| キャンセル | → Not Planned | `issues cancel` | `issues cancel {n}` |
+| セッション終了 | → Review or Done | `ending-session`（セーフティネット） | `session end --review/--done {n}` |
+
+### Planning の運用
+
+`planning-on-issue` スキルが計画を開始するとき、Backlog → Planning に遷移する。
+
+- **目的**: 計画策定中であることの可視化、計画開始タイムスタンプの記録
+- **入口**: `planning-on-issue` が Issue を取得後、計画開始時に設定
+- **出口**: 計画完了後 → Spec Review（`planning-on-issue` が設定）
+- **pre-work ステータス**: `WORK_STARTED_STATUSES` に含まれない（Spec Review と同様）
+
+### Spec Review の運用
+
+`planning-on-issue` スキルが計画を Issue 本文に書いた後、Planning → Spec Review に移行する。
+
+- **目的**: ユーザーが計画を確認・承認するゲート
+- **入口**: `planning-on-issue` が `## 計画` セクションを追記後に設定
+- **出口**: ユーザーが承認し `working-on-issue` で実装を開始 → In Progress
+- **適用**: 全 Issue で計画を実施（深さは内容に応じて軽量/標準/詳細）
+
+### ルール
+
+1. **同時に In Progress は1つ**
+2. **Issue ごとにブランチ**（`branch-workflow` 参照）
+3. **イベント駆動**: Status 変更はイベント発生時に即座に実行する（`creating-pr-on-issue` が Review、`issues merge` が Done）
+4. **セッション終了時**に `ending-session` が取りこぼしを補完（セーフティネット）
+5. **Pending は理由必須**
+6. **冪等性**: 既に正しい Status なら更新をスキップ（エラーにしない）
+
+## ビルトイン自動化
+
+推奨ワークフロー（GitHub UI で有効化、API 未対応）:
+- **Item closed** → Done
+- **Pull request merged** → Done
+
+CLI と冪等に協調動作。確認: `shirokuma-docs projects workflows`
+
+**注意**: 「Item closed → Done」自動化が有効な場合、`issues cancel`（Not Planned 設定）と競合する可能性がある。CLI は close 後に Status を Not Planned に設定するため、通常は CLI の更新が優先されるが、タイミングによっては自動化が上書きする場合がある。`session check --fix` で整合性を検出・修正可能。
+
+## ラベル
+
+Type を補完し、**どこ**に影響するかを示す。`area:` プレフィックス使用。Type と重複するラベルは作成しない。
+
+## アイテム本文メンテナンス（Issues / Discussions / PRs 共通）
+
+**本文はソースオブトゥルース。** コメントは議論の経緯・履歴として残し、本文は常に最新の統合版を維持する。「このアイテムの最新状態を知りたければ本文だけ読めばいい」状態を保つこと。
+
+### 更新タイミング
+
+| トリガー | アクション |
+|---------|----------|
+| コメントで新しい知見・訂正を追加 | 本文に統合 |
+| 調査結果をコメントで投稿 | 本文の該当セクションに反映 |
+| 要件がコメントで変更 | 本文のタスク・成果物セクションを更新 |
+| 決定事項がコメントで発生 | 本文に記録 |
+| コメント3件以上蓄積 | 本文に統合 |
+
+### 更新方法
+
+```bash
+# Issues
+shirokuma-docs issues update {number} --body "$(cat <<'EOF'
+{更新内容}
+EOF
+)"
+
+# Discussions
+shirokuma-docs discussions update {number} --body "$(cat <<'EOF'
+{更新内容}
+EOF
+)"
+```
+
+### ワークフロー順序（コメントファースト）
+
+本文を更新する際は、必ず以下の順序で行う:
+
+1. **コメントを投稿** — 変更内容・知見・訂正をコメントとして記録する
+2. **本文に統合** — コメントの内容を本文の該当セクションに反映する
+
+この順序により、コメント履歴に「何を変えたか」の経緯が残り、AI の判断ミスやハルシネーションの検出・改善が可能になる。
+
+**禁止**: 本文を直接更新してからコメントを後付けする（逆順）。コメントなしで本文を更新する。
+
+### 実質的遵守
+
+形式的にコメント→本文の順序を守るだけでは不十分。コメントが**作業の一次記録**として独立した価値を持つ必要がある。
+
+**判定ヒューリスティック**: コメントを削除しても、本文にない情報が失われないなら、そのコメントは実質的ではない。
+
+| 悪い例（形式的遵守） | 良い例（実質的遵守） |
+|---------------------|---------------------|
+| 「計画を策定しました。詳細は本文参照。」 | 「アプローチ A を選定。B 案（〇〇）も検討したが、△△の理由で却下。」 |
+| 「Issue 本文を更新しました。」 | 「調査の結果、X モジュールにも影響があることが判明。タスクに追加。」 |
+| 「レビュー結果を反映しました。」 | 「レビューで N 件の問題を検出: {具体的な所見の要約}」 |
+
+**コメントが一次記録であるべき内容**:
+- 判断の根拠・検討した代替案
+- 調査で発見した事実
+- レビュー所見の要約
+- 要件変更の理由
+
+**本文への統合時**: コメントの内容を構造化して該当セクションにマージする。コメントはそのまま履歴として残る。
+
+### ガイドライン
+
+1. **構造保持** — 元のテンプレートセクションを維持
+2. **タスクチェック更新** — 完了項目をチェック、新規タスクを追加
+3. **要約して重複排除** — コメントスレッドを簡潔に統合
+4. **コメントファースト遵守** — 本文更新前に必ずコメントを投稿する（ワークフロー順序セクション参照）
+
+## 本文テンプレート
+
+```markdown
+## 概要
+{内容}
+
+## タスク
+- [ ] タスク 1
+
+## 成果物
+{"完了" の定義}
+```
+
+## アイテム作成
+
+全必須フィールドを即時設定。XL は分割。デフォルト Status は Backlog（`--field-status` でオーバーライド可）。

package/plugin/shirokuma-skills-ja/rules/memory-operations.md

@@ -0,0 +1,38 @@
+# メモリ運用ルール
+
+## 原則
+
+**メモリはポインタとワーキングコンテキストのみ。**
+
+## メモリに書くもの
+
+| 種類 | 例 |
+|------|------|
+| GitHub への参照ポインタ | `Discussion #343 参照` `Issue #342` |
+| ワーキングコンテキスト | テストコマンド、スキル数などの速引き |
+
+## メモリに書かないもの → GitHub へ
+
+| 種類 | 置き場所 |
+|------|---------|
+| 調査結果 | Discussion (Research) |
+| アイディア・構想 | Discussion |
+| 設計決定 | Discussion (ADR) |
+| 実装タスク | Issue |
+| パターン・知見 | Discussion (Knowledge) → Rule 抽出 |
+
+詳細は `discussions-usage` ルール参照。
+
+## 制約
+
+1. **CLAUDE.md やルールと重複する情報はメモリに書かない** — 情報源は一箇所に
+2. **トピック別ファイルも簡素に** — GitHub 参照ポインタのみ
+
+## 設定ファイル内の指示語
+
+設定ファイルは全て同じコンテキストに並列で読み込まれる。相対指示語を使うとどのファイルの指示か区別できない。
+
+| NG | OK |
+|----|----|
+| 「ここ」「この」「このファイル」 | ファイル名やセクション名で明示 |
+| 「上記のルール」 | `branch-workflow ルール` |

package/plugin/shirokuma-skills-ja/rules/nextjs/known-issues.md

@@ -0,0 +1,59 @@
+# 既知の問題と CVE
+
+## 重大な CVE
+
+### CVE-2025-29927 (Next.js)
+
+**深刻度**: Critical (9.1)
+**影響**: Next.js < 15.2.3
+**問題**: `x-middleware-subrequest` ヘッダーによるミドルウェア認証バイパス
+
+**緩和策**（アップグレードできない場合）:
+```nginx
+if ($http_x_middleware_subrequest) {
+    return 403;
+}
+proxy_set_header x-middleware-subrequest "";
+```
+
+## フレームワークの問題
+
+### Next.js 16
+
+| 問題 | 修正 |
+|------|------|
+| 非同期 params エラー | `const { slug } = await params` |
+| Node.js 18 のサポート終了 | Node.js 20.9.0+ にアップグレード |
+
+### React 19
+
+| 問題 | 修正 |
+|------|------|
+| ハイドレーション不一致 | mounted ステートパターンを使用 |
+| ref を prop として渡す（非推奨） | `element.props.ref` を使用 |
+
+### Tailwind CSS v4
+
+| 問題 | 修正 |
+|------|------|
+| CSS 変数構文 | `var()` を使用: `w-[var(--width)]` |
+| @property の継承 | `@theme inline` を使用 |
+
+### Better Auth
+
+| 問題 | 修正 |
+|------|------|
+| ログインリダイレクトループ | `window.location.href` を使用 |
+| セッションにロールがない | ロールをデータベースから照会 |
+
+## バージョン要件
+
+- **Node.js**: 20.9.0+
+- **TypeScript**: 5.1.0+
+- **Safari**: 16.4+（Tailwind v4）
+
+## セキュリティ要件
+
+- **BETTER_AUTH_SECRET**: 32文字以上
+- **bcrypt ラウンド数**: 12+
+- **レート制限**: 5回 / 15分（本番環境）

package/plugin/shirokuma-skills-ja/rules/nextjs/lib-structure.md

@@ -0,0 +1,48 @@
+---
+paths:
+  - "lib/**/*.ts"
+  - "lib/**/*.tsx"
+  - "**/lib/**/*.ts"
+  - "**/lib/**/*.tsx"
+---
+
+# lib/ ディレクトリ構造ルール
+
+## 必須構造
+
+```
+lib/
+├── actions/           # Server Actions
+│   ├── crud/          # 単一テーブル CRUD
+│   └── domain/        # 複数テーブルのビジネスロジック
+├── auth/              # 認証
+├── context/           # React Context
+├── hooks/             # カスタムフック
+├── utils/             # ユーティリティ関数
+└── validations/       # Zod スキーマ
+```
+
+## 重要ルール
+
+1. **lib/ 直下にファイルを置かない**
+   ```
+   lib/auth/index.ts  ← OK
+   lib/auth.ts        ← NG
+   ```
+
+2. **再エクスポートに index.ts を使用**
+   ```typescript
+   export { auth } from "./config"
+   export { verifyAdmin } from "./utils"
+   ```
+
+3. **`export *` を避ける**
+   - 名前衝突によるビルドエラーの原因
+   - 明示的な再エクスポートを使用
+
+## Server Actions 構造
+
+| ディレクトリ | タイプ | 特徴 |
+|-------------|--------|------|
+| `lib/actions/crud/` | CRUD | 単一テーブル、標準操作 |
+| `lib/actions/domain/` | ドメイン | 複数テーブル、ビジネスワークフロー |

package/plugin/shirokuma-skills-ja/rules/nextjs/radix-ui-hydration.md

@@ -0,0 +1,30 @@
+---
+paths:
+  - "components/**/*.tsx"
+  - "**/components/**/*.tsx"
+---
+
+# Radix UI ハイドレーションパターン
+
+## 問題
+
+Radix UI は SSR と CSR で異なるユニーク ID を生成し、ハイドレーション不一致を引き起こす。
+
+影響: DropdownMenu, Select, Dialog, Popover, Collapsible, Accordion, Tooltip。
+
+## 解決策: mounted ステートパターン
+
+```tsx
+const [mounted, setMounted] = useState(false)
+useEffect(() => { setMounted(true) }, [])
+
+if (!mounted) return <PlaceholderWithoutRadixUI />
+return <ComponentWithRadixUI />
+```
+
+## ルール
+
+- Client Component 内のすべての Radix UI コンポーネントに `mounted` パターンを使用
+- SSR プレースホルダーはフルコンポーネントのビジュアルレイアウトと一致させる
+- 利用可能なら `useMounted()` フックを優先（`hooks/use-mounted.ts`）
+- 回避策として `suppressHydrationWarning` を絶対に使わない

package/plugin/shirokuma-skills-ja/rules/nextjs/server-actions.md

@@ -0,0 +1,50 @@
+---
+paths:
+  - "lib/actions/**/*.ts"
+  - "**/lib/actions/**/*.ts"
+  - "**/actions.ts"
+---
+
+# Server Actions 規約
+
+## 必須順序
+
+1. **認証チェック**
+2. **CSRF 検証**（ミューテーションのみ）
+3. **Zod バリデーション**
+4. **ビジネスロジック**
+5. **パス再検証**
+
+## テンプレート
+
+```typescript
+"use server"
+
+export async function createResource(formData: FormData): Promise<ActionResult> {
+  // 1. Auth
+  const { user } = await auth()
+  if (!user) return { error: "Unauthorized" }
+
+  // 2. CSRF (mutations only)
+  await verifyCsrfToken(formData)
+
+  // 3. Validation
+  const validated = schema.safeParse(Object.fromEntries(formData))
+  if (!validated.success) return { error: validated.error.message }
+
+  // 4. Business logic
+  const result = await db.insert(table).values(validated.data)
+
+  // 5. Revalidate
+  revalidatePath("/resources")
+  return { data: result }
+}
+```
+
+## セキュリティチェックリスト
+
+- [ ] DB 操作前に Auth チェック
+- [ ] ミューテーションで CSRF トークン検証
+- [ ] Zod で入力バリデーション
+- [ ] 更新/削除前に所有権検証
+- [ ] 破壊的操作にレート制限

package/plugin/shirokuma-skills-ja/rules/nextjs/tailwind-v4.md

@@ -0,0 +1,43 @@
+---
+paths:
+  - "**/*.css"
+  - "components/ui/**/*.tsx"
+  - "**/components/ui/**/*.tsx"
+---
+
+# Tailwind CSS v4 + shadcn/ui
+
+## CSS 変数構文
+
+```tsx
+// NG: Tailwind v3 構文（v4 では壊れる）
+className="bg-[--sidebar-background]"
+
+// OK: Tailwind v4 構文
+className="bg-[var(--sidebar-background)]"
+```
+
+shadcn/ui コンポーネント追加後：
+```bash
+npx shadcn@canary add <component> -y
+# CSS 変数構文を修正: [--var] → [var(--var)]
+```
+
+## 本番環境のみの問題
+
+CSS 変数は開発環境では動くが、本番ビルドで壊れる場合がある。
+
+修正: `@property` や `:root` の代わりに `@theme inline` を使用：
+```css
+@theme inline {
+  --sidebar-width: 16rem;
+  --sidebar-background: 0 0% 100%;
+}
+```
+
+## 検証
+
+```bash
+grep -r "\[--" components/ui/  # v3 構文を検索
+pnpm build  # 本番ビルドをテスト
+```