Files
clean-architecture-frontend…/scripts/tests/test_claude_setup.py
T
DongHyeonka 9f8596280c feat(claude): 경로별 규칙·스킬·결과만 돌려주는 서브에이전트를 둔다
Claude Code 세션이 테스트·문서·adapter·게이트 기준·기능 폴더를 고칠 때
읽을 규칙이 루트 한 파일에 섞여 있었고, desktop 실행과 새 기능 절차를
부르는 스킬, 결과만 받는 리뷰어 정의가 없었다.

- .claude/rules/: tests, docs, adapters, gates-and-budgets, features.
  paths로 그 파일을 열 때만 읽힌다.
- .claude/skills/: desktop-gates(scripts/verify.sh로 desktop에서 돌리기),
  new-feature(create:feature부터). 소유자 결정대로 모델이 부르고, 설명에
  발동 조건을 문단으로 쓴다. 본문은 정본 playbook을 가리킨다.
- .claude/agents/: arch-reviewer(경계 규칙), verify-app(desktop에서
  빌드·브라우저 확인), code-simplifier. 쓰기 도구가 없다.
- .claude/settings.json: 하네스 플러그인 harness@claude-harness를 켜고
  실제 .env 읽기·쓰기를 막는다. Agent deny는 두지 않는다.
- .gitignore: .claude/는 이 넷만 추적하고 worktree·훅 상태·
  settings.local.json은 무시한다.

버린 대안: Agent deny 유지(소유자 결정 2026-11-07 Q5가 풀었다), 스킬을
사용자 호출 전용으로(Q9가 모델 호출을 골랐다).

위험·한계: 규칙 paths는 지금 있는 파일로 시험하지만 Claude Code가 실제로
읽는지는 이 세션에서 보지 않았다(설정은 세션 시작에 읽힌다).

검증: python3 -m unittest scripts/tests/test_claude_setup.py 통과
(서브에이전트 쓰기 도구 없음, 스킬 설명 길이와 발동 조건, 규칙 paths가
가리키는 파일 있음).

Refs: design-docs harness/01-harness-design.md 13절 Q3·Q5·Q9
2026-11-08 17:27:39 +09:00

140 lines
6.9 KiB
Python

"""루트 지침과 `.claude/`의 규칙·스킬·서브에이전트가 소유자 결정(2026-11-07)대로인지 본다.
결과만 받는 일은 서브에이전트, 파일을 바꾸는 위임은 하위 세션이다(docs/work/delegate.md 4.3절).
새 스킬은 모두 모델이 부를 수 있고, 설명에 발동 조건을 문단으로 적는다.
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"}
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 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", "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_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"}
def test_the_repository_skills_are_the_two_the_manual_names(self) -> None:
self.assertEqual(sorted(path.parent.name for path in (CLAUDE / "skills").glob("*/SKILL.md")), sorted(self.CANON))
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", "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()