Beyond-KLE/CLAUDE.md

Beyond KLE

キーボード設計のデータモデルとワークフローを再設計するプロジェクト。 PHY(物理配置) / ELC(電気配線) / IDX(キー識別) / MAP(キーマップ) / HST(ホスト) の5層に分離する。

• 応答・ドキュメントは日本語。
• 現状はコード未着手、設計ドキュメントのみ。

ドキュメント地図

ファイル	内容
keyboard-design-layers.md	レイヤー構造とツール分割方針(最上位)
PHYレイヤー.md	PHY層の仕様
ELCレイヤー.md	ELC層の仕様
IDXレイヤー.md	IDX層の仕様
MAPレイヤー.md	MAP層とエディタの責務・実機との読み書き方針
HSTレイヤー.md	HST層(ホストによるキーコードの解釈)の仕様
phase1-json-schema.md	各層のJSON Schema
keyboard-making-workflow.md	既存の自作キーボード制作フローとの対応
implementation-plan.md	実装方針の決定事項・検証用サンプル
backlog/README.md	後回しにできる問い・検証・改善候補
samples/	検証用サンプル(KLE JSON、VIA定義)。出典とテストケースは implementation-plan.md

既存ドキュメントには下記ルールを段階的に適用する。PHY・ELC・IDXの保留課題はbacklogへ分離済み。 全体の再編は別タスクとして行い、指示なく他の内容を移動・分割・書き直ししない。

初期コミット以前の経緯は追跡できない。現在のドキュメント群を「初期検討段階」のベースラインとして扱い、 それ以前の決定理由を掘り起こそうとしない。

ドキュメント運用ルール

現在の仕様・将来取り組む課題・過去の検討を分け、仕様を読む際に判断状況が混ざらないようにする。 未確認の前提は確定事項と区別し、保留課題は再開するまで見つけられる状態に保つ。

1. メインドキュメント(リポジトリ直下の *.md)

書くもの: 採用した案 / 現在の設定 / 設計に影響する制約。

• 複数案から選んだ場合、「なぜAなのか」を1〜3行で書く。「なぜBではないのか」は書かない。
• 却下案の比較表・検討過程・ベンチマーク結果はここに置かない(→ journal/)。
• 却下案の再提案を防ぐ情報は、比較ではなく制約文として書く。
  • ✗ B案はKLEパーサーが壊れるので却下した
  • ○ クラスター情報はKLE JSONに出力しない(KLE互換性の制約)
• 落とした案があれば、末尾に ## 検討済み・非採用 を置き、1案1行で残す。理由は書かず、journalファイル名を参照する。
  • 例: - labels[9] へのID埋め込み (journal/2026-09-16-cluster-metadata.md)
  • コミットは git log --oneline -- journal/2026-09-16-cluster-metadata.md で引ける(journal削除後も追跡可)
  • 載せるのは、実際に検討した別方針のうち再提案されうるものに限る。本文の制約文で足りるなら重複させない。
  • 目安5行まで。増えたら、再提案を防ぐ必要性が低いものから落とす。長くなるのは書きすぎのサイン。

2. 履歴と根拠

• 何を変えたか + 理由数行 → コミットメッセージ。git log --oneline で意思決定の流れが追えること。1コミット1決定。
• なぜそう決めたか / 調査 / 案の比較 → journal/ に置き、その決定と同じコミットに含める。
• コミットメッセージ末尾に参照を1行入れる: Journal: journal/2026-09-16-cluster-metadata.md
• journal は作業ツリーから削除する前提(人間にとってのノイズになるため)。履歴には残るので、 削除後は git show <sha>:journal/... で読む。

3. journal の書き方

• 1ファイル1トピック。journal/YYYY-MM-DD-<topic>.md。トピックを詰め込まない。
• 構成は上から順に: 結論 → 案の比較(簡潔な表) → 検証ログ・根拠・捨てた案。 冒頭20行で結論と選択肢が分かること。
• 他のファイルから journal へリンクを張らない。journal 同士も張らない。参照経路はコミットメッセージのみ。
• 結論がメインドキュメントに反映されたら削除してよい。
• 整形は最低限でよい。人間向けの読みやすさは要求しない。

4. 事実と推測

