"""루트 지침과 `.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", "") 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_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()