shirokuma-docs 0.1.0-alpha.1

package/plugin/shirokuma-skills-ja/skills/claude-config-reviewing/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: claude-config-reviewing
+description: Claude Code 設定ファイル（skills、rules、agents、output-styles、plugins）の品質・一貫性・Anthropic ベストプラクティス準拠をレビューする。.claude/ 設定の作成・更新後にプロアクティブに使用すること。トリガー: "設定レビュー", "スキルの品質チェック", "エージェント設定確認", "config review", "skill quality check".
+context: fork
+agent: general-purpose
+model: opus
+allowed-tools: Read, Grep, Glob, WebSearch, WebFetch
+---
+
+# Claude 設定レビュアー
+
+Claude Code 設定ファイルの品質と Anthropic ベストプラクティスへの準拠をレビューする。
+
+> 参考: [Building Effective Agents](https://www.anthropic.com/engineering/building-effective-agents)
+
+## 主な責務
+
+- ベストプラクティスに基づく構造の検証
+- アンチパターンと一時的マーカーの検出
+- 内部リンク切れの確認
+- 必須セクションの存在確認
+- 重大度レベル付きの問題報告
+
+## ワークフロー
+
+1. **発見**: `.claude/` と `.claude/plugins/` 内の全設定ファイルを検索
+2. **分類**: タイプ別にグループ化（agents、skills、commands、output-styles、plugins）
+3. **検証**: 各ファイルをタイプ固有のルールに照合
+4. **報告**: 重大度と修正提案を含む検出結果を生成
+
+## 検証ルール
+
+### 全ファイル共通
+
+| チェック | 重大度 | パターン（およびバリエーション） |
+|---------|--------|-------------------------------|
+| 一時的マーカー | Warning | `**NEW**`, `TODO:`, `FIXME:`, `WIP`, `TBD`, `DRAFT`, `PLACEHOLDER`, `XXX:` |
+| 手動日付スタンプ | Warning | `Last Updated:`, `Updated:`, `Modified:`, `Created:`, `Date:`, `Version:`, `Rev:` |
+| ASCIIアート図 | Warning | 罫線文字、繰り返し装飾（`===`、`---` をボーダーとして使用） |
+| リンク切れ | Error | `[text](path)` でパスが存在しない |
+| 親参照ループ | Warning | `[../CLAUDE.md]`, `See parent project` |
+| コードブロックの言語指定なし | Info | ` ``` ` で言語指定なし |
+| ファイルが長すぎる | Warning | SKILL.md で 500行超 |
+
+**パターンマッチング**: 類似パターンにはあいまい一致を使用：
+- 日付: コードブロック外の `/\d{4}[-/]\d{2}[-/]\d{2}/`
+- マーカー: 大文字小文字無視（`TODO`, `Todo`, `todo`）
+- バージョン: `v1.0`, `1.0.0`, `ver. 1.0`
+- ASCIIアート: `/[+\-|]{3,}/` でボックスを形成
+
+### スキル（`.claude/skills/` および `.claude/plugins/*/skills/`）
+
+| チェック | 重大度 |
+|---------|--------|
+| SKILL.md が見つからない | Error |
+| SKILL.md frontmatter に description がない | Error |
+| 存在しないファイルへの参照 | Error |
+
+### エージェント（`.claude/agents/`）
+
+| チェック | 重大度 |
+|---------|--------|
+| frontmatter に `name` がない | Error |
+| frontmatter に `description` がない | Error |
+| 無効な名前形式（lowercase-hyphen である必要） | Error |
+| 呼び出しトリガーのない description | Warning |
+| ワークフローセクションがない | Warning |
+| ツールが過剰（正当な理由なく5個超） | Info |
+
+**Anthropic ベストプラクティスチェック**：
+
+| チェック | 重大度 | 根拠 |
+|---------|--------|------|
+| 重量級エージェント（500行超、約25k+トークン） | Warning | マルチエージェントワークフローのボトルネック |
+| キッチンシンクパターン（全ツール + 広範なスコープ） | Warning | 単一責務原則違反 |
+| 責務が多すぎる（コアタスク3個超） | Warning | 「シンプルに始める」原則 |
+| 「使用タイミング」ガイダンスがない | Info | 明確な呼び出しトリガーが必要 |
+| レビュアーに Write/Edit ツール | Warning | チェッカーエージェントは読み取り専用であるべき |
+| ジェネレーターに Write ツールがない | Info | 不完全な可能性 |
+
+### コマンド（`.claude/commands/`）
+
+| チェック | 重大度 |
+|---------|--------|
+| 空のコマンドファイル | Error |
+| 先頭に説明コメントがない | Warning |
+
+### 出力スタイル（`.claude/output-styles/`）
+
+| チェック | 重大度 |
+|---------|--------|
+| スタイル定義がない | Error |
+
+## 検出すべきアンチパターン
+
+```text
+# 一時的マーカー（大文字小文字無視、バリエーション含む）
+**NEW**, **WIP**, **DRAFT**, **PLACEHOLDER**
+TODO:, TODO(xxx):, FIXME:, HACK:, XXX:, NOTE:
+TBD, N/A, COMING SOON, IN PROGRESS
+[WIP], [DRAFT], [TODO]
+
+# 手動日付スタンプ（git が管理する - バリエーションを検出）
+Last Updated: 2025-xx-xx
+Updated:, Modified:, Created:, Revised:
+Date: xxxx-xx-xx
+Version: 1.0.0, v1.0, Rev. 1.0
+（コードブロック外の YYYY-MM-DD または YYYY/MM/DD）
+
+# 古い参照
+(patterns/old-file.md)  # ファイルが存在しない
+(../missing.md)         # リンク切れ
+
+# 曖昧な description
+description: Does stuff
+description: Agent for things
+description: [TODO]
+
+# キッチンシンクエージェント（単一責務原則違反）
+tools: All
+tools: Read, Write, Edit, Bash, WebFetch, WebSearch, Task  # 多すぎ
+
+# 書き込み権限を持つチェッカーエージェント（Creator-Checker 違反）
+name: code-reviewer
+tools: Read, Write, Edit      # レビュアーは読み取り専用であるべき
+```
+
+**ASCIIアートの代替案**（コンテキストサイズを考慮）：
+
+| 代わりに | 使うべきもの |
+|---------|-------------|
+| ボックス図 | Markdown テーブル、箇条書き |
+| フロー矢印 | 番号付きステップ、`1. → 2. → 3.` |
+| ツリー構造 | インデントリスト、ファイルパス表記 |
+| 装飾ボーダー | Markdown 見出し（`##`） |
+
+## レポートフォーマット
+
+```markdown
+# Claude 設定レビュー
+
+**スキャン**: .claude/ 内の {count} ファイル
+**問題**: {error_count} エラー, {warning_count} 警告, {info_count} 情報
+
+## エラー（修正必須）
+
+- [{ファイル}] {問題の説明}
+  修正: {提案}
+
+## 警告（修正推奨）
+
+- [{ファイル}] {問題の説明}
+  修正: {提案}
+
+## 情報（検討）
+
+- [{ファイル}] {問題の説明}
+
+## サマリー
+
+{全体的な評価と次のステップ}
+
+Self-Review Result: {PASS|FAIL}
+  Critical: {count}
+  Warning: {count}
+  Info: {count}
+  Files with issues: {file1, file2, ...}
+  Auto-fixable: {yes|no}
+```
+
+**Self-Review Result は必ずレポート末尾に出力する。**
+
+**Status 判定:**
+- Error > 0 → FAIL
+- Error = 0 → PASS
+
+**Auto-fixable 判定:**
+- yes: 一時的マーカー削除、コードブロック言語指定追加等の機械的修正
+- no: リンク切れ（リンク先確認必要）、構造的問題（設計判断必要）
+
+## ワークフローパターン認識
+
+スキル/エージェントレビュー時に、どのパターンに従っているか特定する：
+
+| パターン | 指標 | 推奨事項 |
+|---------|------|---------|
+| **アナライザー** | 読み取り専用ツール、description に「レビュー/チェック/分析」 | Write/Edit ツールがないことを確認 |
+| **ジェネレーター** | Write ツール、description に「作成/生成」 | 出力フォーマットが定義されているか確認 |
+| **トランスフォーマー** | Edit ツール、description に「リファクタ/移行/更新」 | 安全ルールの存在を確認 |
+| **インベスティゲーター** | Bash + Read、description に「デバッグ/診断」 | 根本原因ワークフローを確認 |
+| **オーケストレーター** | Task ツール、サブエージェントを調整 | 委任ロジックを確認 |
+
+**Creator-Checker ペア検出**：
+- 名前に「レビュアー/監査/チェッカー」を含む場合は読み取り専用であるべき
+- 名前に「ビルダー/ジェネレーター/コーダー」を含む場合は Write ツールが必要
+
+## 重要ポイント
+
+- `.claude/` ファイルの作成・更新後に毎回実行する
+- 明確な修正案を含む実行可能な問題に焦点を当てる
+- エラーは修正必須、警告は推奨
+- レポートは簡潔でスキャンしやすく保つ
+- 修正提案時に Anthropic のベストプラクティスを参照
+- `context: fork` でメインコンテキストを汚さない隔離サブエージェントとして実行
+- **fork 制約**: `context: fork` のため TodoWrite / AskUserQuestion は使用不可。読み取り専用サブエージェントとしてレポートのみ返す
+
+## NGケース
+
+- 検出した問題を自動修正しない（レポートのみ）
+- `.claude/rules/shirokuma/` のプラグイン生成ルールはレビュー対象外

package/plugin/shirokuma-skills-ja/skills/codebase-rule-discovery/SKILL.md

@@ -0,0 +1,217 @@
+---
+name: codebase-rule-discovery
+description: TypeScriptアプリケーションを分析してパターンを発見し、shirokuma-docs lintルール向けのコーディング規約を提案します。「ルール発見」「rule discovery」「規約提案」「convention proposal」「パターン分析」、コードベースからパターン抽出や新しい規約提案を調査する場合に使用。
+allowed-tools: Read, Grep, Glob, Bash, AskUserQuestion, TodoWrite
+---
+
+# コードベースルール発見
+
+TypeScript アプリケーションを分析して以下の2つの目的で使用：
+1. **パターン発見**: アプリ横断で既存パターンを抽出
+2. **規約提案**: 機械的チェックを可能にする新規約を提案
+
+## 使用タイミング
+
+- 「ルール発見」「rule discovery」を要求された場合
+- 「パターン分析」「pattern analysis」を要求された場合
+- 「規約提案」「convention proposal」を要求された場合
+- 「もっとチェックできるようにしたい」と言われた場合
+- 「統一感を上げたい」「機械的チェックを増やしたい」と言われた場合
+
+## 2つのモード
+
+### モード 1: パターン発見
+
+**目的**: アプリ横断で既存パターンを発見する
+
+```
+既存コード分析 → 共通パターン発見 → ルール提案
+```
+
+### モード 2: 規約提案
+
+**目的**: 機械的チェックを可能にする規約を提案する
+
+```
+チェック可能性分析 → 規約提案 → 採用後にルール実装
+```
+
+**重要な問い**: 「機械的チェックを可能にするために、コードはどう書くべきか？」
+
+## 対象アプリケーション
+
+| アプリ | パス | 説明 |
+|--------|------|------|
+| Blog CMS (admin) | `nextjs-tdd-blog-cms/apps/admin/` | CMS 管理画面 |
+| Blog CMS (public) | `nextjs-tdd-blog-cms/apps/public/` | 公開ブログ |
+| shirokuma-docs | `shirokuma-docs/src/` | ドキュメント生成 CLI |
+
+## ワークフロー: パターン発見
+
+6ステップ以上のため TodoWrite で進捗管理すること。規約提案の優先度判断時は AskUserQuestion でユーザー確認。
+
+### ステップ概要
+
+1. スコープ定義 + 既存ルール確認
+2. パターンカウント実行 + サンプル収集
+3. 一貫性・不整合・欠落パターンの分析
+4. 優先度付け（P0/P1/P2）
+5. 提案生成（テンプレート使用）
+6. レポート保存 + フォローアップ Issue 作成
+
+### 詳細ワークフロー
+
+[workflows/analyze-codebase.md](workflows/analyze-codebase.md) を参照
+
+## ワークフロー: 規約提案
+
+### ステップ 1: チェック可能な機会を特定
+
+規約があればチェック可能になる箇所を分析：
+
+| カテゴリ | 現状 | 標準化した場合 |
+|----------|------|---------------|
+| ファイル配置 | 混在 | ドメインベース配置チェックが可能 |
+| 命名 | 部分的に統一 | 自動リネーム提案が可能 |
+| i18n キー | 自由形式 | キーフォーマット検証が可能 |
+
+### ステップ 2: 現状の構造を分析
+
+```bash
+# ファイル構造分析
+find apps/ -name "*.ts" -o -name "*.tsx" | head -100
+
+# ディレクトリパターン
+ls -la apps/admin/lib/
+ls -la apps/public/lib/
+
+# 命名規約
+find apps/ -name "*.tsx" | xargs basename -a | sort | uniq -c | sort -rn
+```
+
+### ステップ 3: 規約を提案
+
+各機会について以下を文書化：
+
+1. **現状**: 現在の実装方法（バリエーション含む）
+2. **提案する規約**: 具体的なルール
+3. **移行コスト**: 既存コードの変更量
+4. **可能になるチェック**: 実装可能になる lint ルール
+5. **メリット**: 標準化の価値
+
+### ステップ 4: 規約提案書を生成
+
+[templates/convention-proposal.md](templates/convention-proposal.md) を使用
+
+### ステップ 5: Knowledge Discussion として保存
+
+ルール提案前に、コンテキストと根拠を保存するため Knowledge Discussion を作成。
+
+```bash
+# 確認済みパターン → Knowledge カテゴリ
+shirokuma-docs discussions create --category Knowledge --title "{パターン名}" --body "..."
+
+# 調査中 → Research カテゴリ
+shirokuma-docs discussions create --category Research --title "[Research] convention-{category}" --body "..."
+```
+
+**確信度に基づきカテゴリを選択：**
+
+| 確信度 | カテゴリ | 次のステップ |
+|--------|----------|-------------|
+| 確認済み（パターンが2回以上観測） | Knowledge | ルール抽出に進む（ステップ 6） |
+| 暫定的（更なる検証が必要） | Research | より多くの証拠を待つ |
+
+Discussion はルールの根拠の**ソースオブトゥルース**。ルール提案前に必ず作成すること。
+
+### ステップ 6: ルール抽出（Knowledge の場合）
+
+パターンが Knowledge（確認済み）として記録された場合、AI 向けのルールを提案：
+
+1. `managing-rules` スキルを使用してルールファイルを作成
+2. ルールは簡潔で実行可能に（AI 向け）
+3. ソース参照を追加: `<!-- Source: Discussion #{N} -->`
+4. Knowledge Discussion が完全なコンテキストを保持、ルールはその抽出版
+
+## 規約カテゴリ
+
+### 1. ファイル配置規約
+
+| 領域 | 規約 | 可能になるチェック |
+|------|------|-------------------|
+| Server Actions | `lib/actions/{domain}.ts` | ドメイン網羅性チェック |
+| コンポーネント | `components/{Domain}/` | コンポーネント依存チェック |
+| Hooks | `hooks/use{Name}.ts` | Hook 命名チェック |
+| 型定義 | `types/{domain}.ts` | 型定義重複チェック |
+
+### 2. 命名規約
+
+| 対象 | 規約 | 例 |
+|------|------|-----|
+| Server Action ファイル | `{domain}-actions.ts` | `post-actions.ts` |
+| コンポーネントファイル | `{Name}.tsx` (PascalCase) | `PostCard.tsx` |
+| Hook ファイル | `use{Name}.ts` | `useAuth.ts` |
+| テストファイル | `{name}.test.ts` | `post-actions.test.ts` |
+
+### 3. コード構造規約
+
+| 領域 | 規約 | 可能になるチェック |
+|------|------|-------------------|
+| Server Action の順序 | Auth → CSRF → Validation → Processing | 順序チェック |
+| エクスポートスタイル | 名前付きエクスポート推奨 | 未使用エクスポート検出の改善 |
+| i18n キー | `{domain}.{action}.{element}` | キーフォーマットチェック |
+
+### 4. アノテーション規約
+
+| タグ | 必須対象 | 可能になるチェック |
+|------|----------|-------------------|
+| `@serverAction` | Server Actions | 自動ドキュメント生成 |
+| `@screen` | ページコンポーネント | 画面カタログ生成 |
+| `@usedComponents` | 画面 | 依存関係グラフ生成 |
+
+## 既存ルール（参考）
+
+| ルール | ステータス |
+|--------|-----------|
+| server-action-structure | 実装済み |
+| annotation-required | 実装済み |
+| testdoc-* | 実装済み |
+
+現在の実装は `shirokuma-docs/src/lint/rules/` を確認。
+
+## NGケース
+
+- 既存ルールと重複する提案をしない
+- 2回未満の観測でパターン確認済みとしない
+
+## クイックリファレンス
+
+```bash
+# パターン発見（モード 1）
+"discover patterns in blog-cms"
+
+# 規約提案（モード 2）
+"propose conventions for better checking"
+
+# 特定領域
+"propose file placement conventions"
+"propose naming conventions"
+"propose i18n key conventions"
+```
+
+## 関連リソース
+
+- [patterns/discovery-categories.md](patterns/discovery-categories.md) - 発見対象
+- [templates/rule-proposal.md](templates/rule-proposal.md) - ルール提案フォーマット
+- [templates/convention-proposal.md](templates/convention-proposal.md) - 規約提案フォーマット
+- [workflows/analyze-codebase.md](workflows/analyze-codebase.md) - 詳細ワークフロー
+
+## 出力
+
+規約提案は以下に回答すべき：
+
+1. **何を**: 具体的な規約内容
+2. **なぜ**: その規約が必要な理由
+3. **チェック**: 可能になるチェック
+4. **移行**: 既存コードの移行コスト
+5. **優先度**: P0/P1/P2

package/plugin/shirokuma-skills-ja/skills/codebase-rule-discovery/patterns/discovery-categories.md

@@ -0,0 +1,150 @@
+# 発見カテゴリ
+
+TypeScript アプリケーション全体で発見すべきパターンのカテゴリ。
+
+## 1. 構造パターン
+
+### ファイル命名
+
+| パターン | Grep コマンド | ルール候補 |
+|---------|--------------|-----------|
+| kebab-case ファイル | `find . -name "*.ts" \| grep -E "[a-z]+-[a-z]+"` | naming-convention |
+| PascalCase コンポーネント | `find . -name "*.tsx" \| grep -E "^[A-Z]"` | component-naming |
+| index.ts 再エクスポート | `find . -name "index.ts"` | barrel-exports |
+
+### エクスポートパターン
+
+```bash
+# default vs named exports
+grep -r "^export default" --include="*.ts" | wc -l
+grep -r "^export function" --include="*.ts" | wc -l
+grep -r "^export const" --include="*.ts" | wc -l
+```
+
+### インポート順序
+
+```bash
+# インポートグループ確認 (react, next, lib, local)
+grep -A10 "^import" --include="*.tsx" | head -50
+```
+
+## 2. コード品質パターン
+
+### エラーハンドリング
+
+```bash
+# try-catch 使用状況
+grep -rn "try {" --include="*.ts"
+
+# エラーログ
+grep -rn "console.error" --include="*.ts"
+grep -rn "logger.error" --include="*.ts"
+
+# エラー型
+grep -rn "throw new Error" --include="*.ts"
+grep -rn "throw new [A-Z].*Error" --include="*.ts"
+```
+
+### 非同期パターン
+
+```bash
+grep -rn "async function" --include="*.ts"
+grep -rn "\.then(" --include="*.ts"
+grep -rn "await " --include="*.ts"
+grep -rn "Promise.all" --include="*.ts"
+```
+
+### 型安全性
+
+```bash
+# any の使用
+grep -rn ": any" --include="*.ts"
+grep -rn "as any" --include="*.ts"
+
+# unknown の使用
+grep -rn ": unknown" --include="*.ts"
+
+# 型アサーション
+grep -rn "as [A-Z]" --include="*.ts"
+```
+
+## 3. フレームワークパターン
+
+### Server Actions
+
+```bash
+grep -rn '"use server"' --include="*.ts"
+grep -rn "verifyAuth\|verifyAuthMutation" --include="*.ts"
+grep -rn "validateCSRF\|csrfProtect" --include="*.ts"
+grep -rn "\.parse(\|\.safeParse(" --include="*.ts"
+```
+
+### React コンポーネント
+
+```bash
+grep -rn "^export function [A-Z]" --include="*.tsx"
+grep -rn "interface.*Props" --include="*.tsx"
+grep -rn "use[A-Z][a-zA-Z]*(" --include="*.tsx"
+```
+
+### i18n パターン
+
+```bash
+grep -rn "useTranslations" --include="*.tsx"
+grep -rn "t\(['\"]" --include="*.tsx"
+grep -rn 't("' --include="*.tsx" | sed 's/.*t("//' | sed 's/".*//' | sort | uniq
+```
+
+## 4. ドキュメントパターン
+
+### JSDoc カバレッジ
+
+```bash
+grep -rn "/\*\*" --include="*.ts"
+grep -rn "@description" --include="*.ts"
+grep -rn "@param" --include="*.ts"
+grep -rn "@returns\|@return" --include="*.ts"
+```
+
+### カスタムアノテーション
+
+```bash
+grep -rn "@screen\|@component\|@serverAction" --include="*.ts"
+grep -rn "@usedComponents\|@usedActions" --include="*.ts"
+grep -rn "@dbTables\|@feature" --include="*.ts"
+```
+
+### TODO/FIXME 追跡
+
+```bash
+grep -rn "// TODO\|// FIXME" --include="*.ts"
+grep -rn "// TODO(@" --include="*.ts"
+```
+
+## 5. テストパターン
+
+### テスト構造
+
+```bash
+grep -rn "describe(" --include="*.test.ts"
+grep -rn "it(\|test(" --include="*.test.ts"
+grep -rn "@testdoc" --include="*.test.ts"
+```
+
+### モックパターン
+
+```bash
+grep -rn "jest.mock" --include="*.test.ts"
+grep -rn "vi.mock" --include="*.test.ts"
+```
+
+## 分析マトリクス
+
+| カテゴリ | Admin | Public | Web | MCP | shirokuma |
+|---------|-------|--------|-----|-----|-----------|
+| エラーハンドリング | ? | ? | ? | ? | ? |
+| 型安全性 | ? | ? | ? | ? | ? |
+| JSDoc カバレッジ | ? | ? | ? | ? | ? |
+| Server Actions | ? | ? | ? | N/A | N/A |
+
+分析中にカウントを記入し、パターンと不整合を特定する。