初期検討段階のドキュメントと運用ルールを取り込む

ルール策定前に書かれた設計ドキュメント7点を、以降の基準点としてそのままの状態で記録する。CLAUDE.md のルール1〜4は未適用。 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MdLT5x5ka5y6CaWLeE3EKb
2026-09-18 08:43:01 +09:00
commit 55243f626d
12 changed files with 2395 additions and 0 deletions
@@ -0,0 +1,203 @@
+# Beyond KLE: TypeScript実装計画
+
+## プロジェクト構造
+
+```
+beyond-kle/
+├── packages/
+│   ├── core/                 # 共通型定義とユーティリティ
+│   │   ├── src/
+│   │   │   ├── types/       # 各レイヤーの型定義
+│   │   │   ├── validators/  # JSON Schema バリデーター
+│   │   │   └── utils/       # 共通ユーティリティ
+│   │   └── package.json
+│   ├── phy-editor/          # PHYレイヤーエディタ
+│   ├── matrix-mapper/       # IDX/ELCレイヤーマッパー
+│   ├── keymap-designer/     # MAPレイヤーデザイナー
+│   ├── converter/           # 既存フォーマット変換
+│   └── firmware-gen/        # ファームウェア生成
+├── tools/
+│   ├── cli/                 # CLI ツール
+│   └── web-editor/          # Web統合エディタ
+├── schemas/                 # JSON Schema定義
+├── examples/               # サンプルプロジェクト
+└── docs/                   # ドキュメント
+```
+
+## 開発フェーズ
+
+### Phase 1a: 基盤実装
+
+1. **型定義とSchema**
+   - TypeScript型定義
+   - JSON Schema validation
+   - テスト用サンプルデータ
+
+2. **変換エンジン**
+   - KLE JSON → PHY変換
+   - PHY → IDX自動生成
+   - QMK/VIA出力
+
+3. **CLIツール**
+   - 変換機能のコマンドライン提供
+   - バリデーション機能
+
+### Phase 1b: エディタプロトタイプ
+
+1. **PHY Editor (Web)**
+   - React + Canvas での編集機能
+   - KLE互換インポート
+
+2. **Matrix Mapper**
+   - 視覚的マトリックス割り当て
+   - 最適化アルゴリズム
+
+## 技術スタック
+
+### コア
+
+- **言語**: TypeScript
+- **ランタイム**: Node.js / Bun
+- **パッケージ管理**: pnpm + workspace
+- **バリデーション**: Ajv (JSON Schema)
+
+### CLI
+
+- **フレームワーク**: Commander.js
+- **出力**: chalk (色付き), table
+
+### Web Editor
+
+- **フロントエンド**: React + Vite
+- **描画**: Konva.js / Fabric.js
+- **状態管理**: Zustand
+- **UI**: Mantine / shadcn/ui
+
+### テスト
+
+- **テストランナー**: Vitest
+- **E2E**: Playwright
+
+## 実装優先度
+
+### 最優先 (2週間)
+
+1. 型定義とJSON Schema
+2. KLE → PHY変換
+3. PHY → IDX基本変換
+4. CLIでの変換確認
+
+### 高優先 (1ヶ月)
+
+1. QMK/VIA出力
+2. 基本的なWebエディタ
+3. マトリックス最適化
+
+### 中優先 (2ヶ月)
+
+1. 高度なエディタ機能
+2. プロジェクト管理
+3. 既存ツール連携
+
+## 開発環境セットアップ
+
+### 1. プロジェクト初期化
+
+```bash
+# プロジェクト作成
+mkdir beyond-kle-proto
+cd beyond-kle-proto
+
+# pnpm workspace設定
+echo 'packages:\n  - "packages/*"\n  - "tools/*"' > pnpm-workspace.yaml
+
+# TypeScript設定
+pnpm add -D typescript @types/node
+npx tsc --init
+
+# 共通依存関係
+pnpm add -D vitest ajv
+```
+
+### 2. パッケージ構成
+
+```bash
+# Core package
+mkdir -p packages/core/src/{types,validators,utils}
+cd packages/core && pnpm init
+
+# CLI tool
+mkdir -p tools/cli/src
+cd tools/cli && pnpm init
+
+# 各エディタパッケージ
+mkdir -p packages/{phy-editor,matrix-mapper,keymap-designer}
+```
+
+### 3. 開発ツール設定
+
+```bash
+# Linting & Formatting
+pnpm add -D eslint prettier @typescript-eslint/eslint-plugin
+
+# Testing
+pnpm add -D @vitest/ui
+
+# Build tools
+pnpm add -D tsup
+```
+
+## サンプルプロジェクト設計
+
+### テストケース
+
+1. **60% ANSI** - 標準的なレイアウト
+2. **Split keyboard** - 左右分離型
+3. **Ergonomic layout** - カラムスタッガード + 回転
+4. **Macro pad** - シンプルな4x4
+
+### データ例
+
+#### 60% ANSI PHY Layer
+
+```json
+{
+  "version": "1.0.0",
+  "metadata": {
+    "name": "60% ANSI",
+    "description": "Standard 60% layout"
+  },
+  "profiles": [
+    {
+      "id": "standard",
+      "name": "Cherry MX",
+      "unitSize": { "x": 19.05, "y": 19.05 }
+    }
+  ],
+  "keys": [
+    // Escape key
+    {
+      "id": "k00", "profile": "standard",
+      "position": { "x": 0, "y": 0 },
+      "size": { "width": 1, "height": 1 },
+      "metadata": { "label": "Esc" }
+    },
+    // Space bar
+    {
+      "id": "k60", "profile": "standard", 
+      "position": { "x": 5, "y": 4 },
+      "size": { "width": 6.25, "height": 1 },
+      "metadata": { "label": "Space" }
+    }
+  ]
+}
+```
+
+## 次のアクション
+
+1. **GitHub リポジトリ作成**
+2. **開発環境セットアップ**
+3. **型定義の実装開始**
+4. **KLE変換機能のプロトタイプ**
+
+実装を開始しますか？最初にどの部分から取り組みたいでしょうか？