shirokuma-docs 0.1.0-alpha.1

package/plugin/shirokuma-skills-ja/skills/codebase-rule-discovery/templates/convention-proposal.md

@@ -0,0 +1,138 @@
+# 規約提案テンプレート
+
+規約を提案し、それによって可能になるチェックを明確にするテンプレート。
+
+---
+
+# Convention Proposal: {convention-name}
+
+**Date**: YYYY-MM-DD
+**Category**: {File Placement | Naming | Code Structure | Annotation | i18n}
+**Priority**: {P0 | P1 | P2}
+
+## 現状分析
+
+### 現在の状態
+
+{現在どのように書かれているか}
+
+| App | パターンA | パターンB | その他 |
+|-----|----------|----------|--------|
+| blog-cms (admin) | X件 | Y件 | Z件 |
+| blog-cms (public) | X件 | Y件 | Z件 |
+
+### 問題点
+
+1. {問題1: 不統一による問題}
+2. {問題2: 機械的チェックができない}
+3. {問題3: 新規参画者の混乱}
+
+## 提案規約
+
+### 規約内容
+
+```
+{具体的なルール}
+例: Server Actionファイルは `lib/actions/{domain}.ts` に配置する
+```
+
+### 詳細仕様
+
+| 項目 | 規約 | 例 |
+|------|------|-----|
+| {項目1} | {規約} | {例} |
+| {項目2} | {規約} | {例} |
+
+### 許容パターン
+
+```typescript
+// OK
+{許容されるコード例}
+
+// NG
+{許容されないコード例}
+```
+
+## チェック可能性
+
+### この規約で可能になるチェック
+
+| チェック | 説明 | severity |
+|---------|------|----------|
+| {check-1} | {説明} | error/warning/info |
+| {check-2} | {説明} | error/warning/info |
+
+### 実装イメージ
+
+```typescript
+// shirokuma-docs lint rule
+export const {ruleName}Rule: LintRule = {
+  id: "{rule-id}",
+  check(file, allFiles) {
+    // {チェックロジック概要}
+  }
+}
+```
+
+## 移行計画
+
+### 影響範囲
+
+| App | 変更必要ファイル数 | 工数見積 |
+|-----|------------------|---------|
+| blog-cms | X件 | Y時間 |
+
+### 移行手順
+
+1. {手順1}
+2. {手順2}
+3. {手順3}
+
+### 自動修正可能性
+
+- [ ] 完全自動修正可能
+- [ ] 部分的に自動修正可能（{理由}）
+- [ ] 手動修正必要
+
+## 効果
+
+### 定量効果
+
+- チェック可能項目: +{N}項目
+- 機械的検出可能なバグ: {種類}
+- ドキュメント自動生成: {範囲}
+
+### 定性効果
+
+- {効果1: コード統一性}
+- {効果2: 新規参画者の学習コスト削減}
+- {効果3: レビュー負荷軽減}
+
+## 代替案
+
+### 代替案A: {名前}
+
+{概要}
+
+**Pros**: {利点}
+**Cons**: {欠点}
+
+### 採用理由
+
+{提案案を採用する理由}
+
+## 関連
+
+- 既存ルール: {関連する既存ルール}
+- ADR: {関連するADR}
+- Issue: {関連するIssue}
+
+---
+
+## チェックリスト
+
+- [ ] 現状の変動パターンを全て把握
+- [ ] 規約が明確で例外なく適用可能
+- [ ] チェックロジックが実装可能
+- [ ] 移行コストが許容範囲
+- [ ] 効果が移行コストを上回る

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

