fe-design-system 스킬의 기준 문장 두 곳이 실제 규칙·토큰과 다르다. `color-mix()`는 `in oklab`만 쓴다고 적었지만 규칙(UI-02)은 색상각 공간만 거절하고, 코드는 반투명 가림막을 브라우저가 겹쳐 그린 색과 맞추려고 `in srgb`를 일부러 쓴다. `docs/styling/design-tokens.md` UI-02도 같은 문장이었다. 그리고 아이콘 토큰을 `--icon-size-*`라고 적었지만 실제 이름은 `--size-icon-*`·`--icon-stroke-default`다. 스킬을 따르는 리뷰어가 srgb를 oklab으로 "고치면" 스크롤바 자리 색 맞춤이 깨지고, 없는 토큰을 새로 만든다. 고른 방법: 두 문서의 문장을 규칙과 토큰 이름에 맞춘다. 그리고 `scripts/tests/test_claude_setup.py`에 "스킬이 백틱으로 적은 토큰 이름(토큰 이름공간만, 별표는 아무 이름)은 토큰 파일이 정의한다" 시험을 더한다. 버린 대안: 문서만 고치기(같은 어긋남이 다시 생겨도 아무도 모른다). 검증: 노트북 `python3 -m unittest scripts.tests.test_claude_setup`. 고치기 전 스킬에서 새 시험이 `--icon-size-*`로 실패했고, 고친 뒤 전부 통과한다. Refs: 1112/04-15
349 lines
20 KiB
Python
349 lines
20 KiB
Python
"""루트 지침과 `.claude/`의 규칙·스킬·서브에이전트가 소유자 결정(2026-11-07, 2026-11-11)대로인지 본다.
|
|
|
|
결과만 받는 일은 서브에이전트, 파일을 바꾸는 위임은 하위 세션이다(docs/work/delegate.md 4.3절).
|
|
새 스킬은 모두 모델이 부를 수 있고, 설명에 발동 조건을 적는다.
|
|
분야 전문가는 `paths`를 건 지식 스킬(`fe-*`)이고, 분야 판정은 서브에이전트 `reviewer` 하나에 렌즈로 준다
|
|
(docs/work/experts.md). 서브에이전트 설명은 모든 세션의 컨텍스트에 들어가니 합에 상한을 둔다.
|
|
|
|
python3 -m unittest discover -s scripts/tests
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import json
|
|
import re
|
|
import unittest
|
|
from pathlib import Path
|
|
|
|
REPO = Path(__file__).resolve().parent.parent.parent
|
|
CLAUDE = REPO / ".claude"
|
|
# Claude Code cuts a skill description at this many characters in the listing.
|
|
DESCRIPTION_LIMIT = 1536
|
|
WRITE_TOOLS = {"Edit", "Write", "MultiEdit", "NotebookEdit"}
|
|
# Every session (and every subagent) carries the subagent descriptions; there is no listing budget for them.
|
|
AGENT_DESCRIPTIONS_LIMIT = 1200
|
|
KNOWLEDGE_DESCRIPTION_LIMIT = 300
|
|
KNOWLEDGE_BODY_LIMIT = 150
|
|
KNOWLEDGE_SECTIONS = ["언제 쓰나 · 넘기는 곳", "함정", "이 분야에서 실패는 이렇게 보인다", "검증", "이 repo에서 정한 것"]
|
|
# Emphasis makes models over-trigger; a pasted example turn gets copied instead of the body being read.
|
|
BANNED_IN_DESCRIPTION = ("PROACTIVELY", "MUST", "CRITICAL", "IMPORTANT", "<example>")
|
|
|
|
|
|
# A skill points at a section as `path.md` 「name」, `path.md` 3.1절 (or 3·4절), `path.md` 4.1절 「name」,
|
|
# 같은 문서 6절 (the path cited last), or `fe-x` 「name」 (another skill's section).
|
|
CITED_TARGET = re.compile(r"`([^`\s]+\.md)`|`((?:fe-[a-z0-9-]+|new-feature|desktop-gates))`|(같은 문서)")
|
|
SECTION_NUMBERS = re.compile(r"(\d+(?:\.\d+)*(?:·\d+(?:\.\d+)*)*)절")
|
|
SECTION_NAME = re.compile(r"「([^」]+)」")
|
|
# What follows a citation up to the first of these is about that citation; past it is the sentence's own text.
|
|
CITATION_END = re.compile(r"—|`|\(|\)|;|\. |。")
|
|
HEADING_NUMBER = re.compile(r"^(\d+(?:\.\d+)*)\.?(?=\s)")
|
|
|
|
|
|
# A paragraph label on its own line ("자동 실행이 검사하는 것:") names a part of a section the same way a heading does.
|
|
LABEL_LINE = re.compile(r"^\*{0,2}([^\s*#|>`-][^:|]*?)\*{0,2}:\s*$")
|
|
|
|
|
|
def headings(path: Path) -> tuple[set[str], set[str]]:
|
|
"""The section names of a markdown file and the numbers of its numbered headings.
|
|
|
|
A name is a heading's text, with and without its leading number and a trailing "(…)", or a label line."""
|
|
names, numbers, fenced = set(), set(), False
|
|
for line in path.read_text(encoding="utf-8").splitlines():
|
|
if line.startswith("```"):
|
|
fenced = not fenced
|
|
if fenced:
|
|
continue
|
|
label = LABEL_LINE.match(line)
|
|
if label:
|
|
names.add(label.group(1).strip())
|
|
if not re.match(r"#{1,6} ", line):
|
|
continue
|
|
text = line.lstrip("#").strip()
|
|
number = HEADING_NUMBER.match(text)
|
|
if number:
|
|
numbers.add(number.group(1))
|
|
for name in (text, text[number.end():].strip() if number else text):
|
|
names.add(name)
|
|
names.add(re.sub(r"\s*\([^()]*\)$", "", name))
|
|
return names, numbers
|
|
|
|
|
|
def cited_sections(text: str) -> list[tuple[int, str, str]]:
|
|
"""(line, target file, 「name」 or N절) for every section a skill names after a path or another skill."""
|
|
found, last_path = [], None
|
|
for number, line in enumerate(text.splitlines(), 1):
|
|
matches = list(CITED_TARGET.finditer(line))
|
|
for index, match in enumerate(matches):
|
|
path, skill, same = match.groups()
|
|
if path:
|
|
target = last_path = path
|
|
elif skill:
|
|
target = f".claude/skills/{skill}/SKILL.md"
|
|
elif last_path:
|
|
target = last_path
|
|
else:
|
|
continue
|
|
rest = line[match.end(): matches[index + 1].start() if index + 1 < len(matches) else len(line)]
|
|
end = CITATION_END.search(rest)
|
|
segment = rest[: end.start()] if end else rest
|
|
if skill or same:
|
|
# Only a section named right after it: `fe-x`의 「검증」, 같은 문서 12절.
|
|
segment = re.match(r"(?:의)?\s*(?:\d[\d.·]*절\s*)?(?:「[^」]+」)?", segment).group(0)
|
|
for numbers in SECTION_NUMBERS.findall(segment):
|
|
found.extend((number, target, f"{value}절") for value in numbers.split("·"))
|
|
found.extend((number, target, f"「{name}」") for name in SECTION_NAME.findall(segment))
|
|
return found
|
|
|
|
|
|
def front_matter(path: Path) -> tuple[dict[str, str], list[str]]:
|
|
"""The scalar fields and the list items of a document's YAML front matter."""
|
|
match = re.match(r"^---\n(.*?)\n---\n", path.read_text(encoding="utf-8"), re.S)
|
|
if not match:
|
|
return {}, []
|
|
fields, items = {}, []
|
|
for line in match.group(1).splitlines():
|
|
if line.lstrip().startswith("- "):
|
|
items.append(line.strip()[2:].strip('"'))
|
|
continue
|
|
key, _, value = line.partition(":")
|
|
fields[key.strip()] = value.strip()
|
|
return fields, items
|
|
|
|
|
|
class RootInstructionsTest(unittest.TestCase):
|
|
def test_claude_md_imports_the_map_and_says_how_to_install_the_plugin_non_interactively(self) -> None:
|
|
text = (REPO / "CLAUDE.md").read_text(encoding="utf-8")
|
|
self.assertEqual(text.splitlines()[0], "@AGENTS.md")
|
|
for command in ("claude plugin marketplace add https://git.learn.hyeonworks.com/donghyeon.kang/claude-harness.git"
|
|
" --scope project", "claude plugin install harness@claude-harness --scope project"):
|
|
self.assertIn(command, text)
|
|
|
|
def test_the_map_holds_the_five_rules_the_router_and_the_entry_point(self) -> None:
|
|
text = (REPO / "AGENTS.md").read_text(encoding="utf-8")
|
|
self.assertEqual(len(re.findall(r"^[1-5]\. ", text.split("## 지도")[0], re.M)), 5)
|
|
for fragment in ("docs/work/README.md", "scripts/verify.sh", "config/ci/gates.json", ".dependency-cruiser.json",
|
|
"하위 세션", "서브에이전트"):
|
|
self.assertIn(fragment, text)
|
|
|
|
def test_the_review_criteria_left_the_session_instructions(self) -> None:
|
|
for path in ("AGENTS.md", "CLAUDE.md"):
|
|
text = (REPO / path).read_text(encoding="utf-8")
|
|
self.assertNotIn("28개 관점", text, path)
|
|
self.assertNotIn("서브에이전트를 병렬로", text, path)
|
|
|
|
|
|
class LayerGuideTest(unittest.TestCase):
|
|
"""Every top-level src/ folder has its rule book, readable by any agent, and Claude Code imports it."""
|
|
|
|
def test_every_layer_folder_has_a_rule_book_and_the_import_beside_it(self) -> None:
|
|
folders = sorted(path for path in (REPO / "src").iterdir() if path.is_dir() and not path.name.startswith("."))
|
|
self.assertTrue(folders)
|
|
for folder in folders:
|
|
guide = folder / "AGENTS.md"
|
|
self.assertTrue(guide.is_file(), f"{folder.name}: no AGENTS.md")
|
|
self.assertTrue(guide.read_text(encoding="utf-8").startswith(f"# AGENTS.md — `src/{folder.name}`"))
|
|
self.assertEqual((folder / "CLAUDE.md").read_text(encoding="utf-8"), "@AGENTS.md\n", folder.name)
|
|
|
|
def test_path_rules_point_at_the_folder_books_instead_of_copying_them(self) -> None:
|
|
for rule, book in (("adapters", "src/adapters/AGENTS.md"), ("features", "src/features/AGENTS.md")):
|
|
self.assertIn(f"`{book}`", (CLAUDE / "rules" / f"{rule}.md").read_text(encoding="utf-8"))
|
|
|
|
def test_the_owner_forms_exist_and_the_map_points_at_them(self) -> None:
|
|
for form in ("docs/vision.md", "docs/problem-statement.md"):
|
|
self.assertIn("(채울 것", (REPO / form).read_text(encoding="utf-8"), form)
|
|
self.assertIn(f"`{form}`", (REPO / "AGENTS.md").read_text(encoding="utf-8"))
|
|
|
|
|
|
class SubagentTest(unittest.TestCase):
|
|
AGENTS = CLAUDE / "agents"
|
|
|
|
def test_the_agent_tool_is_not_denied(self) -> None:
|
|
settings = json.loads((CLAUDE / "settings.json").read_text(encoding="utf-8"))
|
|
deny = settings.get("permissions", {}).get("deny", [])
|
|
self.assertFalse([rule for rule in deny if rule == "Agent" or rule.startswith("Agent(")])
|
|
|
|
def test_each_definition_names_itself_and_says_when_to_use_it(self) -> None:
|
|
definitions = sorted(self.AGENTS.glob("*.md"))
|
|
self.assertEqual([path.stem for path in definitions],
|
|
["arch-reviewer", "code-simplifier", "reviewer", "verify-app"])
|
|
for path in definitions:
|
|
fields, _ = front_matter(path)
|
|
self.assertEqual(fields.get("name"), path.stem, path)
|
|
self.assertIn("쓴다", fields.get("description", ""), path)
|
|
self.assertTrue(fields.get("tools"), f"{path} must list its tools; an empty list inherits every tool")
|
|
|
|
def test_no_subagent_can_edit_files(self) -> None:
|
|
for path in self.AGENTS.glob("*.md"):
|
|
tools = {tool.strip() for tool in front_matter(path)[0].get("tools", "").split(",")}
|
|
self.assertFalse(tools & WRITE_TOOLS, f"{path} returns results only; it must not hold {tools & WRITE_TOOLS}")
|
|
|
|
def test_the_reviewers_run_nothing_heavy(self) -> None:
|
|
self.assertNotIn("Bash", front_matter(self.AGENTS / "code-simplifier.md")[0]["tools"])
|
|
reviewer = (self.AGENTS / "arch-reviewer.md").read_text(encoding="utf-8")
|
|
self.assertIn("파일을 쓰거나 고치지 않는다", reviewer)
|
|
self.assertIn("pnpm·node·게이트는 돌리지 않는다", reviewer)
|
|
|
|
def test_no_subagent_can_start_another_subagent(self) -> None:
|
|
# Only the lead starts a wave; a reviewer that spawns reviewers multiplies tokens and hides who saw what.
|
|
for path in self.AGENTS.glob("*.md"):
|
|
tools = {tool.strip() for tool in front_matter(path)[0].get("tools", "").split(",")}
|
|
self.assertNotIn("Agent", tools, path)
|
|
|
|
def test_subagent_descriptions_stay_within_the_budget(self) -> None:
|
|
total = sum(len(front_matter(path)[0].get("description", "")) for path in self.AGENTS.glob("*.md"))
|
|
self.assertLessEqual(total, AGENT_DESCRIPTIONS_LIMIT, "every session carries these; shorten one")
|
|
|
|
def test_the_reviewer_takes_its_lens_from_the_brief_and_the_others_preload_their_skill(self) -> None:
|
|
self.assertNotIn("skills", front_matter(self.AGENTS / "reviewer.md")[0], "the lens changes per brief")
|
|
self.assertIn("렌즈", (self.AGENTS / "reviewer.md").read_text(encoding="utf-8"))
|
|
self.assertEqual(front_matter(self.AGENTS / "arch-reviewer.md")[0].get("skills"), "[fe-structure]")
|
|
self.assertEqual(front_matter(self.AGENTS / "verify-app.md")[0].get("skills"), "[fe-qa]")
|
|
|
|
def test_verify_app_runs_on_the_desktop_under_the_shared_lock(self) -> None:
|
|
text = (self.AGENTS / "verify-app.md").read_text(encoding="utf-8")
|
|
for fragment in ("docs/work/operate.md", "scripts/verify.sh", "flock /tmp/claude-gates/heavy.lock",
|
|
"stash@{0}", "TEST_RUN_ID"):
|
|
self.assertIn(fragment, text)
|
|
|
|
|
|
class SkillTest(unittest.TestCase):
|
|
CANON = {"new-feature": "docs/work/new-feature.md", "desktop-gates": "docs/work/operate.md"}
|
|
|
|
KNOWLEDGE = ["fe-a11y", "fe-design-system", "fe-performance", "fe-qa", "fe-react", "fe-security", "fe-structure",
|
|
"fe-testing", "fe-ux"]
|
|
|
|
def test_the_repository_skills_are_the_two_playbook_skills_and_the_knowledge_skills(self) -> None:
|
|
self.assertEqual(sorted(path.parent.name for path in (CLAUDE / "skills").glob("*/SKILL.md")),
|
|
sorted(list(self.CANON) + self.KNOWLEDGE))
|
|
|
|
def test_each_knowledge_skill_is_path_scoped_short_and_puts_gotchas_first(self) -> None:
|
|
for name in self.KNOWLEDGE:
|
|
path = CLAUDE / "skills" / name / "SKILL.md"
|
|
fields, patterns = front_matter(path)
|
|
self.assertEqual(fields.get("name"), name)
|
|
self.assertNotIn("disable-model-invocation", fields)
|
|
description = fields.get("description", "")
|
|
self.assertLessEqual(len(description), KNOWLEDGE_DESCRIPTION_LIMIT, name)
|
|
for banned in BANNED_IN_DESCRIPTION:
|
|
self.assertNotIn(banned, description, name)
|
|
self.assertIn("paths", fields, f"{name}: paths keeps it out of the listing until its files are touched")
|
|
self.assertTrue(patterns, name)
|
|
text = path.read_text(encoding="utf-8")
|
|
self.assertEqual([line[3:].strip() for line in text.splitlines() if line.startswith("## ")],
|
|
KNOWLEDGE_SECTIONS, name)
|
|
self.assertLessEqual(len(text.splitlines()), KNOWLEDGE_BODY_LIMIT, name)
|
|
for pattern in patterns:
|
|
# A relayout that moves folders leaves a glob matching nothing, and the skill never shows up.
|
|
self.assertTrue(next(REPO.glob(pattern), None), f"{name}: '{pattern}' matches no file")
|
|
|
|
def test_the_experts_manual_names_every_expert(self) -> None:
|
|
manual = (REPO / "docs/work/experts.md").read_text(encoding="utf-8")
|
|
for name in self.KNOWLEDGE + [path.stem for path in (CLAUDE / "agents").glob("*.md")]:
|
|
self.assertIn(name, manual)
|
|
|
|
def test_each_skill_is_model_invoked_and_says_when_in_its_description(self) -> None:
|
|
for name in self.CANON:
|
|
fields, _ = front_matter(CLAUDE / "skills" / name / "SKILL.md")
|
|
self.assertEqual(fields.get("name"), name)
|
|
self.assertNotIn("disable-model-invocation", fields)
|
|
description = fields.get("description", "")
|
|
self.assertLessEqual(len(description), DESCRIPTION_LIMIT, name)
|
|
self.assertIn("쓴다", description, f"{name}: say when to use it")
|
|
self.assertIn("부른다", description, f"{name}: say what the user says that calls it")
|
|
|
|
def test_every_section_a_skill_cites_is_a_heading_of_that_document(self) -> None:
|
|
# The path check (verify:documentation) passes when a cited document is translated or renumbered
|
|
# and the section the skill names is gone: 「Decision rule」 outlived its heading this way.
|
|
missing = []
|
|
for path in sorted((CLAUDE / "skills").glob("*/SKILL.md")):
|
|
for line, target, section in cited_sections(path.read_text(encoding="utf-8")):
|
|
document = REPO / target
|
|
if not document.is_file():
|
|
missing.append(f"{path.parent.name}:{line}: {target} does not exist")
|
|
continue
|
|
names, numbers = headings(document)
|
|
known = numbers if section.endswith("절") and not section.startswith("「") else names
|
|
if section.strip("「」").removesuffix("절") not in known:
|
|
missing.append(f"{path.parent.name}:{line}: {target} has no section {section}")
|
|
self.assertEqual(missing, [], "\n" + "\n".join(missing))
|
|
|
|
def test_the_section_check_reads_each_citation_form(self) -> None:
|
|
text = "\n".join([
|
|
"- 배럴 — `docs/a.md` 「공개 경계」, `docs/b.md` 3·4.1절",
|
|
"- 토큰 — `docs/c.md` 6절 「검사 규칙」, 같은 문서 12절",
|
|
"- 원칙 — `PRODUCT.md` 원칙 1, 「Constraints」",
|
|
"- 골든을 본다(`fe-design-system` 「검증」). 예제가 없으면 「없음」",
|
|
"- `docs/d.md` — 설명. 아래 「함정」",
|
|
])
|
|
self.assertEqual(cited_sections(text), [
|
|
(1, "docs/a.md", "「공개 경계」"), (1, "docs/b.md", "3절"), (1, "docs/b.md", "4.1절"),
|
|
(2, "docs/c.md", "6절"), (2, "docs/c.md", "「검사 규칙」"), (2, "docs/c.md", "12절"),
|
|
(3, "PRODUCT.md", "「Constraints」"),
|
|
(4, ".claude/skills/fe-design-system/SKILL.md", "「검증」"),
|
|
])
|
|
|
|
def test_the_section_check_reads_headings_numbers_and_labels(self) -> None:
|
|
import tempfile
|
|
with tempfile.TemporaryDirectory() as folder:
|
|
document = Path(folder) / "doc.md"
|
|
document.write_text("\n".join([
|
|
"# 제목", "## 3. merge 가능 판정", "### 3.1 열린 결정", "#### 토큰 CSS 검사 규칙 (`check:design-system`)",
|
|
"임의 값(arbitrary value) 정책:", "- 목록 줄: 이름이 아니다", "```text", "## 9. 코드 안 제목", "```",
|
|
]), encoding="utf-8")
|
|
names, numbers = headings(document)
|
|
self.assertEqual(numbers, {"3", "3.1"})
|
|
for name in ("merge 가능 판정", "열린 결정", "토큰 CSS 검사 규칙", "임의 값(arbitrary value) 정책"):
|
|
self.assertIn(name, names)
|
|
self.assertNotIn("코드 안 제목", names)
|
|
self.assertFalse(any(name.startswith("목록 줄") for name in names))
|
|
|
|
# A token name in a skill that the token files do not define sends a reviewer to make a second copy:
|
|
# fe-design-system once asked for `--icon-size-*`, and the tokens are `--size-icon-*`.
|
|
TOKEN_NAMESPACES = ("color", "space", "spacing", "font", "line", "radius", "shadow", "duration", "easing", "size",
|
|
"icon", "breakpoint", "container", "elevation", "layer", "opacity", "palette", "button",
|
|
"field", "dialog", "navigation", "drawer", "toast")
|
|
|
|
def test_every_token_a_skill_names_is_a_defined_token(self) -> None:
|
|
tokens = REPO / "src/presentation/design-system/tokens"
|
|
defined = {match for css in tokens.glob("*.css")
|
|
for match in re.findall(r"(--[a-z0-9-]+)\s*:", css.read_text(encoding="utf-8"))}
|
|
self.assertIn("--size-icon-md", defined)
|
|
for path in sorted((CLAUDE / "skills").glob("*/SKILL.md")):
|
|
for name in re.findall(r"`(--[a-z0-9*-]+)`", path.read_text(encoding="utf-8")):
|
|
if name[2:].split("-")[0] not in self.TOKEN_NAMESPACES:
|
|
continue
|
|
pattern = re.compile("^" + re.escape(name).replace(r"\*", "[a-z0-9-]+") + "$")
|
|
self.assertTrue(any(pattern.match(token) for token in defined),
|
|
f"{path.parent.name}: `{name}` names no token in {tokens.relative_to(REPO)}")
|
|
|
|
def test_each_skill_points_at_its_canonical_playbook_instead_of_copying_it(self) -> None:
|
|
for name, canon in self.CANON.items():
|
|
body = (CLAUDE / "skills" / name / "SKILL.md").read_text(encoding="utf-8")
|
|
self.assertIn(f"정본은 `{canon}`", body)
|
|
self.assertIn("정본이 맞다", body)
|
|
|
|
|
|
class PathRuleTest(unittest.TestCase):
|
|
def test_every_rule_is_scoped_by_paths_that_exist(self) -> None:
|
|
rules = sorted((CLAUDE / "rules").glob("*.md"))
|
|
self.assertEqual([path.stem for path in rules],
|
|
["adapters", "docs", "expert-skills", "features", "gates-and-budgets", "tests"])
|
|
for path in rules:
|
|
fields, patterns = front_matter(path)
|
|
self.assertIn("paths", fields, path)
|
|
self.assertTrue(patterns, path)
|
|
for pattern in patterns:
|
|
# A pattern that matches nothing is a rule nobody reads.
|
|
self.assertTrue(next(REPO.glob(pattern), None), f"{path}: '{pattern}' matches no file")
|
|
|
|
|
|
class GitignoreTest(unittest.TestCase):
|
|
def test_the_shared_claude_files_are_tracked_and_session_state_is_not(self) -> None:
|
|
lines = (REPO / ".gitignore").read_text(encoding="utf-8").splitlines()
|
|
for line in (".claude/*", "!.claude/settings.json", "!.claude/rules/", "!.claude/agents/", "!.claude/skills/"):
|
|
self.assertIn(line, lines)
|
|
|
|
|
|
if __name__ == "__main__":
|
|
unittest.main()
|