Files
clean-architecture-backend-…/docs/work/experts.md
T
DongHyeonka a638698fc8 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.
2026-11-12 21:40:07 +09:00

11 KiB

전문가 — 누가 무엇을 보고 어떻게 주고받나

이 repo의 분야 전문가 명단과 협업 규칙이다. 절차(쓸지 → 렌즈 고르기 → brief → 병렬 → 합치기·반증 → 넘김 → 충돌 판정 → 고치기 → 재확인 세 라운드까지)는 하네스 플러그인의 lead 스킬이고, 왜 이 모양인지는 claude-harness repo의 설계 문서 「분야 전문가와 협업」이다. 이 문서는 이 repo에서 다른 것만 적는다. 전문가를 더할 때는 new-expert 스킬.

이 repo에서 전문가는 지식 스킬이다. 판정은 분야마다 서브에이전트를 두지 않고, 서브에이전트 reviewer 하나에 스킬 경로를 렌즈로 준다. 렌즈는 brief마다 바뀐다.

리드(메인 세션) ──brief: 렌즈(스킬 경로 1~3) + diff 명령──> reviewer(새 눈, 판정만) ──발견·넘길 것──> 리드 ──> 고치기(리드·하위 세션)
고치는 사람 ──그 분야 파일을 만짐──> 지식 스킬이 목록에 뜸 ──부름──> 같은 점검표로 고친다

이 문서에서 쓰는 말

  • 렌즈: 리뷰어에게 "이 지식 스킬로 보라"고 주는 스킬 경로 1~3개.
  • 리드: 렌즈를 고르고 리뷰어를 띄우고 합치는 메인 세션. 하위 세션을 나눠 맡기는 총괄이면 총괄.
  • 물결: 리뷰어를 한꺼번에 띄우는 차례(한 라운드에 두 번까지). 라운드: 리뷰 → 고치기 → 재확인 한 바퀴(세 번까지).
  • 리뷰어 수: 렌즈 수가 아니라 변경 크기와 누가 고쳤나로 정한다. 남이 쓴 300줄 아래 변경은 0명(리드가 렌즈 스킬을 직접 읽는다), 리드가 고친 300줄 아래 변경은 1명, 그보다 크면 2~4명(lead ①).

1. 큰 그림을 읽는 순서

모든 전문가와 리드가 같은 순서로 읽는다.

  1. 루트 AGENTS.md(무엇인가 · HARD-STOP · 지도)
  2. 이 문서의 자기 칸
  3. 자기 지식 스킬. reviewer는 brief의 렌즈 스킬을, arch-reviewer는 시작할 때 실리는 be-domain을 읽는다
  4. 작업 파일과 가장 가까운 폴더의 AGENTS.md
  5. 스킬이 가리키는 정본 문서(필요한 절만)

2. 명단

지식 스킬은 .claude/skills/<이름>/SKILL.md이고, 그 분야 파일을 만질 때만 목록에 뜬다(paths). 본문 순서는 언제 쓰나·넘기는 곳 → 함정 → 실패는 이렇게 보인다 → 검증 → 이 repo에서 정한 것이다.

