문제: 하네스에 분야 지식이 없다. 영속성·메시징·보안·관측·성능·API 계약· 빌드·시험·문서·도메인의 이 repo 규칙(적용된 마이그레이션 금지, 잠금 상한, 동시 인덱스 빌드, env 키 레지스트리 등)은 문서에 흩어져 있어, 세션이 그 문서를 찾아 읽어야만 지킨다. 여러 분야에 걸친 일을 누가 보고 어떻게 합치는지도 정한 곳이 없다. 고른 방법(소유자 결정 2026-11-11 「W3 설계대로」): - 지식 스킬 be-* 10개(.claude/skills/). 각자 paths를 걸어 그 분야 파일을 만질 때만 목록에 뜬다. 본문은 언제 쓰나 → 함정 → 실패는 이렇게 보인다 → 검증 → 이 repo에서 정한 것 순서이고, 정본 문서를 가리킨다. 초안은 이 repo 문서만 본 서브에이전트가 썼고, 경로는 relayout 배치에 맞췄다. - 서브에이전트 reviewer(렌즈 = brief의 스킬 경로). arch-reviewer는 be-domain을 미리 싣고 lead 공통 양식으로 돌려준다. - .claude/rules/expert-skills.md: 분야 파일을 고치기 전에 그 스킬의 「함정」·「검증」을 보게 하는 두 줄(평가에서 스킬 호출이 5번 중 2번이었다). - docs/work/experts.md: 명단·경로 → 렌즈·넘김 지도·충돌·비용. 루트 AGENTS.md 한 줄, CLAUDE.md 두 줄 고침(10줄 상한 유지), README 3절 4단계와 delegate.md 4.3절에 가리키는 말. - 시험: 에이전트 넷, Agent 도구 금지, 설명 합 1,200자, 지식 스킬의 paths· 설명 300자·금지어·절 순서·150줄, 모든 paths glob이 추적 파일에 걸림, 명단이 모든 전문가를 담음. 버린 대안: 분야마다 서브에이전트. Anthropic 2026-10-22·2026-01-23·2026-04-07 글이 반대하고, 설명이 모든 세션에 든다. 위험: 플러그인 lead·new-expert·harness-eval은 claude-harness PR #3(0.3.0)이 병합돼야 받는다. 그전에는 lead를 가리키는 문장이 설명만 남는다. 검증: python3 -m unittest discover -s scripts/tests → 154건 통과. 새 시험 6개는 조건을 깰 때마다 실패했다. scripts/verify.sh docs → rc=0.
100 lines
10 KiB
Markdown
100 lines
10 KiB
Markdown
# 전문가 — 누가 무엇을 보고 어떻게 주고받나
|
|
|
|
이 repo의 분야 전문가 명단과 협업 규칙이다. 절차(쓸지 → 렌즈 고르기 → brief → 병렬 → 합치기·반증 → 넘김 → 충돌 판정 → 고치기 → 재확인 세 라운드까지)는 하네스 플러그인의 `lead` 스킬이고, 왜 이 모양인지는 claude-harness repo의 설계 문서 「분야 전문가와 협업」이다. 이 문서는 이 repo에서 다른 것만 적는다. 전문가를 더할 때는 `new-expert` 스킬.
|
|
|
|
이 repo에서 전문가는 **지식 스킬**이다. 판정은 분야마다 서브에이전트를 두지 않고, 서브에이전트 `reviewer` 하나에 스킬 경로를 **렌즈**로 준다. 렌즈는 brief마다 바뀐다.
|
|
|
|
```text
|
|
리드(메인 세션) ──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. 경로 → 전문가
|
|
|
|
리드가 바뀐 경로로 렌즈를 고르는 표다. 지식 스킬의 `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/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 | 문서가 설명하는 동작 → 그 분야 렌즈 |
|
|
|
|
## 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 규칙대로 구현하는 과제로 잰다.
|