Files
clean-architecture-backend-…/scripts/tests/test_claude_setup.py
DongHyeonka 2249d44278
pr / done (pull_request) Canceled after 0s
docs(claude): 지식 스킬의 「명령은 src/에서」를 고치고 옛 Gradle 루트 지시를 막는다
문제: be-api-contract·be-domain·be-persistence·be-security의 「검증」 절이
"명령은 `src/`에서다"라고 한다. 분야 스킬은 Gradle 루트를 저장소 루트로
옮긴 뒤에 들어왔는데 옛 위치를 적었다. 그대로 따르면 gradlew가 없는
폴더에서 명령을 돌린다. operate.md 4.1절의 같은 꼴은 앞 커밋이 고쳤다.

고른 방법: 네 줄을 "저장소 루트에서다"로 고치고, 진입 문서(AGENTS.md·
CLAUDE.md·docs/work/·.claude/)에 "명령은 `src/`에서"나 `cd …/src`가 남으면
실패하는 시험을 둔다.

검증: 새 시험 test_no_instruction_runs_gradle_from_the_old_src_root —
기준 스킬 넷에서 4건, 기준 operate.md에서 2건(57·87줄)을 잡고, 이
커밋에서 통과. scripts/tests 158건 통과, check-work-docs.py rc=0.
2026-11-12 21:42:56 +09:00

233 lines
12 KiB
Python