• 裏取りの済んだ事実は、ドキュメント内のどこに書いてもよい。文中に自然に混ぜてよい。 ただし同じ事実を複数ドキュメントに複製しない。必要ならリンクする。
• 現在の仕様・実装が答えに依存する未確認事項は、仕様書の末尾に残す。2種類ある:
  • 本文が前提にしている推測 → 本文に [推測:P-n] を付け、末尾の ## 未確認事項 に対応項目を置く
  • 実装前に判断が必要な未解決の問い → 本文タグなしで ## 未確認事項 に直接置く
• 本文が未決の問いに触れるときは、「未決」と書いて終わらせず該当項目へリンクする。 同一ファイル内は [P-3](#p-3-...)、他ファイルからは [MAPのP-3](MAPレイヤー.md#p-3-...) の形とする。 問いの内容は ## 未確認事項 にだけ書き、本文へ写さない(二重管理を避ける)。
• 未確認の推測には、何を確認できれば事実に格上げできるかを「格上げ条件」として書く。 設計判断には、何を決めれば解決するかを「完了条件」として書く。意思決定を事実確認と混同しない。
• 答えに依存せず進められる課題は backlog/ に置く(ルール5)。保留中の対応範囲・暫定仕様は仕様書に残す。
• 検証できたらタグを外し、該当項目を削除する。
• 「今回検討して捨てた仮説」は ## 未確認事項 に書かない。journal に残して消す。
• 推測に基づいて実装しない。先に検証するか、ユーザーに確認する。

書式:

## 未確認事項

### P-1 KLEはlabels[9]の内容を保存時に保持する
- 位置づけ: 本文「クラスター管理」が前提にしている
- 格上げ条件: KLE本家でインポート→エクスポートし、labels[9]が残ることを確認する

5. 保留課題(backlog/)

書くもの: 今は解決しなくても進められる問い・検証・改善候補。

• 当面は backlog/README.md にまとめる。増えて読みにくくなったらレイヤー別・トピック別に分ける。
• 項目には、関連仕様・未決事項・保留できる理由・再開条件・完了条件を書く。 再開条件は「いつ考え直すか」、完了条件は「何を確認または決定すれば終わるか」を示す。
• 仕様書から移す項目は、元の番号にレイヤー名などを付けて識別する(例: PHY-P-14)。 判断に必要な候補や制約は短く残す。長い比較・調査ログは journal/ に置く。
• 問いの本文は二重管理しない。仕様書には保留中の対応範囲・暫定仕様を残し、必要に応じてbacklogへリンクする。
• 仕様書から保留課題を分離した場合、末尾の管理セクションを ## 保留課題 → ## 検討済み・非採用 → ## 未確認事項 の順に置く(存在するものだけ)。## 保留課題 には下記のリンク箇条書きだけを書く。 項目名の列挙・問いの要約・保留理由・対応範囲は書かない。対応範囲は仕様本文、問いの詳細はbacklogに置く。
• リンクは - [<区分>の保留課題](backlog/README.md#<区分の見出し>) の形とする。 分割後は該当するbacklogファイルへ向ける。複数区分を参照する場合は1リンク1行とし、参照先の見出しまで指定する。 該当課題がなくなったらリンクを削除し、空になった ## 保留課題 はセクションごと削除する。
• 現在の仕様が依存する未確認の前提は、backlogへ移して隠さない。仕様書の ## 未確認事項 に残す。
• backlogへの移動は仮説の採用や実装の許可を意味しない。実装は採用済みの仕様・対応範囲に従う。
• 解決したら必要な結論を仕様書へ反映し、項目と不要になった参照を削除する。取り下げた項目も削除し、完了一覧は蓄積しない。 調査・判断の経緯はルール2・3に従って履歴に残す。
• 未解決の課題は作業ツリーに残す。結論反映後に削除できるjournalとは寿命が異なる。

仕様書側の書式:

## 保留課題

- [PHYの保留課題](backlog/README.md#phy)

Claude への作業指示

• ドキュメントを更新するときは、上のルール1〜5のどこに属する情報かを判断してから書く。分類に迷うものは書く前に確認する。
• 調査タスクの結果は、結論だけをメインドキュメントに書き、調査過程は journal/ に落とす。
• 既存ドキュメントの記述と食い違う事実を見つけたら、勝手に上書きせず指摘する。

未確認事項

(なし)