@@ -0,0 +1,148 @@
+# ルール提案テンプレート
+
+shirokuma-docs の新しい lint ルールを提案する際に使用するテンプレート。
+
+---
+
+# Rule Proposal: {rule-name}
+
+**Date**: YYYY-MM-DD
+**Category**: {Structural | Quality | Framework | Documentation}
+**Priority**: {P0 | P1 | P2}
+
+## パターン説明
+
+{発見されたパターンとその重要性}
+
+## 検出状況
+
+| App | 件数 | 例 |
+|-----|------|-----|
+| admin | X | `lib/actions/posts.ts:10` |
+| public | X | `lib/actions/comments.ts:5` |
+| web | X | `lib/actions/sessions.ts:15` |
+| mcp | X | `src/tools/entity.ts:20` |
+| shirokuma | X | `src/commands/lint.ts:30` |
+
+**合計**: Y アプリ全体で X 件
+
+## 不整合
+
+{期待されるパターンからの逸脱を列挙}
+
+- App `admin`: {逸脱の説明}
+- App `web`: {逸脱の説明}
+
+## 提案ルール
+
+### 仕様
+
+```yaml
+rule:
+  id: "{rule-name}"
+  severity: "{error | warning | info}"
+  description: "{チェック内容}"
+  fixable: {true | false}
+
+  options:
+    option1: value
+    option2: value
+```
+
+### 検出ロジック
+
+```
+1. {パターン} を検索
+2. {条件} をチェック
+3. {違反} があれば報告
+```
+
+### 自動修正（該当する場合）
+
+```
+1. {修正手順1}
+2. {修正手順2}
+```
+
+## 実装スケッチ
+
+```typescript
+import type { LintRule, LintIssue } from "../types.js";
+
+export const {ruleName}Rule: LintRule = {
+  id: "{rule-name}",
+  severity: "{severity}",
+  description: "{description}",
+
+  check(file: SourceFile, allFiles: SourceFile[]): LintIssue[] {
+    const issues: LintIssue[] = [];
+
+    // TODO: 実装
+    // 1. ファイル内容をパース
+    // 2. パターン出現箇所を検索
+    // 3. 違反をチェック
+    // 4. 問題を報告
+
+    return issues;
+  }
+};
+```
+
+## 設定
+
+```yaml
+# shirokuma-docs.config.yaml
+lintQuality:
+  {ruleName}:
+    enabled: true
+    severity: "{severity}"
+    # ルール固有オプション
+    option1: value
+```
+
+## テストケース
+
+### パスすべきケース
+
+```typescript
+// 有効なコード例
+{valid code}
+```
+
+### 失敗すべきケース
+
+```typescript
+// 無効なコード例
+{invalid code}
+```
+
+### エッジケース
+
+- {エッジケース1}
+- {エッジケース2}
+
+## 優先度の根拠
+
+**P0**: デプロイをブロックする、またはバグを引き起こす
+**P1**: 品質・一貫性を向上させる
+**P2**: あれば良い程度の改善
+
+{この優先度を選択した理由}
+
+## 関連
+
+- 既存ルール: {関連する既存ルール}
+- ADR: {関連するADR}
+- Issue: {関連するIssue}
+
+---
+
+## チェックリスト
+
+- [ ] 全アプリでパターンを検証済み
+- [ ] 検出件数を記録済み
+- [ ] 不整合を特定済み
+- [ ] 実装スケッチを提供済み
+- [ ] テストケースを定義済み
+- [ ] 優先度の根拠を記載済み
+- [ ] 既存ルールとの重複なし

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