"""`.claude/`의 서브에이전트 정의와 스킬이 소유자 결정(2026-11-07, 2026-11-11)대로인지 본다.
결과만 받는 일은 서브에이전트, 파일을 바꾸는 위임은 하위 세션이다(docs/work/delegate.md 4.3절).
새 스킬은 모두 모델이 부를 수 있고, 설명에 발동 조건을 적는다.
분야 전문가는 `paths`를 건 지식 스킬(`be-*`)이고, 분야 판정은 서브에이전트 `reviewer` 하나에 렌즈로 준다
(docs/work/experts.md). 서브에이전트 설명은 모든 세션의 컨텍스트에 들어가니 합에 상한을 둔다.
python3 -m unittest discover -s scripts/tests
"""
from __future__ import annotations
import json
import re
import subprocess
import unittest
from pathlib import Path
REPO = Path(__file__).resolve().parent.parent.parent
AGENTS = REPO / ".claude/agents"
SKILLS = REPO / ".claude/skills"
# 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>")
EXPERTS = REPO / "docs/work/experts.md"
def tracked_files() -> list[str]:
out = subprocess.run(["git", "-C", str(REPO), "ls-files"], capture_output=True, text=True, check=True).stdout
return [line for line in out.splitlines() if line]
def glob_regex(pattern: str) -> re.Pattern[str]:
"""A `paths` glob as Claude Code reads it: `**/` any folders, `*` one segment, `{a,b}` either."""
out, i = "", 0
while i < len(pattern):
if pattern.startswith("**/", i):
out, i = out + "(?:.*/)?", i + 3
elif pattern.startswith("**", i):
out, i = out + ".*", i + 2
elif pattern[i] == "*":
out, i = out + "[^/]*", i + 1
elif pattern[i] == "{":
end = pattern.index("}", i)
out, i = out + "(?:" + "|".join(re.escape(part) for part in pattern[i + 1:end].split(",")) + ")", end + 1
else:
out, i = out + re.escape(pattern[i]), i + 1
return re.compile(out)
def skill_paths(path: Path) -> list[str]:
head = re.match(r"^---\n(.*?)\n---\n", path.read_text(encoding="utf-8"), re.S).group(1)
block = re.search(r"^paths:\n((?:\s+-\s+.*\n?)+)", head, re.M)
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)
if not match:
return {}
fields = {}
for line in match.group(1).splitlines():
key, _, value = line.partition(":")
fields[key.strip()] = value.strip()
return fields
class SubagentTest(unittest.TestCase):
def test_the_agent_tool_is_no_longer_denied(self) -> None:
settings = json.loads((REPO / ".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(AGENTS.glob("*.md"))
self.assertEqual([path.stem for path in definitions],
["arch-reviewer", "code-simplifier", "reviewer", "verify-api"])
for path in definitions:
fields = front_matter(path)
self.assertEqual(fields.get("name"), path.stem, path)
self.assertRegex(fields.get("description", ""), r"쓴다", 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 AGENTS.glob("*.md"):
tools = {tool.strip() for tool in front_matter(path).get("tools", "").split(",")}
self.assertFalse(tools & WRITE_TOOLS, f"{path} returns results only; it must not hold {tools & WRITE_TOOLS}")
def test_the_reviewers_have_no_shell_that_could_change_the_tree_except_read_commands(self) -> None:
self.assertNotIn("Bash", front_matter(AGENTS / "code-simplifier.md")["tools"])
reviewer = (AGENTS / "arch-reviewer.md").read_text(encoding="utf-8")
self.assertIn("파일을 쓰거나 고치지 않는다", 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 AGENTS.glob("*.md"):
tools = {tool.strip() for tool in front_matter(path).get("tools", "").split(",")}
self.assertNotIn("Agent", tools, path)
def test_subagent_descriptions_stay_within_the_budget(self) -> None:
total = sum(len(front_matter(path).get("description", "")) for path in 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_arch_reviewer_preloads_the_domain_skill(self) -> None:
reviewer = (AGENTS / "reviewer.md").read_text(encoding="utf-8")
self.assertNotIn("skills", front_matter(AGENTS / "reviewer.md"), "the lens changes per brief")
self.assertIn("렌즈", reviewer)
self.assertEqual(front_matter(AGENTS / "arch-reviewer.md").get("skills"), "[be-domain]")
def test_verify_api_runs_the_app_on_the_desktop_under_the_shared_lock(self) -> None:
text = (AGENTS / "verify-api.md").read_text(encoding="utf-8")
# verify.sh takes the shared lock and turns the Gradle daemon off; a bare flock around the bootstrap script
# left a daemon behind on the desktop, and the cleanup it pointed at was in no manual.
for fragment in ("docs/work/operate.md", "scripts/verify.sh app --on here", "scripts/bootstrap-local.sh",
"stash@{0}", "down", "git worktree remove"):
self.assertIn(fragment, text)
self.assertNotIn("heavy.lock scripts/bootstrap-local.sh", text)
self.assertNotIn("정리법", text)
class SkillTest(unittest.TestCase):
CANON = {"new-feature": "docs/work/new-feature.md", "desktop-gates": "docs/work/operate.md"}
KNOWLEDGE = ["be-api-contract", "be-build-ci", "be-docs", "be-domain", "be-messaging", "be-observability",
"be-performance", "be-persistence", "be-security", "be-testing"]
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 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 = SKILLS / name / "SKILL.md"
fields = 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.assertTrue(skill_paths(path), f"{name}: paths keeps it out of the listing until its files are touched")
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)
def test_every_knowledge_skill_glob_matches_a_tracked_file(self) -> None:
# A relayout that moves folders leaves a glob matching nothing, and the skill silently never shows up.
files = tracked_files()
for name in self.KNOWLEDGE:
for pattern in skill_paths(SKILLS / name / "SKILL.md"):
rx = glob_regex(pattern)
self.assertTrue(any(rx.fullmatch(f) for f in files), f"{name}: {pattern} matches no tracked file")
def test_no_instruction_runs_gradle_from_the_old_src_root(self) -> None:
# The Gradle root moved from src/ to the repository root (2026-11-11). An instruction that still says
# "run it in src/" sends a session to a folder with no gradlew.
stale = re.compile(r"명령은 `src/`에서|cd [^`'&;|]*?/src(?=[ `'&;]|$)", re.M)
roots = [REPO / ".claude", REPO / "docs/work"]
files = [REPO / "AGENTS.md", REPO / "CLAUDE.md"] + [f for root in roots for f in root.rglob("*.md")]
hits = [f"{f.relative_to(REPO)}:{n}" for f in files if "worktrees" not in f.relative_to(REPO).parts
for n, line in enumerate(f.read_text(encoding="utf-8").splitlines(), 1) if stale.search(line)]
self.assertEqual(hits, [])
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")]:
self.assertIn(name, manual)
rule = (REPO / ".claude/rules/expert-skills.md").read_text(encoding="utf-8")
self.assertIn("docs/work/experts.md", rule)
self.assertIn("「함정」", rule)
def test_each_skill_is_model_invoked_and_says_when_in_its_description(self) -> None:
for name in self.CANON:
fields = front_matter(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_each_skill_points_at_its_canonical_playbook_instead_of_copying_it(self) -> None:
for name, canon in self.CANON.items():
body = (SKILLS / name / "SKILL.md").read_text(encoding="utf-8")
self.assertIn(f"정본은 `{canon}`", body)
self.assertIn("정본이 맞다", body)
def test_the_uninstalled_skill_lock_is_gone(self) -> None:
self.assertFalse((REPO / "skills-lock.json").exists())
if __name__ == "__main__":
unittest.main()