문제: verify-api 서브에이전트는 desktop worktree에서 `flock /tmp/claude-gates/heavy.lock scripts/bootstrap-local.sh`를 직접 돌린다. bootstrap-local.sh의 ./gradlew에는 --no-daemon이 없어 desktop에 Gradle daemon이 남는다(여러 worktree를 받은 daemon이 compiler worker를 쌓아 메모리를 채운 일이 있다). 5단계가 따르라는 "4.1절의 정리법"은 operate.md에 없다. 고른 방법: `scripts/verify.sh app --on here`로 부른다. verify.sh가 공유 잠금을 잡고 GRADLE_OPTS로 daemon을 끈 채 같은 스크립트를 부른다. 앱은 compose로 떠 있으니 4단계 호출은 그대로다. 정리는 compose down과 git worktree remove만 적고, 못 지우면 보고에 남기게 한다. 버린 대안: bootstrap-local.sh의 ./gradlew에 --no-daemon을 붙이기 — 사람이 노트북에서 처음 돌릴 때는 daemon이 이득이라 스크립트 기본값은 두고, desktop 쪽 진입점(verify.sh)이 끈다. 검증: test_verify_api_runs_the_app_on_the_desktop_under_the_shared_lock을 새 절차로 바꿨다(verify.sh app --on here와 git worktree remove를 요구하고, 잠금만 두른 직접 호출과 "정리법"을 거절). 기준 verify-api.md에서 실패, 고친 파일에서 통과. test_claude_setup 16건 통과.
223 lines
12 KiB
Python
223 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_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()
|