전문가 형태 파일 언제 받는 것 내는 것
리드 메인 세션 + lead 스킬 플러그인 둘 이상 분야, PR 전, 의견 충돌 목표·기준 커밋 고른 렌즈, 합친 발견, 충돌 판정
be-domain 스킬(arch-reviewer에 실림) .claude/skills/be-domain/ aggregate·값 객체·불변식·유스케이스·포트·배치 고치는 사람 또는 렌즈 점검표, 검증 명령
be-persistence 스킬 .claude/skills/be-persistence/ 엔티티·repository adapter·마이그레이션·트랜잭션·잠금 같음 같음
be-messaging 스킬 .claude/skills/be-messaging/ outbox·이벤트 계약·relay·소비·inbox·멱등성 같음 같음
be-security 스킬 .claude/skills/be-security/ 인증·권한·공개 경로·입력 검증·비밀·CVE 같음 같음
be-observability 스킬 .claude/skills/be-observability/ 로그·MDC·지표·trace·경보·runbook 같음 같음
be-performance 스킬 .claude/skills/be-performance/ 느림·풀·타임아웃·캐시·성능 lane·측정 같음 같음
be-api-contract 스킬 .claude/skills/be-api-contract/ 응답·오류 코드·헤더·env 키·스냅숏·schema 같음 같음
be-build-ci 스킬 .claude/skills/be-build-ci/ registry·Gradle·lockfile·lane·workflow·게이트 실패 같음 같음
be-testing 스킬 .claude/skills/be-testing/ 테스트·fake·공유 계약·strict lane·거짓 통과 같음 같음
be-docs 스킬 .claude/skills/be-docs/ 매뉴얼·AGENTS.md·README·runbook·ADR·문서 검사 같음 같음
reviewer 서브에이전트(렌즈 = brief의 스킬 경로) .claude/agents/reviewer.md PR 전, 여러 분야 변경, 고친 사람과 다른 눈 렌즈·목표·기준 커밋·diff 명령·판정하지 않을 것 lead 공통 양식, 60줄 이하
arch-reviewer 서브에이전트(skills: [be-domain]) .claude/agents/arch-reviewer.md 계층 규칙·도메인 위치 판정, 커밋·PR 전 기준 커밋·diff·경로 lead 공통 양식
verify-api 서브에이전트 .claude/agents/verify-api.md 동작을 바꾼 변경을 desktop에서 띄워 확인 브랜치·endpoint·기대 응답 결과·호출·증거·남은 것
code-simplifier 서브에이전트 .claude/agents/code-simplifier.md 구현 뒤 단순화 제안 파일·diff 제안(파일:줄), 범위 밖에서 본 것

3. 경로 → 전문가

리드가 바뀐 경로로 렌즈를 고르는 표다. 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/**, 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/**, **/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. 넘김 지도

전문가가 「넘길 것」에 자주 쓰는 길이다. 넘김은 리드를 거친다(서로 직접 부르지 않는다). 리드는 받는 렌즈로 reviewer를 다시 띄우거나, 이미 띄운 reviewer에 이어 묻는다.

보낸 쪽 받는 쪽 무엇을
be-persistence be-api-contract 저장 모양 변경이 응답·이벤트 필드로 드러남
be-persistence be-performance 새 조회의 N+1·인덱스·계획 의심
be-messaging be-persistence outbox·inbox·멱등성 테이블, 마이그레이션, claim 잠금
be-messaging be-api-contract 이벤트 payload 필드·schema version 호환
be-security be-api-contract 공개 경로·헤더·오류 코드 추가
be-security be-observability 로그·지표·span에 실리는 민감 값
be-api-contract be-testing 계약 시험(스냅숏·호환 시험)이 빠짐
be-testing be-build-ci 게이트가 그 시험을 실제로 돌리지 않음
be-build-ci 실패한 leaf의 1차 렌즈 게이트 실패의 원인 분야
be-domain be-persistence · be-messaging 포트 구현, 도메인 이벤트를 통합 이벤트로
누구든 be-docs 동작이 바뀌어 따라 고칠 문서
누구든 프론트 repo 세션 API 계약 차이(다른 repo: 총괄을 거쳐서)

5. 충돌 — 이 repo에서 정해 둔 것

사실 다툼(받는 쪽이 있나, 실제로 깨지나)은 반증으로 먼저 가린다. 가치가 부딪칠 때의 순위는 lead 스킬 ⑦이다(데이터 손실·보안 → 공개 계약 → HARD-STOP → 검증 가능 → 성능 예산 → 디자인·UX 일관성 → 단순함). 공개 계약을 바꾸는 선택, 되돌릴 수 없는 방식 고르기, 같은 순위끼리의 충돌은 소유자가 정한다. 같은 충돌이 두 번 나오면 여기에 한 줄 더한다.

날짜 부딪친 것 정한 것 근거

6. 비용

  • 서브에이전트 설명은 모든 세션의 컨텍스트에 들어간다. 설명의 합을 grep -h '^description:' .claude/agents/*.md | wc -c로 보고 늘면 줄인다. 분야 판정은 reviewer 하나에 렌즈로 주므로 분야를 더해도 서브에이전트 설명은 늘지 않는다.
  • 지식 스킬은 paths를 걸어 그 파일을 만질 때만 목록에 뜨게 한다.
  • 전문가를 더하거나 바꾼 뒤 첫 큰 일은 harness-eval 스킬로 바꾸기 전과 견준다. 작은 diff 리뷰는 판을 가르지 못하니 이 repo 규칙대로 구현하는 과제로 잰다.