@@ -0,0 +1,211 @@
+# コードベース分析ワークフロー
+
+アプリケーション全体でパターンを発見するためのステップバイステップワークフロー。
+
+## 前提条件
+
+- 対象アプリケーションへのアクセス
+- shirokuma-docs インストール済み
+- [discovery-categories.md](../patterns/discovery-categories.md) の理解
+
+## ワークフロー
+
+### Phase 1: 準備
+
+#### 1.1 スコープ定義
+
+```bash
+# 全体分析
+APPS="admin public"
+PATHS="nextjs-tdd-blog-cms/apps/admin nextjs-tdd-blog-cms/apps/public"
+
+# 特定カテゴリ
+CATEGORY="error-handling"  # or: naming, types, async, jsdoc, etc.
+```
+
+#### 1.2 既存ルールの確認
+
+```bash
+ls shirokuma-docs/src/lint/rules/
+```
+
+以下との重複を避ける:
+- server-action-structure.ts
+- annotation-required.ts
+- testdoc-*.ts
+
+### Phase 2: データ収集
+
+#### 2.1 パターンカウント実行
+
+discovery-categories.md の各パターンについて:
+
+```bash
+echo "=== Pattern: {name} ==="
+for app in $PATHS; do
+  count=$(grep -rn "PATTERN" "$app" --include="*.ts" 2>/dev/null | wc -l)
+  echo "$app: $count"
+done
+```
+
+#### 2.2 サンプル収集
+
+```bash
+# アプリごとに最初の3例を取得
+for app in $PATHS; do
+  echo "--- $app ---"
+  grep -rn "PATTERN" "$app" --include="*.ts" 2>/dev/null | head -3
+done
+```
+
+#### 2.3 マトリクスに記録
+
+| パターン | Admin | Public |
+|---------|-------|--------|
+| try-catch | X | X |
+| console.error | X | X |
+| ... | ... | ... |
+
+### Phase 3: 分析
+
+#### 3.1 一貫性の特定
+
+ルール候補として有力なパターン:
+- 3つ以上のアプリで同じアプローチ
+- 高い出現回数（アプリあたり10件以上）
+
+#### 3.2 不整合の特定
+
+```
+App A: パターン X (100%)
+App B: パターン X (80%) + パターン Y (20%) ← 不整合!
+```
+
+#### 3.3 欠落パターンの特定
+
+```
+App A: パターンあり
+App B: パターンあり
+App C: パターン欠落 ← 必須ルールの候補
+```
+
+### Phase 4: 優先度付け
+
+#### 優先度マトリクス
+
+| 基準 | P0 | P1 | P2 |
+|------|----|----|-----|
+| バグ発生可能性 | 高 | 中 | 低 |
+| 出現回数 | >100 | 50-100 | <50 |
+| 不整合度 | 重大 | 中程度 | 軽微 |
+| 修正の複雑さ | 自動修正可 | 半自動 | 手動 |
+
+#### 判断ツリー
+
+```
+セキュリティ/認証の問題か?
+├─ はい → P0
+└─ いいえ
+   ランタイムバグを引き起こすか?
+   ├─ はい → P0
+   └─ いいえ
+      アプリ間の一貫性の問題か?
+      ├─ はい、50件以上 → P1
+      └─ いいえ → P2
+```
+
+### Phase 5: 提案生成
+
+#### 5.1 テンプレート使用
+
+[templates/rule-proposal.md](../templates/rule-proposal.md) をコピー
+
+#### 5.2 セクション記入
+
+1. **パターン説明**: 発見内容
+2. **検出状況**: Phase 2 のカウント
+3. **不整合**: Phase 3 の結果
+4. **提案ルール**: 検出ロジック
+5. **実装**: コードスケッチ
+6. **優先度**: Phase 4 の結果
+
+#### 5.3 検証
+
+- [ ] 既存ルールとの重複なし
+- [ ] 合計出現回数 >10
+- [ ] 検出ロジックが明確
+- [ ] 自動修正の可能性を評価済み
+
+### Phase 6: 出力
+
+#### 6.1 レポート保存
+
+```bash
+# GitHub Discussions（Research カテゴリ）に保存
+shirokuma-docs discussions create \
+  --category Research \
+  --title "[Research] Rule Discovery: ${CATEGORY}" \
+  --body "# Rule Discovery Report: ${CATEGORY}
+..."
+```
+
+#### 6.2 将来計画へのリンク（該当する場合）
+
+計画済み機能に関連するルールの場合:
+- GitHub Discussions（Ideas カテゴリ）で関連する提案を確認
+- GitHub Projects でロードマップ追跡にリンク
+
+#### 6.3 フォローアップ Issue 作成
+
+提案ルールが shirokuma-docs の実装を必要とする場合、GitHub Issue を作成。
+
+## クイックコマンドリファレンス
+
+```bash
+# エラーハンドリングパターン
+grep -rn "try {" apps/ --include="*.ts" | wc -l
+grep -rn "catch.*{" apps/ --include="*.ts" | wc -l
+grep -rn "console.error\|logger.error" apps/ --include="*.ts" | wc -l
+
+# 型安全性
+grep -rn ": any\|as any" apps/ --include="*.ts" | wc -l
+
+# 非同期パターン
+grep -rn "async function\|async (" apps/ --include="*.ts" | wc -l
+grep -rn "\.then(" apps/ --include="*.ts" | wc -l
+
+# JSDoc カバレッジ
+grep -rn "^/\*\*" apps/ --include="*.ts" | wc -l
+grep -rn "@param" apps/ --include="*.ts" | wc -l
+
+# 命名パターン
+find apps/ -name "*.ts" | xargs basename -a | sort | uniq -c | sort -rn | head -20
+
+# エクスポートパターン
+grep -r "^export default" apps/ --include="*.ts" | wc -l
+grep -r "^export function" apps/ --include="*.ts" | wc -l
+```
+
+## 出力フォーマット
+
+```markdown
+# Rule Discovery Report: {Category}
+
+**Date**: YYYY-MM-DD
+**Apps Analyzed**: admin, public
+**Patterns Found**: X
+**Proposed Rules**: Y
+
+## Summary
+
+| パターン | 出現回数 | 一貫性 | 優先度 |
+|---------|---------|--------|--------|
+| {name} | X | High/Med/Low | P0/P1/P2 |
+
+## Proposals
+
+### 1. {Rule Name}
+[提案全文へのリンク]
+
+...
+```