# 🔍 Hakorune 機能発見性（Discoverability）問題の深層分析 **問題**: ChatGPTですら、こんな冗長コードを書いてしまう： ```nyash hex_digit(ch) { if ch == "0" { return 0 } if ch == "1" { return 1 } if ch == "2" { return 2 } // ... 続く16行 } ``` **本来あるべき姿**（既に実装済み機能で書ける）： ```nyash // 方法1: match式（Phase 12.7実装済み） hex_digit(ch) { return match ch { "0" => 0, "1" => 1, "2" => 2, "3" => 3, "4" => 4, "5" => 5, "6" => 6, "7" => 7, "8" => 8, "9" => 9, "a" => 10, "b" => 11, "c" => 12, "d" => 13, "e" => 14, "f" => 15, _ => 0 } } // 方法2: Mapリテラル（実装済み） static box HexUtils { hex_map: MapBox birth() { me.hex_map = new MapBox() me.hex_map.set("0", 0) me.hex_map.set("1", 1) // ... } hex_digit(ch) { return me.hex_map.get(ch) } } // 方法3: indexOf（StringBox実装済み） hex_digit(ch) { local hex_chars = "0123456789abcdef" return hex_chars.indexOf(ch) } ``` --- ## 📊 根本原因分析（5つの問題） ### **問題1: ドキュメント導線の弱さ** **現状**: ``` docs/reference/language/LANGUAGE_REFERENCE_2025.md (1,500行) ↓ 機能は書いてある ↓ でも「いつ使うか」が分からない ``` **不足している情報**: - ❌ 「こういう場合はmatch式を使う」 - ❌ 「配列ルックアップ vs Map vs match の使い分け」 - ❌ 「Anti-Pattern（やってはいけない書き方）」 ### **問題2: サンプルコード不足** **現状**: ``` apps/examples/ ← 基本的なサンプルのみ apps/tests/ ← テストケースはあるが学習用ではない ``` **不足**: - ❌ Cookbook/Recipe集（「～したい時は？」） - ❌ Best Practice集 - ❌ イディオム集（慣用句） ### **問題3: AI学習データの不足** **現状**: ``` ChatGPT/Claudeの学習データ: - JavaScript: 大量 - Python: 大量 - Rust: 中程度 - Nyash/Hakorune: ほぼゼロ ``` **結果**: JavaScriptパターンで書いてしまう ```javascript // JavaScript風（冗長） if (x == "a") return 1 if (x == "b") return 2 ``` ### **問題4: 糖衣構文の発見性** **実装済みだが知られていない機能**: - ✅ match式（Phase 12.7） - ✅ Lambda式 - ✅ ?演算子（Result伝播） - ✅ Mapリテラル - ✅ 配列メソッド（indexOf/find等） **問題**: 「機能がある」ことは分かっても、「いつ使うべきか」が分からない ### **問題5: Linter/Static Analysis不足** **現状**: コード品質チェックがない ```nyash // これを書いても警告が出ない（出るべき） if ch == "0" { return 0 } if ch == "1" { return 1 } // ... 続く ``` **理想**: Linterが検出 ``` Warning: Consider using match expression instead of if-else chain → Suggested refactoring: match ch { "0" => 0, "1" => 1, ... } ``` --- ## 🎯 解決策（5つの柱） ### **解決策1: Cookbook/Recipe集の作成** 🔴 最優先 **構成案**: ```markdown docs/cookbook/ ├── README.md ├── patterns/ │ ├── lookup-table.md # ルックアップテーブル実装 │ ├── string-parsing.md # 文字列解析 │ ├── error-handling.md # エラー処理パターン │ └── collections.md # コレクション操作 ├── anti-patterns/ │ ├── if-chain.md # if連鎖のアンチパターン │ ├── manual-loop.md # 手動ループのアンチパターン │ └── null-check.md # null チェックのアンチパターン └── refactoring/ ├── if-to-match.md # if → match変換 ├── loop-to-map.md # ループ → map/filter変換 └── manual-to-builtin.md # 手動実装 → ビルトイン変換 ``` **例**: `docs/cookbook/patterns/lookup-table.md` ```markdown # ルックアップテーブルパターン ## ❌ Anti-Pattern（やってはいけない） ```nyash hex_digit(ch) { if ch == "0" { return 0 } if ch == "1" { return 1 } // ... 冗長 } ``` ## ✅ Pattern 1: match式（推奨、シンプルなルックアップ） ```nyash hex_digit(ch) { return match ch { "0" => 0, "1" => 1, "2" => 2, ... _ => 0 } } ``` ## ✅ Pattern 2: indexOf（文字列ベース） ```nyash hex_digit(ch) { return "0123456789abcdef".indexOf(ch) } ``` ## ✅ Pattern 3: MapBox（複雑な値） ```nyash static box HexMap { map: MapBox birth() { me.map = new MapBox() me.map.set("zero", 0) // ... } } ``` ## 使い分け - シンプルなルックアップ → match式 - 連続文字 → indexOf - 複雑な値/初期化 → MapBox ``` --- ### **解決策2: Quick Reference拡充** 🟡 **現状**: 文法中心 **改善**: Use Case中心に再構成 ```markdown # Use Case別 Quick Reference ## 文字列解析 - hex変換 → indexOf/match - split → string.split() - 正規表現 → RegexBox ## ルックアップ - 固定値 → match - 動的 → MapBox - 連続 → indexOf ## 繰り返し処理 - 変換 → array.map() - フィルタ → array.filter() - 集約 → array.reduce() ``` --- ### **解決策3: サンプルコード集の充実** 🟡 **追加すべきサンプル**: ``` apps/examples/ ├── cookbook/ │ ├── hex_parser.hkr # hex解析の正しい書き方 │ ├── json_parser.hkr # JSON解析 │ ├── state_machine.hkr # ステートマシン │ └── validator.hkr # バリデーション ├── best-practices/ │ ├── match_vs_if.hkr # match vs if使い分け │ ├── map_vs_array.hkr # Map vs Array選択 │ └── error_handling.hkr # エラー処理パターン └── anti-patterns/ ├── if_chain_bad.hkr # ❌ 悪い例 └── if_chain_good.hkr # ✅ 良い例 ``` --- ### **解決策4: Linter/フォーマッター導入** 🟢 **Phase 18-20で実装検討**: ```bash # Linter実行 $ hakorune lint my_code.hkr Warning: Inefficient if-else chain detected --> my_code.hkr:10:5 | 10 | if ch == "0" { return 0 } 11 | if ch == "1" { return 1 } | ^^^^^^^^^^^^^^^^^^^^^^^^^ Consider using match expression | = help: match ch { "0" => 0, "1" => 1, ... } ``` **検出すべきAnti-Pattern**: 1. If-else連鎖（match式推奨） 2. 手動ループ（map/filter推奨） 3. 未使用変数 4. 型不一致（opt-in型チェック時） --- ### **解決策5: AI学習用データ整備** 🟢 **コンテキスト注入用ファイル**: ``` docs/for-ai/ ├── PATTERNS.md # 推奨パターン集 ├── ANTI_PATTERNS.md # アンチパターン集 ├── IDIOMS.md # 慣用句集 └── COMMON_MISTAKES.md # よくある間違い ``` **CLAUDE.mdに追加**: ```markdown ## 🤖 AI開発者への注意事項 ### ❌ やってはいけないパターン 1. If-else連鎖 → match式を使う 2. 手動for文 → map/filter/reduce 3. null手動チェック → ?演算子 ### ✅ 推奨パターン 1. ルックアップ → match/indexOf/MapBox 2. 変換 → array.map() 3. エラー処理 → Result + ?演算子 ``` --- ## 📅 実装優先順位 ### **Phase 17（即座）** 🔴 1. **Cookbook/Recipe集作成** - `docs/cookbook/patterns/lookup-table.md` - `docs/cookbook/anti-patterns/if-chain.md` - `docs/cookbook/refactoring/if-to-match.md` 2. **CLAUDE.md拡充** - AI開発者への注意事項セクション追加 - よくあるアンチパターン明記 ### **Phase 18-19** 🟡 3. **サンプルコード集** - `apps/examples/cookbook/` 作成 - ベストプラクティス実装例 4. **Quick Reference再構成** - Use Case中心に再編成 ### **Phase 20-22** 🟢 5. **Linter/フォーマッター** - Anti-Pattern検出 - 自動リファクタリング提案 --- ## 🎯 期待される効果 ### **短期効果（Phase 17）** - ✅ AI（ChatGPT/Claude）がアンチパターンを避ける - ✅ 新規開発者が正しい書き方を学べる - ✅ コードレビュー時の指摘減少 ### **中期効果（Phase 18-19）** - ✅ サンプルコードからコピペで正しいコード - ✅ 言語機能の利用率向上 - ✅ コード品質の一貫性向上 ### **長期効果（Phase 20-22）** - ✅ Linterが自動で品質保証 - ✅ リファクタリングが容易 - ✅ 技術的負債の削減 --- ## 💡 名言化 > **「機能があっても、使われなければ意味がない」** > > Hakoruneは強力な機能を持つ。 > しかし、その使い方が伝わらなければ宝の持ち腐れ。 > > **Cookbook/Recipe集で「発見性」を高める**ことが、 > 次のPhaseの最重要課題。 --- ## 🎊 まとめ ChatGPTが冗長なif連鎖を書いてしまった問題は、 **言語機能の不足ではなく、発見性（Discoverability）の問題**。 **解決策5本柱**: 1. 🔴 Cookbook/Recipe集作成（Phase 17、最優先） 2. 🟡 Quick Reference拡充（Phase 17-18） 3. 🟡 サンプルコード集（Phase 18-19） 4. 🟢 Linter/フォーマッター（Phase 20-22） 5. 🟢 AI学習用データ整備（Phase 17-19） **Phase 17で即座に着手すべき**: - `docs/cookbook/` ディレクトリ作成 - Anti-Pattern集の整備 - CLAUDE.mdへのAI開発者向け注意事項追加 これにより、「つよつよ機能」が「実際に使われる」ようになりますにゃ！