chore: Markdownのインデント幅を4に固定し、リストの継続行をスペース4つに揃える
継続行がスペース2つだと、VS Codeがインデント幅を2と自動判定する。 .vscode/settings.json でMarkdownの自動判定を切って幅4に固定し、 既存の継続行もリストの記号から4つ下げた位置に揃える。 変更したファイルに markdownlint --fix をかけた分(journalのURL囲みと空行)も含む。 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VbfgHT848s3JbuFw8MKFF8
This commit is contained in:
@@ -9,7 +9,7 @@ PHY(物理配置) / ELC(電気配線) / IDX(キー識別) / MAP(キーマップ)
|
||||
## ドキュメント地図
|
||||
|
||||
| ファイル | 内容 |
|
||||
|---|---|
|
||||
| --- | --- |
|
||||
| `keyboard-design-layers.md` | レイヤー構造とツール分割方針(最上位) |
|
||||
| `PHYレイヤー.md` | PHY層の仕様 |
|
||||
| `ELCレイヤー.md` | ELC層の仕様 |
|
||||
@@ -40,13 +40,13 @@ PHY(物理配置) / ELC(電気配線) / IDX(キー識別) / MAP(キーマップ)
|
||||
- 複数案から選んだ場合、「なぜAなのか」を1〜3行で書く。「なぜBではないのか」は書かない。
|
||||
- 却下案の比較表・検討過程・ベンチマーク結果はここに置かない(→ `journal/`)。
|
||||
- 却下案の再提案を防ぐ情報は、比較ではなく**制約文**として書く。
|
||||
- ✗ `B案はKLEパーサーが壊れるので却下した`
|
||||
- ○ `クラスター情報はKLE JSONに出力しない(KLE互換性の制約)`
|
||||
- ✗ `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行まで。増えたら、再提案を防ぐ必要性が低いものから落とす。長くなるのは書きすぎのサイン。
|
||||
- 例: `- labels[9] へのID埋め込み (journal/2026-09-16-cluster-metadata.md)`
|
||||
- コミットは `git log --oneline -- journal/2026-09-16-cluster-metadata.md` で引ける(journal削除後も追跡可)
|
||||
- 載せるのは、実際に検討した別方針のうち再提案されうるものに限る。本文の制約文で足りるなら重複させない。
|
||||
- 目安5行まで。増えたら、再提案を防ぐ必要性が低いものから落とす。長くなるのは書きすぎのサイン。
|
||||
|
||||
### 2. 履歴と根拠
|
||||
|
||||
@@ -54,13 +54,13 @@ PHY(物理配置) / ELC(電気配線) / IDX(キー識別) / MAP(キーマップ)
|
||||
- **なぜそう決めたか / 調査 / 案の比較** → `journal/` に置き、その決定と**同じコミット**に含める。
|
||||
- コミットメッセージ末尾に参照を1行入れる: `Journal: journal/2026-09-16-cluster-metadata.md`
|
||||
- journal は作業ツリーから削除する前提(人間にとってのノイズになるため)。履歴には残るので、
|
||||
削除後は `git show <sha>:journal/...` で読む。
|
||||
削除後は `git show <sha>:journal/...` で読む。
|
||||
|
||||
### 3. journal の書き方
|
||||
|
||||
- 1ファイル1トピック。`journal/YYYY-MM-DD-<topic>.md`。トピックを詰め込まない。
|
||||
- 構成は上から順に: **結論** → **案の比較(簡潔な表)** → 検証ログ・根拠・捨てた案。
|
||||
冒頭20行で結論と選択肢が分かること。
|
||||
冒頭20行で結論と選択肢が分かること。
|
||||
- 他のファイルから journal へリンクを張らない。journal 同士も張らない。参照経路はコミットメッセージのみ。
|
||||
- 結論がメインドキュメントに反映されたら削除してよい。
|
||||
- 整形は最低限でよい。人間向けの読みやすさは要求しない。
|
||||
@@ -68,15 +68,15 @@ PHY(物理配置) / ELC(電気配線) / IDX(キー識別) / MAP(キーマップ)
|
||||
### 4. 事実と推測
|
||||
|
||||
- **裏取りの済んだ事実**は、ドキュメント内のどこに書いてもよい。文中に自然に混ぜてよい。
|
||||
ただし同じ事実を複数ドキュメントに複製しない。必要ならリンクする。
|
||||
ただし同じ事実を複数ドキュメントに複製しない。必要ならリンクする。
|
||||
- **現在の仕様・実装が答えに依存する未確認事項**は、仕様書の末尾に残す。2種類ある:
|
||||
- 本文が前提にしている推測 → 本文に `[推測:P-n]` を付け、末尾の `## 未確認事項` に対応項目を置く
|
||||
- 実装前に判断が必要な未解決の問い → 本文タグなしで `## 未確認事項` に直接置く
|
||||
- 本文が前提にしている推測 → 本文に `[推測:P-n]` を付け、末尾の `## 未確認事項` に対応項目を置く
|
||||
- 実装前に判断が必要な未解決の問い → 本文タグなしで `## 未確認事項` に直接置く
|
||||
- 本文が未決の問いに触れるときは、「未決」と書いて終わらせず該当項目へリンクする。
|
||||
同一ファイル内は `[P-3](#p-3-...)`、他ファイルからは `[MAPのP-3](MAPレイヤー.md#p-3-...)` の形とする。
|
||||
問いの内容は `## 未確認事項` にだけ書き、本文へ写さない(二重管理を避ける)。
|
||||
同一ファイル内は `[P-3](#p-3-...)`、他ファイルからは `[MAPのP-3](MAPレイヤー.md#p-3-...)` の形とする。
|
||||
問いの内容は `## 未確認事項` にだけ書き、本文へ写さない(二重管理を避ける)。
|
||||
- 未確認の推測には、**何を確認できれば事実に格上げできるか**を「格上げ条件」として書く。
|
||||
設計判断には、**何を決めれば解決するか**を「完了条件」として書く。意思決定を事実確認と混同しない。
|
||||
設計判断には、**何を決めれば解決するか**を「完了条件」として書く。意思決定を事実確認と混同しない。
|
||||
- 答えに依存せず進められる課題は `backlog/` に置く(ルール5)。保留中の対応範囲・暫定仕様は仕様書に残す。
|
||||
- 検証できたらタグを外し、該当項目を削除する。
|
||||
- 「今回検討して捨てた仮説」は `## 未確認事項` に書かない。journal に残して消す。
|
||||
@@ -98,20 +98,20 @@ PHY(物理配置) / ELC(電気配線) / IDX(キー識別) / MAP(キーマップ)
|
||||
|
||||
- 当面は `backlog/README.md` にまとめる。増えて読みにくくなったらレイヤー別・トピック別に分ける。
|
||||
- 項目には、関連仕様・未決事項・保留できる理由・再開条件・完了条件を書く。
|
||||
再開条件は「いつ考え直すか」、完了条件は「何を確認または決定すれば終わるか」を示す。
|
||||
再開条件は「いつ考え直すか」、完了条件は「何を確認または決定すれば終わるか」を示す。
|
||||
- 仕様書から移す項目は、元の番号にレイヤー名などを付けて識別する(例: `PHY-P-14`)。
|
||||
判断に必要な候補や制約は短く残す。長い比較・調査ログは `journal/` に置く。
|
||||
判断に必要な候補や制約は短く残す。長い比較・調査ログは `journal/` に置く。
|
||||
- 問いの本文は二重管理しない。仕様書には保留中の対応範囲・暫定仕様を残し、必要に応じてbacklogへリンクする。
|
||||
- 仕様書から保留課題を分離した場合、末尾の管理セクションを `## 保留課題` → `## 検討済み・非採用` →
|
||||
`## 未確認事項` の順に置く(存在するものだけ)。`## 保留課題` には下記のリンク箇条書きだけを書く。
|
||||
項目名の列挙・問いの要約・保留理由・対応範囲は書かない。対応範囲は仕様本文、問いの詳細はbacklogに置く。
|
||||
`## 未確認事項` の順に置く(存在するものだけ)。`## 保留課題` には下記のリンク箇条書きだけを書く。
|
||||
項目名の列挙・問いの要約・保留理由・対応範囲は書かない。対応範囲は仕様本文、問いの詳細はbacklogに置く。
|
||||
- リンクは `- [<区分>の保留課題](backlog/README.md#<区分の見出し>)` の形とする。
|
||||
分割後は該当するbacklogファイルへ向ける。複数区分を参照する場合は1リンク1行とし、参照先の見出しまで指定する。
|
||||
該当課題がなくなったらリンクを削除し、空になった `## 保留課題` はセクションごと削除する。
|
||||
分割後は該当するbacklogファイルへ向ける。複数区分を参照する場合は1リンク1行とし、参照先の見出しまで指定する。
|
||||
該当課題がなくなったらリンクを削除し、空になった `## 保留課題` はセクションごと削除する。
|
||||
- 現在の仕様が依存する未確認の前提は、backlogへ移して隠さない。仕様書の `## 未確認事項` に残す。
|
||||
- backlogへの移動は仮説の採用や実装の許可を意味しない。実装は採用済みの仕様・対応範囲に従う。
|
||||
- 解決したら必要な結論を仕様書へ反映し、項目と不要になった参照を削除する。取り下げた項目も削除し、完了一覧は蓄積しない。
|
||||
調査・判断の経緯はルール2・3に従って履歴に残す。
|
||||
調査・判断の経緯はルール2・3に従って履歴に残す。
|
||||
- 未解決の課題は作業ツリーに残す。結論反映後に削除できるjournalとは寿命が異なる。
|
||||
|
||||
仕様書側の書式:
|
||||
@@ -128,8 +128,8 @@ PHY(物理配置) / ELC(電気配線) / IDX(キー識別) / MAP(キーマップ)
|
||||
- 調査タスクの結果は、結論だけをメインドキュメントに書き、調査過程は `journal/` に落とす。
|
||||
- 既存ドキュメントの記述と食い違う事実を見つけたら、勝手に上書きせず指摘する。
|
||||
- Markdownをコミットする前に、変更したファイルへ `npx markdownlint-cli2 --fix <files>` をかける。
|
||||
エディタが保存時に同じ修正を入れるため、かけずにコミットするとコミット直後に差分が出る。
|
||||
規則は `.markdownlint.jsonc`。変更していないファイルの指摘は直さない。
|
||||
エディタが保存時に同じ修正を入れるため、かけずにコミットするとコミット直後に差分が出る。
|
||||
規則は `.markdownlint.jsonc`。変更していないファイルの指摘は直さない。
|
||||
|
||||
## 未確認事項
|
||||
|
||||
|
||||
Reference in New Issue
Block a user