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:
Claude Opus 5
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: doc-lint
|
||||
description: ドキュメントがCLAUDE.mdの運用ルール1〜4に沿っているか検査する。推測タグと未確認事項の対応漏れ、journalへのリンク、比較表の混入などを検出する。
|
||||
description: ドキュメントがCLAUDE.mdの運用ルール1〜5に沿っているか検査する。推測タグと未確認事項の対応漏れ、保留課題の書式・参照・必須欄、journalへのリンク、比較表の混入などを検出する。
|
||||
argument-hint: [ファイル...]
|
||||
---
|
||||
|
||||
@@ -15,15 +15,22 @@ argument-hint: [ファイル...]
|
||||
python .claude/skills/doc-lint/doc-lint.py [ファイル...]
|
||||
```
|
||||
|
||||
引数なしで直下の `*.md` と `journal/*.md` を全部見る。ERROR があれば終了コード 1。
|
||||
Python 3.9以上で実行する。引数なしでリポジトリ直下の `*.md`、`journal/*.md`、`backlog/**/*.md` を全部見る。
|
||||
実行場所にかかわらずリポジトリを基準に分類し、明示したパスは実行ディレクトリから解決する。
|
||||
ERROR があれば終了コード 1。存在しない引数のファイルもERRORにする。
|
||||
|
||||
検出する項目:
|
||||
|
||||
| 種別 | 内容 |
|
||||
|---|---|
|
||||
| ERROR | 本文の `[推測:P-n]` に対応する `## 未確認事項` の項目がない |
|
||||
| ERROR | `## 未確認事項` の項目に `- 格上げ条件:` の行がない |
|
||||
| ERROR | 本文の推測タグに対応する項目に `- 格上げ条件:` の内容がない |
|
||||
| ERROR | タグのない未確認事項に `- 格上げ条件:` または `- 完了条件:` の内容がない |
|
||||
| ERROR | `## 未確認事項` のIDが重複している |
|
||||
| ERROR | 仕様書の `## 保留課題` がリンク箇条書き以外を含む、空である、参照先ファイル・見出しがない |
|
||||
| ERROR | 末尾の管理セクションが重複する、保留課題 → 検討済み・非採用 → 未確認事項の順でない |
|
||||
| ERROR | backlogの項目IDが不正・検査対象内で重複する、必須5欄がない・空である |
|
||||
| ERROR | backlogに推測タグがある、参照先ファイルが存在しない |
|
||||
| ERROR | journal へのリンク / journal から他ファイルへのリンク |
|
||||
| ERROR | `## 検討済み・非採用` の項目が journal ファイル名を参照していない |
|
||||
| ERROR | journal のファイル名が `YYYY-MM-DD-<topic>.md` 形式でない |
|
||||
@@ -31,7 +38,12 @@ python .claude/skills/doc-lint/doc-lint.py [ファイル...]
|
||||
| WARN | journal の冒頭20行に結論が見当たらない |
|
||||
| WARN | メインドキュメントに比較表・優先度評価・却下案の記述らしきもの |
|
||||
|
||||
**本文タグのない `## 未確認事項` の項目はエラーにしない。** 「まだ本文に書けない未解決の問い」として正当。
|
||||
**本文タグのない `## 未確認事項` の項目はエラーにしない。** 実装前に判断が必要な未解決の問いとして正当。
|
||||
設計判断は「完了条件」でよい。タグなしの項目が事実確認なのか設計判断なのかは、目視で確認する。
|
||||
|
||||
backlogでは `### PHY-P-14 題名` のように区分付きIDを使い、関連仕様・未決事項・保留できる理由・再開条件・完了条件を必須とする。
|
||||
仕様書側の書式は `- [PHYの保留課題](backlog/README.md#phy)`。
|
||||
backlogは短い候補・制約を保持できるため、メインドキュメント向けの散文ヒューリスティックは適用しない。
|
||||
|
||||
WARN の散文検出は当たりが粗い。取りこぼしも誤検出もあるので、出た/出ないを結論にしない。
|
||||
|
||||
@@ -43,10 +55,12 @@ WARN の散文検出は当たりが粗い。取りこぼしも誤検出もある
|
||||
却下理由ではなく、現在効いている制約として書かれているか。
|
||||
- ✗ `階層構造はKLEが非対応なので諦めた`
|
||||
- ○ `階層クラスターはKLE JSONに出力しない(KLE互換性の制約)`
|
||||
- **裏取りしていない記述にタグが付いていないか。** 検査項目の中で最も重要で、
|
||||
- **本文が前提にする未確認の記述にタグが付いているか。** 検査項目の中で最も重要で、
|
||||
機械では判定できない。「〜できるはず」「〜と考えられる」「実現可能」で実際に試していない
|
||||
記述を探し、`[推測:P-n]` が付いているか確認する。
|
||||
- **同じ事実が複数ドキュメントに複製されていないか。** 片方だけ古くなる。
|
||||
- **保留中の対応範囲が仕様本文にあるか。** 現在の実装が答えに依存する前提をbacklogへ隠していないか。
|
||||
- **再開条件・完了条件が具体的か。** 仕様書の保留課題リンクは該当区分に向き、解決済みの課題が残っていないか。
|
||||
- **journal の冒頭20行で、結論と選択肢が分かるか。** 見出しの有無ではなく中身を読む。
|
||||
- **コミット規約**(必要なら `git log --oneline` を見る)
|
||||
- 1コミット1決定になっているか
|
||||
@@ -59,6 +73,12 @@ ERROR / WARN / 目視で見つけたもの を分けて出す。
|
||||
|
||||
## 注意
|
||||
|
||||
- 運用ルール策定前に書かれた既存ドキュメントは、まだルール1〜4が適用されていない。
|
||||
- 既存ドキュメントへのルール適用は段階的に進めている。
|
||||
WARN が大量に出るのは想定内で、再編(`/restructure-doc`)のタイミングで解消する。
|
||||
再編前のファイルの WARN を個別に直そうとしない。
|
||||
|
||||
スクリプトを変更した場合の回帰検査:
|
||||
|
||||
```
|
||||
python -B -m unittest discover -s .claude/skills/doc-lint -p test_doc_lint.py
|
||||
```
|
||||
|
||||
@@ -1,16 +1,17 @@
|
||||
#!/usr/bin/env python3
|
||||
# -*- coding: utf-8 -*-
|
||||
"""CLAUDE.md の運用ルール1〜4のうち、機械的に判定できる項目を検査する。
|
||||
"""CLAUDE.md の運用ルール1〜5のうち、機械的に判定できる項目を検査する。
|
||||
|
||||
使い方:
|
||||
python .claude/skills/doc-lint/doc-lint.py [ファイル...]
|
||||
引数なしなら リポジトリ直下の *.md と journal/*.md を対象にする。
|
||||
引数なしならリポジトリ直下の *.md、journal/*.md、backlog/**/*.md が対象。
|
||||
明示したパスは実行ディレクトリから解決する。
|
||||
ERROR が1件でもあれば終了コード 1。
|
||||
"""
|
||||
import sys, re, os, io, glob
|
||||
|
||||
if hasattr(sys.stdout, "reconfigure"):
|
||||
sys.stdout.reconfigure(encoding="utf-8")
|
||||
import re
|
||||
import sys
|
||||
from pathlib import Path
|
||||
from urllib.parse import unquote, urlsplit
|
||||
|
||||
TAG = re.compile(r"\[推測:(P-\d+)\]")
|
||||
ENTRY = re.compile(r"^###\s+(P-\d+)\b")
|
||||
@@ -18,6 +19,12 @@ H2 = re.compile(r"^##\s+(.*?)\s*$")
|
||||
MDLINK = re.compile(r"\]\(([^)]+\.md[^)]*)\)")
|
||||
JOURNALFN= re.compile(r"^\d{4}-\d{2}-\d{2}-.+\.md$")
|
||||
PROMOTE = re.compile(r"^\s*[-*]\s*格上げ条件\s*[:：]\s*\S")
|
||||
COMPLETE = re.compile(r"^\s*[-*]\s*完了条件\s*[:：]\s*\S")
|
||||
BACKLOG_ENTRY = re.compile(r"^###\s+([A-Za-z][A-Za-z0-9_-]*-P-\d+)\s+\S")
|
||||
BACKLOG_LINK = re.compile(r"^- \[[^\]]+の保留課題\]\(([^)]+)\)$")
|
||||
BACKLOG_FIELDS = ("関連仕様", "未決事項", "保留できる理由", "再開条件", "完了条件")
|
||||
MANAGEMENT_SECTIONS = ("保留課題", "検討済み・非採用", "未確認事項")
|
||||
ROOT = Path(__file__).resolve().parents[3]
|
||||
|
||||
# ルールブック自身は、アンチパターンを例として引用するため散文ヒューリスティックの対象外
|
||||
PROSE_EXEMPT = {"CLAUDE.md"}
|
||||
@@ -28,7 +35,7 @@ def add(sev, path, line, msg):
|
||||
|
||||
def load(path):
|
||||
"""コードフェンス内を空行に潰した (行番号, 本文) の列を返す。"""
|
||||
raw = io.open(path, encoding="utf-8").read().splitlines()
|
||||
raw = Path(path).read_text(encoding="utf-8").splitlines()
|
||||
out, fence = [], False
|
||||
for i, l in enumerate(raw, 1):
|
||||
if l.lstrip().startswith("```"):
|
||||
@@ -55,15 +62,109 @@ def section(lines, title):
|
||||
body.append((n, l))
|
||||
return body
|
||||
|
||||
def check(path):
|
||||
rel = path.replace(os.sep, "/")
|
||||
base = os.path.basename(rel)
|
||||
is_journal = rel.startswith("journal/")
|
||||
def local_target(path, target):
|
||||
"""相対リンクをリンク元基準で解決する。外部URLは対象外。"""
|
||||
parsed = urlsplit(target)
|
||||
if parsed.scheme or parsed.netloc:
|
||||
return None, ""
|
||||
linked = (path.parent / unquote(parsed.path)).resolve() if parsed.path else path
|
||||
return linked, unquote(parsed.fragment)
|
||||
|
||||
|
||||
def check_backlog(path, rel, lines, seen_ids):
|
||||
blocks = []
|
||||
current = None
|
||||
for n, line in lines:
|
||||
if H2.match(line):
|
||||
current = None
|
||||
elif re.match(r"^###\s", line):
|
||||
match = BACKLOG_ENTRY.match(line)
|
||||
current = None
|
||||
if not match:
|
||||
add("ERROR", rel, n, "保留課題の見出しは ### <区分>-P-<番号> <題名> とする")
|
||||
continue
|
||||
pid = match.group(1)
|
||||
if pid in seen_ids:
|
||||
add("ERROR", rel, n, "保留課題のID %s が重複している(初出: %s)" % (pid, seen_ids[pid]))
|
||||
seen_ids[pid] = "%s:%d" % (rel, n)
|
||||
current = (pid, n, [])
|
||||
blocks.append(current)
|
||||
elif current is not None:
|
||||
current[2].append(line)
|
||||
|
||||
for pid, n, body in blocks:
|
||||
for field in BACKLOG_FIELDS:
|
||||
pattern = re.compile(r"^[-*]\s+" + re.escape(field) + r"\s*[:：]\s*\S")
|
||||
if not any(pattern.match(line) for line in body):
|
||||
add("ERROR", rel, n, "%s に「- %s:」の内容がない" % (pid, field))
|
||||
|
||||
for n, line in lines:
|
||||
if TAG.search(line):
|
||||
add("ERROR", rel, n, "本文の前提となる推測タグはbacklogではなく仕様書に置く")
|
||||
for target in MDLINK.findall(line):
|
||||
linked, _ = local_target(path, target)
|
||||
if linked is not None and not linked.is_file():
|
||||
add("ERROR", rel, n, "backlogの参照先ファイルがない: %s" % target)
|
||||
|
||||
|
||||
def check_backlog_section(path, rel, lines):
|
||||
positions = []
|
||||
for title in MANAGEMENT_SECTIONS:
|
||||
headings = [n for n, line in lines if H2.match(line) and H2.match(line).group(1) == title]
|
||||
if len(headings) > 1:
|
||||
add("ERROR", rel, headings[1], "## %s が重複している" % title)
|
||||
if headings:
|
||||
positions.append(headings[0])
|
||||
if positions != sorted(positions):
|
||||
add("ERROR", rel, min(positions), "末尾の管理セクションは保留課題 → 検討済み・非採用 → 未確認事項の順に置く")
|
||||
|
||||
deferred = section(lines, "保留課題")
|
||||
if deferred is None:
|
||||
return
|
||||
contents = [(n, line) for n, line in deferred if line.strip()]
|
||||
if not contents:
|
||||
add("ERROR", rel, 1, "空の ## 保留課題 はセクションごと削除する")
|
||||
for n, line in contents:
|
||||
match = BACKLOG_LINK.fullmatch(line)
|
||||
if not match:
|
||||
add("ERROR", rel, n, "保留課題には - [<区分>の保留課題](backlogのファイル#見出し) だけを書く")
|
||||
continue
|
||||
target = match.group(1)
|
||||
linked, anchor = local_target(path, target)
|
||||
if (linked is None or not linked.is_relative_to(ROOT / "backlog")
|
||||
or linked.suffix != ".md" or not anchor):
|
||||
add("ERROR", rel, n, "保留課題はbacklog内のMarkdownファイルの見出しへリンクする: %s" % target)
|
||||
continue
|
||||
if not linked.is_file():
|
||||
add("ERROR", rel, n, "保留課題の参照先ファイルがない: %s" % target)
|
||||
continue
|
||||
headings = set()
|
||||
for _, linked_line in load(linked):
|
||||
heading = re.match(r"^#{1,6}\s+(.+?)\s*#*\s*$", linked_line)
|
||||
if heading:
|
||||
slug = re.sub(r"[^\w\s-]", "", heading.group(1)).lower().replace(" ", "-")
|
||||
headings.add(slug)
|
||||
if anchor not in headings:
|
||||
add("ERROR", rel, n, "保留課題の参照先見出しがない: %s" % target)
|
||||
|
||||
|
||||
def check(path, seen_backlog_ids=None):
|
||||
path = Path(path).resolve()
|
||||
rel = path.relative_to(ROOT).as_posix() if path.is_relative_to(ROOT) else path.as_posix()
|
||||
base = path.name
|
||||
is_journal = path.is_relative_to(ROOT / "journal")
|
||||
is_backlog = path.is_relative_to(ROOT / "backlog")
|
||||
lines = load(path)
|
||||
|
||||
if is_backlog:
|
||||
check_backlog(path, rel, lines, seen_backlog_ids if seen_backlog_ids is not None else {})
|
||||
elif not is_journal:
|
||||
check_backlog_section(path, rel, lines)
|
||||
|
||||
unconf = section(lines, "未確認事項")
|
||||
rejected = section(lines, "検討済み・非採用")
|
||||
unconf_span = set(n for n, _ in unconf) if unconf else set()
|
||||
tagged = {pid for n, line in lines if n not in unconf_span for pid in TAG.findall(line)}
|
||||
|
||||
# --- ルール4: 推測タグと未確認事項の対応 ---
|
||||
entries = set()
|
||||
@@ -80,9 +181,14 @@ def check(path):
|
||||
elif blocks:
|
||||
blocks[-1][2].append(l)
|
||||
for pid, ln, body in blocks:
|
||||
if not any(PROMOTE.match(x) for x in body):
|
||||
has_promote = any(PROMOTE.match(x) for x in body)
|
||||
has_complete = any(COMPLETE.match(x) for x in body)
|
||||
if pid in tagged and not has_promote:
|
||||
add("ERROR", rel, ln,
|
||||
"%s に「- 格上げ条件:」の行がない(何を確認すれば事実に格上げできるか)" % pid)
|
||||
elif not has_promote and not has_complete:
|
||||
add("ERROR", rel, ln,
|
||||
"%s に「- 格上げ条件:」または「- 完了条件:」の内容がない" % pid)
|
||||
|
||||
for n, l in lines:
|
||||
if n in unconf_span:
|
||||
@@ -96,9 +202,10 @@ def check(path):
|
||||
# --- ルール3: journal への/からのリンク禁止 ---
|
||||
for n, l in lines:
|
||||
for target in MDLINK.findall(l):
|
||||
if target.lstrip("./").startswith("journal/"):
|
||||
linked, _ = local_target(path, target)
|
||||
if linked is not None and linked.is_relative_to(ROOT / "journal"):
|
||||
add("ERROR", rel, n, "journal へのリンクが張られている: %s" % target)
|
||||
elif is_journal:
|
||||
elif is_journal and linked is not None:
|
||||
add("ERROR", rel, n, "journal から他ファイルへのリンクが張られている: %s" % target)
|
||||
|
||||
# --- ルール1: 検討済み・非採用 ---
|
||||
@@ -121,7 +228,7 @@ def check(path):
|
||||
add("WARN", rel, 1, "冒頭20行に結論が見当たらない(結論を先頭に置く)")
|
||||
|
||||
# --- ルール1: 調査・比較の混入(要目視確認) ---
|
||||
if not is_journal and base not in PROSE_EXEMPT:
|
||||
if not is_journal and not is_backlog and base not in PROSE_EXEMPT:
|
||||
# 検討済み・非採用 は却下案を列挙する場所なので対象外
|
||||
skip = set(n for n, _ in rejected) if rejected else set()
|
||||
for n, l in lines:
|
||||
@@ -135,16 +242,21 @@ def check(path):
|
||||
add("WARN", rel, n, "優先度評価は journal 行きでは?")
|
||||
|
||||
def main(argv):
|
||||
targets = argv[1:]
|
||||
issues.clear()
|
||||
targets = [Path(arg).resolve() for arg in argv[1:]]
|
||||
if not targets:
|
||||
targets = sorted(glob.glob("*.md")) + sorted(glob.glob("journal/*.md"))
|
||||
targets = (sorted(ROOT.glob("*.md")) + sorted((ROOT / "journal").glob("*.md"))
|
||||
+ sorted((ROOT / "backlog").rglob("*.md")))
|
||||
targets = list(dict.fromkeys(targets))
|
||||
if not targets:
|
||||
print("対象ファイルなし"); return 0
|
||||
print("対象ファイルなし")
|
||||
return 0
|
||||
seen_backlog_ids = {}
|
||||
for t in targets:
|
||||
if os.path.isfile(t):
|
||||
check(t)
|
||||
if t.is_file():
|
||||
check(t, seen_backlog_ids)
|
||||
else:
|
||||
print("見つからない: %s" % t)
|
||||
add("ERROR", t.as_posix(), 1, "対象ファイルが見つからない")
|
||||
|
||||
errs = [i for i in issues if i[0] == "ERROR"]
|
||||
warns = [i for i in issues if i[0] == "WARN"]
|
||||
@@ -154,4 +266,6 @@ def main(argv):
|
||||
return 1 if errs else 0
|
||||
|
||||
if __name__ == "__main__":
|
||||
if hasattr(sys.stdout, "reconfigure"):
|
||||
sys.stdout.reconfigure(encoding="utf-8")
|
||||
sys.exit(main(sys.argv))
|
||||
|
||||
@@ -0,0 +1,150 @@
|
||||
"""文書の分類・参照・完了条件の回帰検査。標準ライブラリだけで実行する。"""
|
||||
import contextlib
|
||||
import importlib.util
|
||||
import io
|
||||
import tempfile
|
||||
import unittest
|
||||
from pathlib import Path
|
||||
from unittest.mock import patch
|
||||
|
||||
|
||||
spec = importlib.util.spec_from_file_location("doc_lint", Path(__file__).with_name("doc-lint.py"))
|
||||
lint = importlib.util.module_from_spec(spec)
|
||||
spec.loader.exec_module(lint)
|
||||
|
||||
|
||||
def backlog_item(pid="PHY-P-14"):
|
||||
return (
|
||||
f"### {pid} 原点の吸着\n\n"
|
||||
"- 関連仕様: [PHY](../PHY.md)\n"
|
||||
"- 未決事項: 吸着が必要か\n"
|
||||
"- 保留できる理由: 数値入力で編集できる\n"
|
||||
"- 再開条件: 原点移動を試作するとき\n"
|
||||
"- 完了条件: 吸着の要否を決める\n"
|
||||
)
|
||||
|
||||
|
||||
class DocLintTests(unittest.TestCase):
|
||||
def setUp(self):
|
||||
temporary = tempfile.TemporaryDirectory()
|
||||
self.addCleanup(temporary.cleanup)
|
||||
self.root = Path(temporary.name).resolve()
|
||||
root_patch = patch.object(lint, "ROOT", self.root)
|
||||
root_patch.start()
|
||||
self.addCleanup(root_patch.stop)
|
||||
self.write("PHY.md", "# PHY\n")
|
||||
|
||||
def write(self, relative, content):
|
||||
path = self.root / relative
|
||||
path.parent.mkdir(parents=True, exist_ok=True)
|
||||
path.write_text(content, encoding="utf-8")
|
||||
return path
|
||||
|
||||
def run_lint(self, *paths):
|
||||
output = io.StringIO()
|
||||
with contextlib.redirect_stdout(output):
|
||||
status = lint.main(["doc-lint.py", *(str(path) for path in paths)])
|
||||
return status, output.getvalue()
|
||||
|
||||
def test_default_scan_includes_backlog_and_accepts_fixed_links(self):
|
||||
self.write("PHY.md", "# PHY\n\n## 保留課題\n\n- [PHYの保留課題](backlog/README.md#phy)\n")
|
||||
self.write("backlog/README.md", "# 保留課題\n\n## PHY\n\n" + backlog_item())
|
||||
self.write("journal/2026-09-22-decision.md", "# 決定\n\n## 結論\n\n採用した。\n")
|
||||
status, output = self.run_lint()
|
||||
self.assertEqual(status, 0, output)
|
||||
self.assertIn("3 files / ERROR 0", output)
|
||||
|
||||
def test_backlog_fields_must_have_values(self):
|
||||
for field in lint.BACKLOG_FIELDS:
|
||||
with self.subTest(field=field):
|
||||
text = backlog_item()
|
||||
text = "\n".join(f"- {field}: " if line.startswith(f"- {field}:") else line
|
||||
for line in text.splitlines())
|
||||
path = self.write("backlog/README.md", "## PHY\n" + text)
|
||||
status, output = self.run_lint(path)
|
||||
self.assertEqual(status, 1)
|
||||
self.assertIn(f"- {field}:", output)
|
||||
|
||||
def test_duplicate_backlog_ids_across_nested_files(self):
|
||||
self.write("backlog/one.md", "## PHY\n" + backlog_item())
|
||||
self.write("backlog/sub/two.md", "## PHY\n" + backlog_item().replace("../PHY.md", "../../PHY.md"))
|
||||
status, output = self.run_lint()
|
||||
self.assertEqual(status, 1)
|
||||
self.assertIn("保留課題のID PHY-P-14 が重複", output)
|
||||
|
||||
def test_incomplete_last_item_cannot_borrow_fields_from_next_section(self):
|
||||
self.write("backlog/README.md", "## PHY\n### PHY-P-14 吸着\n\n## ELC\n" + backlog_item("ELC-P-1"))
|
||||
status, output = self.run_lint()
|
||||
self.assertEqual(status, 1)
|
||||
self.assertIn("PHY-P-14 に「- 完了条件:」", output)
|
||||
|
||||
def test_invalid_backlog_heading_and_missing_reference(self):
|
||||
path = self.write("backlog/README.md", "## PHY\n### P-14 吸着\n" + backlog_item().replace("../PHY.md", "../missing.md"))
|
||||
status, output = self.run_lint(path)
|
||||
self.assertEqual(status, 1)
|
||||
self.assertIn("保留課題の見出し", output)
|
||||
self.assertIn("参照先ファイルがない", output)
|
||||
|
||||
def test_spec_backlog_section_rejects_prose_empty_and_broken_targets(self):
|
||||
self.write("backlog/README.md", "## PHY\n" + backlog_item())
|
||||
cases = {
|
||||
"内容をここにも要約する。": "だけを書く",
|
||||
"": "空の ## 保留課題",
|
||||
"- [PHYの保留課題](backlog/missing.md#phy)": "参照先ファイルがない",
|
||||
"- [PHYの保留課題](backlog/README.md#missing)": "参照先見出しがない",
|
||||
"- [PHYの保留課題](backlog/README.md)": "見出しへリンク",
|
||||
"- [PHYの保留課題](PHY.md#phy)": "backlog内",
|
||||
}
|
||||
for content, expected in cases.items():
|
||||
with self.subTest(content=content):
|
||||
path = self.write("PHY.md", "# PHY\n\n## 保留課題\n\n" + content + "\n")
|
||||
status, output = self.run_lint(path)
|
||||
self.assertEqual(status, 1)
|
||||
self.assertIn(expected, output)
|
||||
|
||||
def test_management_sections_have_one_order(self):
|
||||
path = self.write("PHY.md", "## 未確認事項\n\n(なし)\n\n## 検討済み・非採用\n\n## 未確認事項\n")
|
||||
status, output = self.run_lint(path)
|
||||
self.assertEqual(status, 1)
|
||||
self.assertIn("順に置く", output)
|
||||
self.assertIn("## 未確認事項 が重複", output)
|
||||
|
||||
def test_decisions_accept_completion_but_tagged_assumptions_require_evidence(self):
|
||||
text = "## 未確認事項\n\n### P-1 操作方式\n- 完了条件: 操作方式を決める\n"
|
||||
path = self.write("PHY.md", text)
|
||||
self.assertEqual(self.run_lint(path)[0], 0)
|
||||
path.write_text("本文 [推測:P-1]\n\n" + text, encoding="utf-8")
|
||||
status, output = self.run_lint(path)
|
||||
self.assertEqual(status, 1)
|
||||
self.assertIn("格上げ条件", output)
|
||||
path.write_text("本文 [推測:P-1]\n\n" + text.replace("完了条件", "格上げ条件"), encoding="utf-8")
|
||||
self.assertEqual(self.run_lint(path)[0], 0)
|
||||
|
||||
def test_absolute_journal_paths_keep_journal_checks(self):
|
||||
path = self.write("journal/bad.md", "# 調査\n\n[仕様](../PHY.md)\n")
|
||||
status, output = self.run_lint(path)
|
||||
self.assertEqual(status, 1)
|
||||
self.assertIn("journal のファイル名", output)
|
||||
self.assertIn("journal から他ファイルへのリンク", output)
|
||||
|
||||
def test_backlog_is_not_prose_linted_but_cannot_link_to_journal(self):
|
||||
self.write("journal/2026-09-22-decision.md", "## 結論\n")
|
||||
path = self.write("backlog/README.md", "## PHY\n" + backlog_item() + "\n候補はA案。\n[履歴](../journal/2026-09-22-decision.md)\n")
|
||||
status, output = self.run_lint(path)
|
||||
self.assertEqual(status, 1)
|
||||
self.assertIn("journal へのリンク", output)
|
||||
self.assertIn("WARN 0", output)
|
||||
|
||||
def test_code_examples_do_not_create_real_sections_or_tags(self):
|
||||
path = self.write("PHY.md", "```markdown\n## 保留課題\n[推測:P-9]\n```\n")
|
||||
status, output = self.run_lint(path)
|
||||
self.assertEqual(status, 0, output)
|
||||
|
||||
def test_missing_explicit_file_is_an_error(self):
|
||||
status, output = self.run_lint(self.root / "missing.md")
|
||||
self.assertEqual(status, 1)
|
||||
self.assertIn("対象ファイルが見つからない", output)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -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/` に落とす。
|
||||
- 既存ドキュメントの記述と食い違う事実を見つけたら、勝手に上書きせず指摘する。
|
||||
|
||||
|
||||
+9
-21
@@ -25,6 +25,9 @@ ELCが扱う「ピン」は物理的なマイコンピンに限らない。**ピ
|
||||
現時点で具体形を定めるのは、マイコンとアナログマルチプレクサの2種別。
|
||||
デジタル側でピンを増やす部品も提供者として扱うが、種別ごとの記述は必要になった時点で定める。
|
||||
|
||||
同じ `PinRef` が複数の提供者の `select` に現れることは一律には禁止しない。
|
||||
複数mux構成の走査出力は、実配線と制御方法を確認した構成から対応する。
|
||||
|
||||
### キーの端子
|
||||
|
||||
キーは検出方式(detect)を持ち、検出方式ごとに端子の構成が決まる。各端子は接続先の論理ピンを持つ。
|
||||
@@ -32,7 +35,7 @@ ELCが扱う「ピン」は物理的なマイコンピンに限らない。**ピ
|
||||
- 接点(contact): a, b の2端子。端子は無極性で、a と b に順序の意味はない
|
||||
- アナログ(analog): out 1端子。加えて電源の vcc, gnd。ホールセンサがこれにあたる
|
||||
|
||||
光学スイッチの端子構成は未定 [推測:P-1]。
|
||||
光学スイッチは当面未対応とする。端子構成を確認するまで、既存の検出方式に仮置きしない。
|
||||
|
||||
### 配線トポロジを区分として持たない
|
||||
|
||||
@@ -140,6 +143,10 @@ type ELC = {
|
||||
}
|
||||
```
|
||||
|
||||
## 保留課題
|
||||
|
||||
- [ELCの保留課題](backlog/README.md#elc)
|
||||
|
||||
## 検討済み・非採用
|
||||
|
||||
- `matrix.type` による配線方式の列挙 (journal/2026-09-20-elc-pin-provider.md)
|
||||
@@ -148,23 +155,4 @@ type ELC = {
|
||||
|
||||
## 未確認事項
|
||||
|
||||
### P-1 光学スイッチの端子構成
|
||||
|
||||
- 位置づけ: 本文「キーの端子」が扱えていない残り
|
||||
- 現状の認識: 発光側と受光側が独立した端子を持つのか、接点と同じ2端子として扱えるのかが分からない
|
||||
- 格上げ条件: 光学スイッチを使った実在のPCBの回路図を読み、端子数と配線の形を確認する
|
||||
|
||||
### P-2 複数マルチプレクサ構成の作り
|
||||
|
||||
- 位置づけ: 本文「ピンとピン提供者」が前提にしている。`select` を提供者ごとに持たせてよいかに関わる
|
||||
- 現状の認識: 選択ピンを複数のmuxで共有して共通ピンだけ分ける形と、イネーブルピンで切り替える形が考えられるが、
|
||||
どちらが一般的か確認していない。前者なら同じ `PinRef` が複数の提供者の `select` に現れる
|
||||
- 格上げ条件: 複数muxを使った実在のキーボードの配線を確認し、共有の形を確かめる
|
||||
|
||||
### P-3 方式ごとの走査設定の確認
|
||||
|
||||
- 位置づけ: 本文「配線トポロジを区分として持たない」の残り。走査方向の決定は出力器が持つと決めた
|
||||
- 現状の認識: 接点マトリクスではダイオードの向きから、directでは電源レールの参照から役割を判断できそうだが、
|
||||
方式ごとに出力器が決められる範囲と、ユーザーの追加指定が必要になる範囲は確認していない
|
||||
- 格上げ条件: 対象方式の配線と整合する走査方法を確認し、必要な出力設定と対応範囲を定める。
|
||||
全方式で走査手順が一意に決まることの証明は求めない
|
||||
(なし)
|
||||
|
||||
+8
-8
@@ -83,6 +83,9 @@ QとAは共通キー、バックスラッシュと `#` は排他キーとする
|
||||
全体の並びは `Q → バックスラッシュ → A → #`、ANSI出力は `Q → バックスラッシュ → A`、
|
||||
ISO出力は `Q → A → #` になる。
|
||||
|
||||
既存コミュニティレイアウトとの互換出力は、要求順を再現できることを確認したものを対象とする。
|
||||
単一の `order` で既存レイアウト全般を再現できることは、現行仕様の前提にしない。
|
||||
|
||||
## 他レイヤーとの関係
|
||||
|
||||
IDXはPHYのキーIDだけを参照する。ELCを参照しない。
|
||||
@@ -118,6 +121,10 @@ type IDX = {
|
||||
|
||||
出力番号の対象は `order` に挙げたキーに限る。PHYの部品ノードと `decal` のキーは対象にならない。
|
||||
|
||||
## 保留課題
|
||||
|
||||
- [IDXの保留課題](backlog/README.md#idx)
|
||||
|
||||
## 検討済み・非採用
|
||||
|
||||
- PHYのツリー順をキー番号とする (journal/2026-09-21-idx-necessity.md)
|
||||
@@ -128,11 +135,4 @@ type IDX = {
|
||||
|
||||
## 未確認事項
|
||||
|
||||
### P-1 単一のorderから既存コミュニティレイアウトの並びを得られる範囲
|
||||
|
||||
- 位置づけ: 本文「レイアウトバリアント」の方式を、既存レイアウトとの互換出力に使う際の未検証部分
|
||||
- 現状の認識: 同じ配線を使う別のPHYキーを別々の位置に置けるため、本文のANSI/ISO例は取捨で表せる。
|
||||
既存のコミュニティレイアウト全般で同じように表せるかは未検証。同じPHYキーIDを使う共通キー同士の
|
||||
要求順がレイアウト間で逆転する場合は、単一のorderからの取捨では表せないが、その実例の有無は未確認
|
||||
- 格上げ条件: 実データのキーを共通キーとバリアント別のPHYキーに対応づけ、全体のorderから各レイアウトの
|
||||
要求順を取捨で再現できるか確認する。再現できないものが残る場合は、対応範囲と扱いを決める
|
||||
(なし)
|
||||
|
||||
+19
-37
@@ -101,6 +101,8 @@ LED・OLED・ロータリーエンコーダ・ネジ穴のように、設計者
|
||||
フットプリントの選択には使わない。予約名以外および省略時は既定の形で描く。
|
||||
ユーザーが付ける名前は `@` で始めない限り予約と衝突しない。
|
||||
|
||||
当面は表裏の描き分けを行わない。描画用の予約グループ名を、PCB上の実装面の指定としては使わない。
|
||||
|
||||
部品ノードはクラスターの子になれる。クラスターを動かせば配下の部品も追随する。
|
||||
|
||||
LEDの配線はPHYが持たない。LEDの識別番号もPHYは持たない。番号は配線で決まるため、ELCが持つ。
|
||||
@@ -113,6 +115,7 @@ IDXはLEDの番号を持たない。RGB効果が必要とする位置と区分
|
||||
### ラベル
|
||||
|
||||
キーはラベルを参考情報として持つ。KLE JSONの取り込みでは照合に使う。
|
||||
当面はラベルからMAPへの自動適用は行わない。
|
||||
|
||||
### グルーピング
|
||||
|
||||
@@ -198,6 +201,9 @@ Transform は回転と平行移動だけを持つ剛体変換であり、合成
|
||||
ただし選択したノード全部が同じ回転角度を持つ場合はその角度を基準角度に採り、境界矩形もその角度の座標系で取る
|
||||
- 組み替えで生じた非グリッド値はそのまま保持する。クラスターを解除して親に戻ったノードも同じ
|
||||
|
||||
当面、reframeは通常の移動・回転と別の明示的な操作とし、原点の指定は数値入力で行う。
|
||||
原点の吸着やフォーカス状態・ハンドルに連動した操作は、試作後に検討する。
|
||||
|
||||
## 保存形式
|
||||
|
||||
各ノードは親から見た変換を持つ。キー・クラスター・部品ノード・バリアントノードを混在させた木構造として保持する。
|
||||
@@ -342,6 +348,10 @@ const kleData = (ConfigObject | KeyLabel)[][]
|
||||
|
||||
### KLE JSONの取り込み
|
||||
|
||||
当面は新規PHYとしての読み込みを対象とする。既存PHYへの照合・更新は、照合規則を検証するまで未対応とする。
|
||||
以下は照合・更新に対応する際の制約であり、曖昧な対応を自動確定しない。
|
||||
誤照合で既存IDを別のキーに割り当てると、他レイヤーの参照にも影響するため。
|
||||
|
||||
既存のPHYデータを畳んだ配置に対して、KLE JSONの各キーを形状(位置・サイズ・回転)とラベルで照合する。
|
||||
|
||||
- 照合できたキーは元のノードとして扱う。KLE側で配置が変わっていれば、元の親から見た相対座標に戻して反映する
|
||||
@@ -356,10 +366,17 @@ KLE本家はこの位置の r, rx, ry をエラーにするが、VIAとRemapは
|
||||
|
||||
KLEの rx, ry, r はキーの絶対配置 (x, y, rotation) に変換して取り込む。元の rx, ry は保持しない。
|
||||
|
||||
見た目の属性(c, t, p, a, f, f2, fa, l, n)は、KLE JSONへ書き戻せるように保持する。どの層で持つかは決まっていない。
|
||||
見た目の属性(c, t, p, a, f, f2, fa, l, n)は、KLE JSONへ書き戻せるように保持する。
|
||||
当面はキー単位の `kleCompatibility` に不透明なデータとして退避し、見た目の編集機能は持たない。
|
||||
|
||||
KLEの sm, sb, st(ファイル単位では switchMount, switchBrand, switchType)も同様に、不透明なまま保持して書き戻す。
|
||||
Beyond KLEはスイッチの品種を持たないため、対応づける先がない。
|
||||
ファイル単位の属性(switchMount, switchBrand, switchType, backcolor, radii, background, css)は、
|
||||
ファイル単位の `kleCompatibility` に退避する。正式な所属層を決めるまでは、この退避先で保持する。
|
||||
|
||||
## 保留課題
|
||||
|
||||
- [PHYの保留課題](backlog/README.md#phy)
|
||||
|
||||
## 検討済み・非採用
|
||||
|
||||
@@ -371,39 +388,4 @@ Beyond KLEはスイッチの品種を持たないため、対応づける先が
|
||||
|
||||
## 未確認事項
|
||||
|
||||
### P-2 KLE JSON取り込み時の照合基準
|
||||
|
||||
- 位置づけ: 本文「KLE JSONの取り込み」の具体化に必要な未解決の問い
|
||||
- 現状の認識: 形状の許容誤差、ラベルの扱い、複数候補がある場合の決め方が未定
|
||||
- 格上げ条件: 照合規則を決めたうえで、KLE本家でキーの移動・追加・削除をしたJSONを取り込み、意図どおりに対応づくことを確認する
|
||||
|
||||
### P-6 キーキャップの見た目情報を持つ層
|
||||
|
||||
- 位置づけ: 本文「見た目の属性は保持する。どの層で持つかは決まっていない」の未解決部分
|
||||
- 現状の認識: c, t, p, a, f系に加え、l, n もキーキャップの見た目属性であり、PHYとは別の層が要りそう。退避だけして書き戻す sm, sb, st も同じ置き場の問題を持つ。そもそもキーキャップは設計時に決める必要が薄く、カスタムキーボードの文脈に属するため、Beyond KLEの扱う範囲かどうかも未定。ファイル単位の backcolor, radii, background, css も同じ問いに含まれる
|
||||
- 格上げ条件: キーキャップの情報をBeyond KLEの範囲に含めるかをユーザーが決め、保持する層を決める
|
||||
|
||||
### P-8 ラベルをMAPに適用するか
|
||||
|
||||
- 位置づけ: 未解決の問い。本文ではラベルを参考情報として持つことだけを決めている
|
||||
- 現状の認識: どのラベルがMAPに適用できるかは、おそらく機械的には判断できない。自動で適用してユーザーが不要なものを落とす方式も考えられる
|
||||
- 格上げ条件: 適用するか、する場合は自動適用とユーザーによる取捨の流れをユーザーが決める
|
||||
|
||||
### P-12 部品の表裏を描画でどう扱うか
|
||||
|
||||
- 位置づけ: 本文「部品ノードは表裏を持たない」の残余
|
||||
- 現状の認識: どちらの面に載るかはPCB設計ツールが決める情報なのでPHYには持たない。ただしエディタ上で裏面の部品を描き分けたくなる可能性があり、`@` 始まりの予約グループ名だけで表現できるかは未検証
|
||||
- 格上げ条件: 予約グループ名による描画を実装し、表裏の描き分けが必要になるか、必要なら予約名で足りるかを確認する
|
||||
|
||||
### P-13 reframeと通常の移動・回転をエディタ上でどう区別するか
|
||||
|
||||
- 位置づけ: 本文「クラスターの組み替え」の残余。データモデル側は決まっており、操作系だけが未定
|
||||
- 現状の認識: クラスターへのフォーカス状態に紐づけ(中に入っている間は配下の絶対配置が変わらない)、
|
||||
そのうえで原点ハンドルと通常の移動・回転ハンドルを分ける案が有力。専用モードを設ける案もある
|
||||
- 格上げ条件: 操作系をユーザーが決める
|
||||
|
||||
### P-14 クラスター原点の吸着先
|
||||
|
||||
- 位置づけ: 未解決の問い。数値入力以外に、原点をどこへ吸着させるか
|
||||
- 現状の認識: キーのローカル原点(左上角)・キー中心・境界矩形の角と中心が候補。相対グリッドとは別の機構になる
|
||||
- 格上げ条件: 原点移動を実装し、吸着なしで足りるか、足りない場合どの候補が要るかを確認する
|
||||
(なし)
|
||||
|
||||
@@ -0,0 +1,100 @@
|
||||
# 保留課題
|
||||
|
||||
現在の実装が答えに依存せず進められる問い・検証・改善候補をまとめる。
|
||||
保留中の対応範囲は各仕様書を正とし、運用は[ドキュメント運用ルール](../CLAUDE.md)に従う。
|
||||
項目の識別子は移動元のレイヤー名と番号を引き継ぐ。
|
||||
|
||||
## PHY
|
||||
|
||||
### PHY-P-2 KLE JSON取り込み時の照合基準
|
||||
|
||||
- 関連仕様: [PHYレイヤー](../PHYレイヤー.md)「KLE JSONの取り込み」
|
||||
- 未決事項: 形状の許容誤差、ラベルの扱い、複数候補がある場合の決め方。
|
||||
- 保留できる理由: 新規PHYとしての読み込みは、既存ノードとの照合なしで実装できる。
|
||||
- 再開条件: 既存PHYへのKLE JSONの照合・更新に着手するとき。
|
||||
- 完了条件: 照合規則と曖昧な候補の扱いを決め、KLE本家でキーの移動・追加・削除をしたJSONを取り込み、
|
||||
意図したIDに対応づき、他レイヤーの参照を誤って付け替えないことを確認する。
|
||||
|
||||
### PHY-P-6 キーキャップの見た目情報を持つ層
|
||||
|
||||
- 関連仕様: [PHYレイヤー](../PHYレイヤー.md)「KLE JSONの取り込み」、[JSON Schema](../phase1-json-schema.md)の `kleCompatibility`
|
||||
- 未決事項: キーキャップの見た目編集をBeyond KLEの範囲に含めるか、正式にはどの層で情報を持つか。
|
||||
対象はキー単位の c, t, p, a, f系, l, n と、退避する sm, sb, st、ファイル単位の
|
||||
switchMount, switchBrand, switchType, backcolor, radii, background, css。
|
||||
- 保留できる理由: 現行Schemaの `kleCompatibility` で、正式な所属層や編集機能を決めずに保持・書き戻しができる。
|
||||
- 再開条件: 見た目の編集機能、または退避先から正式な所属層への移行を検討するとき。
|
||||
- 完了条件: 扱う範囲と所属層をユーザーが決め、既存の退避情報を失わない保持・移行方法を定める。
|
||||
|
||||
### PHY-P-8 ラベルをMAPに適用するか
|
||||
|
||||
- 関連仕様: [PHYレイヤー](../PHYレイヤー.md)「ラベル」
|
||||
- 未決事項: ラベルをMAPへ適用するか。機械的に適用先を判断できるかは未確認で、候補を自動適用してユーザーが不要なものを落とす案もある。
|
||||
- 保留できる理由: ラベルは参考情報として保持でき、MAPへの自動適用なしで各レイヤーを扱える。
|
||||
- 再開条件: MAPのキーコード割り当てを補助する機能を検討するとき。
|
||||
- 完了条件: 適用の要否と、適用する場合の候補提示・ユーザーによる取捨の流れをユーザーが決める。
|
||||
|
||||
### PHY-P-12 部品の表裏を描画でどう扱うか
|
||||
|
||||
- 関連仕様: [PHYレイヤー](../PHYレイヤー.md)「部品ノード」
|
||||
- 未決事項: エディタ上で表裏の描き分けが必要か。必要なら `@` 始まりの予約グループ名だけで足りるか。
|
||||
- 保留できる理由: 表裏を描き分けなくても配置は編集でき、実装面はPCB設計ツール側で決められる。
|
||||
- 再開条件: 部品ノードと予約グループ名による描画を試作し、表示を評価するとき。
|
||||
- 完了条件: 描き分けの要否を確認し、必要なら実装面の指定と混同しない表示方法を決める。
|
||||
|
||||
### PHY-P-13 reframeと通常の移動・回転をエディタ上でどう区別するか
|
||||
|
||||
- 関連仕様: [PHYレイヤー](../PHYレイヤー.md)「クラスターの組み替え」
|
||||
- 未決事項: reframeの操作系。クラスターへのフォーカス状態に紐づけて原点ハンドルと通常のハンドルを分ける案と、専用モードを設ける案がある。
|
||||
- 保留できる理由: データ変換は定義済みで、通常の移動・回転とは別の明示的な操作として試作できる。
|
||||
- 再開条件: クラスター編集を試作し、操作の分かりやすさを評価するとき。
|
||||
- 完了条件: 配下が追随する操作と絶対配置を保つ操作を区別できる操作系をユーザーが決める。
|
||||
|
||||
### PHY-P-14 クラスター原点の吸着先
|
||||
|
||||
- 関連仕様: [PHYレイヤー](../PHYレイヤー.md)「クラスターの組み替え」
|
||||
- 未決事項: 吸着が必要か。候補はキーのローカル原点(左上角)・キー中心・境界矩形の角と中心で、相対グリッドとは別の機構になる。
|
||||
- 保留できる理由: 数値入力だけで原点移動は成立する。
|
||||
- 再開条件: 原点移動を試作し、操作性を評価するとき。
|
||||
- 完了条件: 吸着の要否と、必要な場合の候補を決める。
|
||||
|
||||
## ELC
|
||||
|
||||
### ELC-P-1 光学スイッチの端子構成
|
||||
|
||||
- 関連仕様: [ELCレイヤー](../ELCレイヤー.md)「キーの端子」
|
||||
- 未決事項: 発光側と受光側が独立した端子を持つのか、接点と同じ2端子として扱えるのか。
|
||||
- 保留できる理由: 光学スイッチを対応範囲から外したまま、接点・アナログの配線を扱える。
|
||||
- 再開条件: 光学スイッチの配線に対応するとき。
|
||||
- 完了条件: 実在のPCBの回路図で端子数と配線の形を確認し、必要な端子構成を定める。
|
||||
|
||||
### ELC-P-2 複数マルチプレクサ構成の作り
|
||||
|
||||
- 関連仕様: [ELCレイヤー](../ELCレイヤー.md)「ピンとピン提供者」
|
||||
- 未決事項: 選択ピンを共有して共通ピンを分ける構成と、enableで切り替える構成の実配線・制御方法。
|
||||
どちらが一般的かは未確認。前者は複数providerの `select` に同じ `PinRef` を書く形で表現できる。
|
||||
- 保留できる理由: providerごとの参照を保存する形は維持でき、複数muxの走査出力を検証済みの構成に限定できる。
|
||||
- 再開条件: 複数muxを使う構成のファームウェア出力に対応するとき。
|
||||
- 完了条件: 実在のキーボードの配線でピン共有とenableの使い方を確認し、現行モデルでの表現と必要な制御を確かめる。
|
||||
|
||||
### ELC-P-3 方式ごとの走査設定の確認
|
||||
|
||||
- 関連仕様: [ELCレイヤー](../ELCレイヤー.md)「配線トポロジを区分として持たない」
|
||||
- 未決事項: 各方式で出力器が決められる走査方法と、ユーザーの追加指定が必要になる範囲。
|
||||
接点マトリクスではダイオードの向き、directでは電源レールの参照から役割を判断できる範囲を確認する。
|
||||
- 保留できる理由: 走査方向の決定・追加指定の責任は出力器側と決まり、ELCの配線保存はそのまま進められる。
|
||||
- 再開条件: 各方式のファームウェア出力に着手するとき。
|
||||
- 完了条件: 対象方式の配線と整合する走査方法を確認し、必要な出力設定と対応範囲を定める。
|
||||
全方式で走査手順が一意に決まることの証明は求めない。
|
||||
|
||||
## IDX
|
||||
|
||||
### IDX-P-1 単一のorderから既存コミュニティレイアウトの並びを得られる範囲
|
||||
|
||||
- 関連仕様: [IDXレイヤー](../IDXレイヤー.md)「レイアウトバリアント」
|
||||
- 未決事項: 採用済みの方式で既存コミュニティレイアウトの要求順を再現できる範囲の実測。
|
||||
同じPHYキーIDを使う共通キー同士の要求順がレイアウト間で逆転する場合は、単一の `order` からの取捨では表せないが、その実例の有無は未確認。
|
||||
- 保留できる理由: 全バリアントのキーを別々の要素として並べ、選択後に番号を詰める仕様は決定済み。
|
||||
既存レイアウト全般との互換性を前提にせず実装できる。
|
||||
- 再開条件: 既存コミュニティレイアウトとの互換出力を検証するとき。
|
||||
- 完了条件: 実データのキーを共通キーとバリアント別のPHYキーに対応づけ、全体の `order` から各レイアウトの要求順を取捨で再現できるか確認する。
|
||||
再現できないものが残る場合は、対応範囲と扱いを決める。
|
||||
@@ -0,0 +1,44 @@
|
||||
# 保留課題をbacklogへ分離する
|
||||
|
||||
## 結論
|
||||
|
||||
文書を、現行仕様・保留課題・検討履歴の3種類に分ける。
|
||||
後回しにできる問い・検証・改善候補はbacklog/README.mdにまとめる。
|
||||
現在の仕様が依存する未確認の前提は、引き続き仕様書の末尾に残す。
|
||||
|
||||
## 案の比較
|
||||
|
||||
| 置き場 | 判断 |
|
||||
| --- | --- |
|
||||
| 各仕様書の未確認事項にすべて残す | 現行実装の前提と、将来考えればよい課題が混ざる |
|
||||
| journalへ移す | 結論反映後に削除できる履歴と、再開まで残す課題では寿命が異なる |
|
||||
| 直下にbacklog.mdを置く | 直下へ追加したくないというユーザーの意向で採らない |
|
||||
| backlog/README.mdへまとめる | 採用。役割をフォルダで区別し、必要になれば分割できる |
|
||||
|
||||
## 運用の意図
|
||||
|
||||
既存ルールの狙いは、採用した仕様に過去の検討を混ぜず、未確認の前提を事実と誤認して実装しないこと。
|
||||
保留課題は現在の仕様でも解決済みの履歴でもないため、第3の文書種別として扱う。
|
||||
|
||||
移動の基準は未確認かどうかではなく、現在の実装がその答えに依存するかどうか。
|
||||
保留中の対応範囲・暫定仕様は仕様書に明記し、その範囲で進められる問いだけを移す。
|
||||
backlogへの移動自体は、仮説の採用や実装の許可を意味しない。
|
||||
|
||||
各項目は元の番号にレイヤー名を付け、関連仕様・未決事項・保留理由・再開条件・完了条件を持つ。
|
||||
再開条件で「いつ考え直すか」を、完了条件で「何を確認または決定すれば終わるか」を残す。
|
||||
事実確認と設計上の意思決定をともに「格上げ」と呼ぶことはやめる。
|
||||
解決または取り下げた項目は削除し、完了済み課題の一覧は作らない。
|
||||
|
||||
仕様書側の「保留課題」は、対応するbacklogの区分へのリンク箇条書きだけに固定した。
|
||||
問いの要約や項目名の列挙を重ねると片方だけ古くなるため、詳細はbacklogで一元管理する。
|
||||
末尾は保留課題・検討済み非採用・未確認事項の順とし、空の保留課題セクションは残さない。
|
||||
|
||||
## 適用範囲
|
||||
|
||||
PHY・ELC・IDXの10件を整理した。ELC-P-3は責任分担の決定後に残る方式別の確認として扱い、
|
||||
IDX-P-1は別途決定済みの仕様を維持して既存レイアウトとの互換性の実測だけを残した。
|
||||
実機確認や既存コミュニティレイアウトの再調査は行っていない。
|
||||
他の既存文書の全体再編は、この変更には含めない。
|
||||
|
||||
doc-lintもルール5に対応させる。backlogを検査対象に加え、項目の必須欄、
|
||||
仕様書側の固定書式と参照先、事実確認と設計判断の完了条件を検査する。
|
||||
@@ -45,7 +45,7 @@ ELC・IDX・MAPはどれもPHYを参照する。ELCはIDXを参照せず、MAP
|
||||
},
|
||||
"kleCompatibility": {
|
||||
"type": "object",
|
||||
"description": "File-level opaque KLE fields kept for round-trip output (switchMount, switchBrand, switchType, backcolor, radii, background, css). The owning layer is undecided; see P-6 in PHYレイヤー.md",
|
||||
"description": "File-level opaque KLE fields kept for round-trip output (switchMount, switchBrand, switchType, backcolor, radii, background, css). Kept here for now; the eventual owning layer is deferred in backlog/README.md, PHY-P-6",
|
||||
"additionalProperties": true
|
||||
},
|
||||
"profiles": {
|
||||
@@ -170,7 +170,7 @@ ELC・IDX・MAPはどれもPHYを参照する。ELCはIDXを参照せず、MAP
|
||||
},
|
||||
"kleCompatibility": {
|
||||
"type": "object",
|
||||
"description": "Opaque KLE fields kept for round-trip output (c, t, p, a, f, f2, fa, l, n, sm, sb, st). The owning layer is undecided; see P-6 in PHYレイヤー.md",
|
||||
"description": "Opaque KLE fields kept for round-trip output (c, t, p, a, f, f2, fa, l, n, sm, sb, st). Kept here for now; the eventual owning layer is deferred in backlog/README.md, PHY-P-6",
|
||||
"additionalProperties": true
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user