docs(work): experts.md 경로 표를 스킬 paths와 맞추고 대조 시험을 둔다
문제: experts.md 3절 「경로 → 전문가」는 리드가 바뀐 경로로 렌즈를 고르는 표이고 "지식 스킬의 paths와 맞춘다"고 적는다. 그런데 손으로 옮긴 표가 열 스킬 중 아홉에서 이미 갈라졌다. 예: be-build-ci의 settings.gradle· gradle.properties·Dockerfile·renovate.json, be-api-contract의 .env.example· docs/upgrade/**, be-observability의 docs/runbooks/**, be-docs의 **/CLAUDE.md가 표에 없다. 표로 렌즈를 고르면 그 파일을 바꾼 변경에서 렌즈가 빠진다. 이름만 보는 시험(test_the_experts_manual_names_every_expert)은 이 차이를 못 잡는다. 고른 방법: 표 1열을 1차 렌즈 스킬의 paths와 똑같이 고치고, 시험이 표를 읽어(중괄호 펼침) 스킬마다 "1차 렌즈로 이름 댄 행의 glob 합집합 == 그 스킬의 paths"를 본다. 표 위 문장에 대조 시험이 있다고 적는다. 버린 대안: 표를 지우고 각 스킬 paths를 읽으라고만 쓰기 — 리드가 렌즈 하나를 고르려고 스킬 열 개의 머리를 읽어야 하고, 「이럴 때 더한다」 칸이 갈 곳이 없다. 위험·한계: 「이럴 때 더한다」 칸은 기계로 대조하지 않는다. 검증: 새 시험 test_the_experts_path_table_lists_exactly_each_skill_paths — 기준 표에서 9개 스킬 실패(be-domain만 통과), 고친 표에서 통과. test_claude_setup 16건 통과, check-work-docs.py·check-docs.py rc=0.
This commit is contained in:
+10
-10
@@ -50,21 +50,21 @@
|
||||
|
||||
## 3. 경로 → 전문가
|
||||
|
||||
리드가 바뀐 경로로 렌즈를 고르는 표다. 지식 스킬의 `paths`와 맞춘다. `reviewer` 하나에는 렌즈 1~3개를 준다. 관점이 서로 다르고 볼 파일이 많으면 `reviewer`를 렌즈별로 나눠 띄운다.
|
||||
리드가 바뀐 경로로 렌즈를 고르는 표다. 1열은 1차 렌즈 스킬의 `paths`를 그대로 옮긴 것이다(`scripts/tests/test_claude_setup.py`가 대조한다. 스킬의 `paths`를 바꾸면 이 표도 바꾼다). `reviewer` 하나에는 렌즈 1~3개를 준다. 관점이 서로 다르고 볼 파일이 많으면 `reviewer`를 렌즈별로 나눠 띄운다.
|
||||
|
||||
| 경로(glob) | 1차 렌즈 | 이럴 때 더한다 |
|
||||
|---|---|---|
|
||||
| `src/domain/core/**`, `src/application/*/**`, `src/shared-contract/**` | be-domain(판정은 `arch-reviewer`) | 오류 코드가 바뀜 → be-api-contract, 포트 계약이 바뀜 → be-testing |
|
||||
| `src/adapter/outbound/persistence-*/**`, `**/db/migration/**` | be-persistence | 새 조회·인덱스 → be-performance, outbox·멱등성 행 → be-messaging, 응답·이벤트 필드로 드러남 → be-api-contract |
|
||||
| `src/adapter/*/messaging*/**`, `src/bootstrap/{outbox-relay,idempotency,durable-operation}/**`, `**/outbox/**`, `**/idempotency/**`, `**/contracts/messaging/**` | be-messaging | 테이블·잠금 → be-persistence, schema version → be-api-contract, handler 권한 표시 → be-security |
|
||||
| `src/adapter/outbound/persistence-*/**`, `**/db/migration/**`, `docs/jpa/**`, `docs/mongodb/**` | be-persistence | 새 조회·인덱스 → be-performance, outbox·멱등성 행 → be-messaging, 응답·이벤트 필드로 드러남 → be-api-contract |
|
||||
| `src/adapter/*/messaging*/**`, `src/bootstrap/{outbox-relay,idempotency,durable-operation}/**`, `**/outbox/**`, `**/idempotency/**`, `**/contracts/messaging/**`, `src/application/core/src/main/java/dev/caskeleton/application/messaging/**` | be-messaging | 테이블·잠금 → be-persistence, schema version → be-api-contract, handler 권한 표시 → be-security |
|
||||
| `src/adapter/inbound/**` | be-api-contract + be-security | 새 조회·목록 → be-performance, 로그·헤더 → be-observability |
|
||||
| `src/bootstrap/app/**`, `**/security/**`, `**/authz/**`, `docs/registries/secrets-classification.yaml`, `docs/security/**` | be-security | env 키·공개 경로 → be-api-contract, `runtimeOnly` 줄·lockfile → be-build-ci |
|
||||
| `docs/registries/{metrics,mdc-keys}.yaml`, `docs/observability/**`, `**/observability/**`, `**/observation/**`, `**/tracing/**`, `src/bootstrap/service-runtime/**` | be-observability | 로그·지표에 실리는 값 → be-security |
|
||||
| `docs/registries/{error-codes,env-keys,headers}.yaml`, `docs/architecture/*-api-surface.txt`, `docs/web/**`, `**/*.graphqls` | be-api-contract | 공개 경로·헤더 → be-security, 계약 시험 → be-testing |
|
||||
| `src/adapter/outbound/**`(위 둘 밖: httpclient, cache-redis, notification, fileserver 등), `**/*Performance*`, `**/jmh/**` | be-performance | 외부 호출 대상·자격 증명 → be-security, 결과 불명 → be-messaging |
|
||||
| `build-logic/**`, `**/build.gradle`, `**/gradle.lockfile`, `gradle/**`, `config/**`, `.gitea/**`, `.github/**`, `scripts/**` | be-build-ci | 새 의존성·버전 → be-security, lane 안 테스트 → be-testing |
|
||||
| `**/src/test/**`, `**/src/testFixtures/**`, `**/src/*Test/**` | be-testing | 계약이 약속하는 동작 → 그 분야 렌즈 |
|
||||
| `docs/**/*.md`, `**/AGENTS.md`, `**/README.md`, `.claude/**/*.md` | be-docs | 문서가 설명하는 동작 → 그 분야 렌즈 |
|
||||
| `src/bootstrap/app/**`, `**/security/**`, `**/authz/**`, `**/authorization/**`, `docs/registries/secrets-classification.yaml`, `docs/security/**`, `.env.example`, `.trivyignore.yaml`, `.github/dependency-vulnerability-policy.md` | be-security | env 키·공개 경로 → be-api-contract, `runtimeOnly` 줄·lockfile → be-build-ci |
|
||||
| `docs/registries/{metrics,mdc-keys}.yaml`, `docs/observability/**`, `docs/runbooks/**`, `**/observability/**`, `**/observation/**`, `**/tracing/**`, `**/*Metrics*`, `**/logback-spring.xml`, `src/bootstrap/service-runtime/**` | be-observability | 로그·지표에 실리는 값 → be-security |
|
||||
| `docs/registries/{error-codes,env-keys,headers}.yaml`, `docs/architecture/*-api-surface.txt`, `docs/web/**`, `docs/security/public-paths-snapshot.txt`, `docs/upgrade/**`, `.env.example`, `**/*.graphqls`, `**/contracts/messaging/**`, `**/released-payload-schemas.sha256` | be-api-contract | 공개 경로·헤더 → be-security, 계약 시험 → be-testing |
|
||||
| `src/adapter/outbound/**`(위 둘 밖: httpclient, cache-redis, notification, fileserver 등), `**/*Performance*`, `**/*PerformanceTest/**`, `**/jmh/**`, `docs/httpclient/performance-baseline.md`, `docs/web/virtual-thread-profile.md` | be-performance | 외부 호출 대상·자격 증명 → be-security, 결과 불명 → be-messaging |
|
||||
| `build-logic/**`, `**/build.gradle`, `settings.gradle`, `gradle/**`, `gradle.properties`, `**/gradle.lockfile`, `**/settings-gradle.lockfile`, `config/**`, `Dockerfile`, `.gitea/**`, `.github/**`, `scripts/**`, `renovate.json` | be-build-ci | 새 의존성·버전 → be-security, lane 안 테스트 → be-testing |
|
||||
| `**/src/test/**`, `**/src/testFixtures/**`, `**/src/*Test/**`, `**/src/*Testkit/**`, `docs/testing/**`, `gradle/container-images.properties` | be-testing | 계약이 약속하는 동작 → 그 분야 렌즈 |
|
||||
| `docs/**/*.md`, `**/AGENTS.md`, `**/README.md`, `**/CLAUDE.md`, `.claude/**/*.md` | be-docs | 문서가 설명하는 동작 → 그 분야 렌즈 |
|
||||
|
||||
## 4. 넘김 지도
|
||||
|
||||
|
||||
@@ -61,6 +61,29 @@ def skill_paths(path: Path) -> list[str]:
|
||||
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)
|
||||
@@ -155,6 +178,14 @@ class SkillTest(unittest.TestCase):
|
||||
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")]:
|
||||
|
||||
Reference in New Issue
Block a user