docs: 保留課題をbacklogへ分離し、運用ルール5を追加

未確認事項が「現在の仕様が答えに依存するもの」と「答えが出なくても進められる
もの」を混ぜて抱えていた。後者を backlog/README.md へ移し、仕様書の未確認事項を
前者だけに絞る。移す際は保留中の対応範囲・暫定仕様を仕様書本文に明記し、
backlogへの移動が仮説の採用を意味しないようにする。

PHY・ELC・IDXの10件を移し、3ファイルとも未確認事項が空になった。
ルール4では、事実確認の「格上げ条件」と意思決定の「完了条件」を区別する。
仕様書側の保留課題はbacklogの区分へのリンク箇条書きだけに固定し、
末尾は保留課題 → 検討済み・非採用 → 未確認事項の順に置く。

doc-lintをルール5に対応させ、backlogを検査対象に加えた。回帰テストを追加。

Journal: journal/2026-09-22-document-backlog.md

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DKW58HEg8zAQoLrkWByPfD
This commit is contained in:
2026-09-22 19:52:39 +09:00
co-authored by Claude Opus 5
parent 66a594a378
commit 5b671976d5
10 changed files with 535 additions and 102 deletions
+42 -7
View File
@@ -17,16 +17,19 @@ PHY(物理配置) / ELC(電気配線) / IDX(キー識別) / MAP(キーマップ)
| `phase1-json-schema.md` | 各層のJSON Schema |
| `keyboard-making-workflow.md` | 既存の自作キーボード制作フローとの対応 |
| `implementation-plan.md` | 実装方針の決定事項・検証用サンプル |
| [`backlog/README.md`](backlog/README.md) | 後回しにできる問い・検証・改善候補 |
**既存ドキュメントは下記ルールの策定前に書かれたもので、ルール1〜4は未適用。**
全体の再編は別タスクとして行う。それまで各ファイルをメイン/journalのどちらに分類するかは未確定なので、
指示なく移動・分割・書き直しをしない。
既存ドキュメントには下記ルールを段階的に適用する。PHY・ELC・IDXの保留課題はbacklogへ分離済み。
全体の再編は別タスクとして行い、指示なく他の内容を移動・分割・書き直ししない。
初期コミット以前の経緯は追跡できない。現在のドキュメント群を「初期検討段階」のベースラインとして扱い、
それ以前の決定理由を掘り起こそうとしない。
## ドキュメント運用ルール
現在の仕様・将来取り組む課題・過去の検討を分け、仕様を読む際に判断状況が混ざらないようにする。
未確認の前提は確定事項と区別し、保留課題は再開するまで見つけられる状態に保つ。
### 1. メインドキュメント(リポジトリ直下の `*.md`)
書くもの: **採用した案 / 現在の設定 / 設計に影響する制約**。
@@ -62,10 +65,12 @@ PHY(物理配置) / ELC(電気配線) / IDX(キー識別) / MAP(キーマップ)
- **裏取りの済んだ事実**は、ドキュメント内のどこに書いてもよい。文中に自然に混ぜてよい。
ただし同じ事実を複数ドキュメントに複製しない。必要ならリンクする。
- **未確認の推測**だけを末尾に隔離する。2種類ある:
- **現在の仕様・実装が答えに依存する未確認事項**は、仕様書の末尾に残す。2種類ある:
- 本文が前提にしている推測 → 本文に `[推測:P-n]` を付け、末尾の `## 未確認事項` に対応項目を置く
- まだ本文に書けない未解決の問い → 本文タグなしで `## 未確認事項` に直接置く
- `## 未確認事項` の各項目には、**何を確認できれば事実に格上げできるか**を必ず書く。
- 実装前に判断が必要な未解決の問い → 本文タグなしで `## 未確認事項` に直接置く
- 未確認の推測には、**何を確認できれば事実に格上げできるか**を「格上げ条件」として書く。
設計判断には、**何を決めれば解決するか**を「完了条件」として書く。意思決定を事実確認と混同しない。
- 答えに依存せず進められる課題は `backlog/` に置く(ルール5)。保留中の対応範囲・暫定仕様は仕様書に残す。
- 検証できたらタグを外し、該当項目を削除する。
- 「今回検討して捨てた仮説」は `## 未確認事項` に書かない。journal に残して消す。
- 推測に基づいて実装しない。先に検証するか、ユーザーに確認する。
@@ -80,9 +85,39 @@ PHY(物理配置) / ELC(電気配線) / IDX(キー識別) / MAP(キーマップ)
- 格上げ条件: 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とは寿命が異なる。
仕様書側の書式:
```markdown
## 保留課題
- [PHYの保留課題](backlog/README.md#phy)
```
## Claude への作業指示
- ドキュメントを更新するときは、上のルール1〜4のどこに属する情報かを判断してから書く。分類に迷うものは書く前に確認する。
- ドキュメントを更新するときは、上のルール1〜5のどこに属する情報かを判断してから書く。分類に迷うものは書く前に確認する。
- 調査タスクの結果は、結論だけをメインドキュメントに書き、調査過程は `journal/` に落とす。
- 既存ドキュメントの記述と食い違う事実を見つけたら、勝手に上書きせず指摘する。