"""`.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", "") 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//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()