계층별 규칙이 Claude만 읽는 .claude/rules/에만 있어 다른 에이전트에는 보이지 않았다. 하네스 자료의 3단계는 레이어마다 그 폴더에 AGENTS.md다. src/의 9개 계층 폴더마다 AGENTS.md(16~20줄)를 둔다: 그 폴더가 하는 일, 그 폴더에만 걸리는 import 금지(.dependency-cruiser.json에서 from이 그 폴더에 맞는 규칙을 뽑아 이름과 함께), 검사하는 게이트, 테스트 위치. 모든 폴더에 걸리는 규칙은 루트 AGENTS.md와 layers.md를 가리킨다. 옆에 @AGENTS.md 한 줄 CLAUDE.md를 둬 Claude Code가 그 폴더 파일을 열 때 같은 책을 읽는다(백엔드와 같은 짝). - .claude/rules/adapters·features는 폴더 AGENTS.md를 가리키게 줄였다. - scripts/check-work-docs.py: src/**/AGENTS.md도 이력 ID 0·200줄·짝·링크를 본다. 훅 N5는 이 파일들을 노트북 확인 파일로 친다. - docs/reviews/adapters/INVENTORY.md: check:adapter-inventory가 src/adapters 아래 추적 파일을 모두 요구하므로 두 행(142·143)을 더했다. - 루트 AGENTS.md 지도가 가장 가까운 src/<계층>/AGENTS.md와 비전·문제 정의 양식을 가리킨다. 버린 대안: .claude/rules/만 두기(다른 에이전트가 못 읽는다), 폴더 CLAUDE.md 없이 AGENTS.md만(Claude Code는 같은 폴더에 CLAUDE.md가 없고 Read로 열 때만 읽어 백엔드와 갈린다). 위험·한계: 규칙 이름은 지금 규칙 파일에서 뽑았다. 규칙을 더하거나 바꾸면 이 문서도 손으로 고쳐야 한다(정본은 규칙 파일과 check:architecture). 검증: scripts/verify.sh docs rc=0(src/**/AGENTS.md 9개, 최대 20/200), python3 -m unittest discover -s scripts/tests 62건 통과.
162 lines
8.3 KiB
Python
162 lines
8.3 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 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", "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()
|