ewdernaandClaude Opus 5
ec36a5139a
決まったことだけを書く文書にし、implementation-plan.md に改名した。 TypeScriptの採否も技術選定のやり直しに含まれるため。 本文には自作の決定と検証用サンプルを残した。データ例は旧形式なので 変換が必要と明記した(変換は後日)。技術スタック・構成・フェーズ・ 優先度・セットアップ手順はjournalに原文のまま移し、未確認事項に P-2 技術選定、P-3 リポジトリ構成を立てた。CLAUDE.md の地図も更新。 Journal: journal/2026-09-18-typescript-implementation-plan.md Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
90 lines
5.4 KiB
Markdown
90 lines
5.4 KiB
Markdown
# Beyond KLE
|
|
|
|
キーボード設計のデータモデルとワークフローを再設計するプロジェクト。
|
|
PHY(物理配置) / ELC(電気配線) / IDX(キー識別) / MAP(キーマップ) / IME(入力変換) の5層に分離する。
|
|
|
|
- 応答・ドキュメントは日本語。
|
|
- 現状はコード未着手、設計ドキュメントのみ。
|
|
|
|
## ドキュメント地図
|
|
|
|
| ファイル | 内容 |
|
|
|---|---|
|
|
| `keyboard-design-layers.md` | レイヤー構造とツール分割方針(最上位) |
|
|
| `PHYレイヤー.md` | PHY層の仕様 |
|
|
| `phase1-json-schema.md` | 各層のJSON Schema |
|
|
| `keyboard-making-workflow.md` | 既存の自作キーボード制作フローとの対応 |
|
|
| `implementation-plan.md` | 実装方針の決定事項・検証用サンプル |
|
|
|
|
**既存ドキュメントは下記ルールの策定前に書かれたもので、ルール1〜4は未適用。**
|
|
全体の再編は別タスクとして行う。それまで各ファイルをメイン/journalのどちらに分類するかは未確定なので、
|
|
指示なく移動・分割・書き直しをしない。
|
|
|
|
初期コミット以前の経緯は追跡できない。現在のドキュメント群を「初期検討段階」のベースラインとして扱い、
|
|
それ以前の決定理由を掘り起こそうとしない。
|
|
|
|
## ドキュメント運用ルール
|
|
|
|
### 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]` を付け、末尾の `## 未確認事項` に対応項目を置く
|
|
- まだ本文に書けない未解決の問い → 本文タグなしで `## 未確認事項` に直接置く
|
|
- `## 未確認事項` の各項目には、**何を確認できれば事実に格上げできるか**を必ず書く。
|
|
- 検証できたらタグを外し、該当項目を削除する。
|
|
- 「今回検討して捨てた仮説」は `## 未確認事項` に書かない。journal に残して消す。
|
|
- 推測に基づいて実装しない。先に検証するか、ユーザーに確認する。
|
|
|
|
書式:
|
|
|
|
```markdown
|
|
## 未確認事項
|
|
|
|
### P-1 KLEはlabels[9]の内容を保存時に保持する
|
|
- 位置づけ: 本文「クラスター管理」が前提にしている
|
|
- 格上げ条件: KLE本家でインポート→エクスポートし、labels[9]が残ることを確認する
|
|
```
|
|
|
|
## Claude への作業指示
|
|
|
|
- ドキュメントを更新するときは、上のルール1〜4のどこに属する情報かを判断してから書く。分類に迷うものは書く前に確認する。
|
|
- 調査タスクの結果は、結論だけをメインドキュメントに書き、調査過程は `journal/` に落とす。
|
|
- 既存ドキュメントの記述と食い違う事実を見つけたら、勝手に上書きせず指摘する。
|
|
|
|
## 未確認事項
|
|
|
|
(なし)
|