문제: 하네스에 분야 지식이 없다. 영속성·메시징·보안·관측·성능·API 계약· 빌드·시험·문서·도메인의 이 repo 규칙(적용된 마이그레이션 금지, 잠금 상한, 동시 인덱스 빌드, env 키 레지스트리 등)은 문서에 흩어져 있어, 세션이 그 문서를 찾아 읽어야만 지킨다. 여러 분야에 걸친 일을 누가 보고 어떻게 합치는지도 정한 곳이 없다. 고른 방법(소유자 결정 2026-11-11 「W3 설계대로」): - 지식 스킬 be-* 10개(.claude/skills/). 각자 paths를 걸어 그 분야 파일을 만질 때만 목록에 뜬다. 본문은 언제 쓰나 → 함정 → 실패는 이렇게 보인다 → 검증 → 이 repo에서 정한 것 순서이고, 정본 문서를 가리킨다. 초안은 이 repo 문서만 본 서브에이전트가 썼고, 경로는 relayout 배치에 맞췄다. - 서브에이전트 reviewer(렌즈 = brief의 스킬 경로). arch-reviewer는 be-domain을 미리 싣고 lead 공통 양식으로 돌려준다. - .claude/rules/expert-skills.md: 분야 파일을 고치기 전에 그 스킬의 「함정」·「검증」을 보게 하는 두 줄(평가에서 스킬 호출이 5번 중 2번이었다). - docs/work/experts.md: 명단·경로 → 렌즈·넘김 지도·충돌·비용. 루트 AGENTS.md 한 줄, CLAUDE.md 두 줄 고침(10줄 상한 유지), README 3절 4단계와 delegate.md 4.3절에 가리키는 말. - 시험: 에이전트 넷, Agent 도구 금지, 설명 합 1,200자, 지식 스킬의 paths· 설명 300자·금지어·절 순서·150줄, 모든 paths glob이 추적 파일에 걸림, 명단이 모든 전문가를 담음. 버린 대안: 분야마다 서브에이전트. Anthropic 2026-10-22·2026-01-23·2026-04-07 글이 반대하고, 설명이 모든 세션에 든다. 위험: 플러그인 lead·new-expert·harness-eval은 claude-harness PR #3(0.3.0)이 병합돼야 받는다. 그전에는 lead를 가리키는 문장이 설명만 남는다. 검증: python3 -m unittest discover -s scripts/tests → 154건 통과. 새 시험 6개는 조건을 깰 때마다 실패했다. scripts/verify.sh docs → rc=0.
188 lines
9.7 KiB
Python
188 lines
9.7 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 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")
|
|
for fragment in ("docs/work/operate.md", "flock /tmp/claude-gates/heavy.lock", "scripts/bootstrap-local.sh",
|
|
"stash@{0}", "down"):
|
|
self.assertIn(fragment, 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_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()
|