docs(work): experts.md 경로 표를 스킬 paths와 맞추고 대조 시험을 둔다

문제: experts.md 3절 「경로 → 전문가」는 리드가 바뀐 경로로 렌즈를
고르는 표이고 "지식 스킬의 paths와 맞춘다"고 적는다. 그런데 손으로 옮긴
표가 열 스킬 중 아홉에서 이미 갈라졌다. 예: be-build-ci의 settings.gradle·
gradle.properties·Dockerfile·renovate.json, be-api-contract의 .env.example·
docs/upgrade/**, be-observability의 docs/runbooks/**, be-docs의
**/CLAUDE.md가 표에 없다. 표로 렌즈를 고르면 그 파일을 바꾼 변경에서
렌즈가 빠진다. 이름만 보는 시험(test_the_experts_manual_names_every_expert)은
이 차이를 못 잡는다.

고른 방법: 표 1열을 1차 렌즈 스킬의 paths와 똑같이 고치고, 시험이
표를 읽어(중괄호 펼침) 스킬마다 "1차 렌즈로 이름 댄 행의 glob 합집합 ==
그 스킬의 paths"를 본다. 표 위 문장에 대조 시험이 있다고 적는다.
버린 대안: 표를 지우고 각 스킬 paths를 읽으라고만 쓰기 — 리드가 렌즈
하나를 고르려고 스킬 열 개의 머리를 읽어야 하고, 「이럴 때 더한다」 칸이
갈 곳이 없다.

위험·한계: 「이럴 때 더한다」 칸은 기계로 대조하지 않는다.

검증: 새 시험 test_the_experts_path_table_lists_exactly_each_skill_paths —
기준 표에서 9개 스킬 실패(be-domain만 통과), 고친 표에서 통과.
test_claude_setup 16건 통과, check-work-docs.py·check-docs.py rc=0.
This commit is contained in:
DongHyeonka
2026-11-12 21:40:07 +09:00
parent 96bbdf6c2e
commit a638698fc8
2 changed files with 41 additions and 10 deletions
+31
View File
@@ -61,6 +61,29 @@ def skill_paths(path: Path) -> list[str]:
return re.findall(r'-\s+"([^"]+)"', block.group(1)) if block else []
def expand_braces(pattern: str) -> list[str]:
"""`a/{b,c}/d` → [`a/b/d`, `a/c/d`]. One brace group is enough for the patterns in experts.md."""
match = re.search(r"\{([^}]*)\}", pattern)
if not match:
return [pattern]
return [pattern[:match.start()] + part + pattern[match.end():] for part in match.group(1).split(",")]
def experts_lens_paths() -> dict[str, set[str]]:
"""experts.md 3절 표: 1열의 glob을 2열(1차 렌즈)이 이름 대는 지식 스킬마다 모은다."""
text = EXPERTS.read_text(encoding="utf-8")
section = text.split("## 3. ", 1)[1].split("\n## ", 1)[0]
lenses: dict[str, set[str]] = {}
for line in section.splitlines():
cells = [cell.strip() for cell in line.strip().strip("|").split("|")]
if len(cells) < 2 or not cells[0].startswith("`"):
continue
globs = [g for raw in re.findall(r"`([^`]+)`", cells[0]) for g in expand_braces(raw)]
for lens in re.findall(r"\bbe-[a-z-]+[a-z]", cells[1]):
lenses.setdefault(lens, set()).update(globs)
return lenses
def front_matter(path: Path) -> dict[str, str]:
text = path.read_text(encoding="utf-8")
match = re.match(r"^---\n(.*?)\n---\n", text, re.S)
@@ -155,6 +178,14 @@ class SkillTest(unittest.TestCase):
rx = glob_regex(pattern)
self.assertTrue(any(rx.fullmatch(f) for f in files), f"{name}: {pattern} matches no tracked file")
def test_the_experts_path_table_lists_exactly_each_skill_paths(self) -> None:
# The lead picks lenses from this table; a glob the skill has but the table lacks is a lens never picked.
table = experts_lens_paths()
for name in self.KNOWLEDGE:
with self.subTest(skill=name):
self.assertEqual(table.get(name, set()), set(skill_paths(SKILLS / name / "SKILL.md")),
"docs/work/experts.md 3절 1열 vs .claude/skills/<name>/SKILL.md paths")
def test_the_experts_manual_names_every_expert_and_the_rule_points_at_it(self) -> None:
manual = EXPERTS.read_text(encoding="utf-8")
for name in self.KNOWLEDGE + [path.stem for path in AGENTS.glob("*.md")]: