feat(claude): 분야 전문가를 지식 스킬 아홉 개와 렌즈 리뷰어로 두고 협업 명단을 붙인다
frontend-quality-gates / merge / static checks (pull_request) Successful in 3m3s
frontend-quality-gates / merge / tests (pull_request) Failing after 13m34s
frontend-quality-gates / merge / browser tests (pull_request) Successful in 9m26s
frontend-quality-gates / FE-GATE-017 / diagram-review (pull_request) Skipped
frontend-quality-gates / main / checker self-tests (pull_request) Skipped
frontend-quality-gates / FE-GATE-014 / config-compatibility (pull_request) Skipped
frontend-quality-gates / FE-GATE-028 / manual-accessibility-review (pull_request) Skipped
frontend-quality-gates / FE-GATE-026 / lab-performance (pull_request) Skipped
frontend-quality-gates / FE-GATE-015 / immutable-release-candidate (pull_request) Skipped
frontend-quality-gates / external-vulnerability-provider (pull_request) Skipped
frontend-quality-gates / external-provenance-provider (pull_request) Skipped
frontend-quality-gates / promote-verified-immutable-candidate (pull_request) Skipped
frontend-quality-gates / deploy-promoted-release (pull_request) Skipped
frontend-quality-gates / FE-GATE-019 / hosting-header (pull_request) Skipped
frontend-quality-gates / FE-GATE-021 / runbook-boot-config (pull_request) Skipped
frontend-quality-gates / FE-GATE-022 / runbook-chunk-mismatch (pull_request) Skipped
frontend-quality-gates / FE-GATE-023 / runbook-api-degradation (pull_request) Skipped
frontend-quality-gates / FE-GATE-024 / runbook-telemetry (pull_request) Skipped
frontend-quality-gates / FE-GATE-025 / runbook-release-rollback (pull_request) Skipped
frontend-quality-gates / FE-GATE-018 / field-web-vitals (pull_request) Skipped

문제: 하네스에 분야 지식이 없다. QA·디자인/UX·디자인 시스템·React·폴더
구조·시험 환경·접근성·성능·보안의 이 repo 규칙(배럴 경계, 토큰 밖 색 금지,
axe 태그 범위, 예산, FE-GATE 실행법 등)은 문서와 검사기에 흩어져 있고,
여러 분야에 걸친 일을 누가 보고 어떻게 합치는지 정한 곳이 없다.

고른 방법(소유자 결정 2026-11-11 「W3 설계대로」, 백엔드와 같은 모양):
- 지식 스킬 fe-* 9개(.claude/skills/). paths를 걸어 그 분야 파일을 만질 때만
  목록에 뜬다. 본문은 언제 쓰나 → 함정 → 실패는 이렇게 보인다 → 검증 →
  이 repo에서 정한 것 순서. 초안은 이 repo 문서만 본 서브에이전트가 썼고
  glob 75개가 모두 파일에 걸리는 것을 확인했다.
- 서브에이전트 reviewer(렌즈 = brief의 스킬 경로). arch-reviewer는
  fe-structure를, verify-app은 fe-qa를 미리 싣는다(QA 탐색 차터).
- .claude/rules/expert-skills.md: 분야 파일을 고치기 전에 그 스킬의
  「함정」·「검증」을 보게 하는 두 줄.
- docs/work/experts.md: 명단·경로 → 렌즈·넘김 지도(백엔드 repo로 가는 API
  계약 차이는 총괄을 거침)·충돌·비용. 루트 AGENTS.md·CLAUDE.md 한 줄씩,
  README 3절 4단계와 delegate.md 4.3절에 가리키는 말.
- 시험: 에이전트 넷, Agent 도구 금지, 설명 합 1,200자, 미리 싣는 스킬,
  지식 스킬의 paths·설명 300자·금지어·절 순서·150줄·glob이 파일에 걸림,
  명단이 모든 전문가를 담음, 규칙 목록에 expert-skills.
- 문서 PR #15와 겹치지 않게 docs/는 docs/work/만 건드렸다.
버린 대안: 분야마다 서브에이전트(QA·디자인·접근성 …). Anthropic
2026-10-22·2026-01-23·2026-04-07 글이 반대하고, 설명이 모든 세션에 든다.

위험: 플러그인 lead·new-expert·harness-eval은 claude-harness PR #3(0.3.0)이
병합돼야 받는다. fe-ux·fe-a11y의 paths는 템플릿에 기능 화면이 없어
src/presentation/**까지만 건다(기능이 생기면 넓힌다).

검증: scripts/verify.sh docs → rc=0, scripts/verify.sh hooks → 68건 통과.
새 시험은 조건을 깰 때마다 실패했다. desktop merge 단계는 이 커밋 뒤에 돈다.
This commit is contained in:
DongHyeonka
2026-11-11 23:55:59 +09:00
parent 38c0dc7dbf
commit b5e7f54bd1
19 changed files with 1011 additions and 16 deletions
+104
View File
@@ -0,0 +1,104 @@
# 전문가 — 누가 무엇을 보고 어떻게 주고받나
이 repo의 분야 전문가 명단과 협업 규칙이다. 절차(쓸지 → 렌즈 고르기 → brief → 병렬 → 합치기·반증 → 넘김 → 충돌 판정 → 고치기 → 재확인 세 라운드까지)는 하네스 플러그인의 `lead` 스킬이고, 왜 이 모양인지는 claude-harness repo의 설계 문서 「분야 전문가와 협업」이다. 이 문서는 이 repo에서 다른 것만 적는다. 전문가를 더할 때는 `new-expert` 스킬.
이 repo에서 전문가는 **지식 스킬**이다. 판정은 분야마다 서브에이전트를 두지 않고, 서브에이전트 `reviewer` 하나에 스킬 경로를 **렌즈**로 준다. 렌즈는 brief마다 바뀐다.
```text
리드(메인 세션) ──brief: 렌즈(스킬 경로 1~3) + diff 명령──> reviewer(새 눈, 판정만) ──발견·넘길 것──> 리드 ──> 고치기(리드·하위 세션)
고치는 사람 ──그 분야 파일을 만짐──> 지식 스킬이 목록에 뜸 ──부름──> 같은 점검표로 고친다
화면을 봐야 아는 것 ──> verify-app(desktop에서 앱을 띄움, fe-qa를 실음) ──> 리드
```
**이 문서에서 쓰는 말**
- **렌즈**: 리뷰어에게 "이 지식 스킬로 보라"고 주는 스킬 경로 1~3개.
- **리드**: 렌즈를 고르고 리뷰어를 띄우고 합치는 메인 세션. 하위 세션을 나눠 맡기는 총괄이면 총괄.
- **물결**: 리뷰어를 한꺼번에 띄우는 차례(한 라운드에 두 번까지). **라운드**: 리뷰 → 고치기 → 재확인 한 바퀴(세 번까지).
- **리뷰어 수**: 렌즈 수가 아니라 변경 크기와 누가 고쳤나로 정한다. 남이 쓴 300줄 아래 변경은 0명(리드가 렌즈 스킬을 직접 읽는다), 리드가 고친 300줄 아래 변경은 1명, 그보다 크면 2~4명(`lead` ①).
- **서브에이전트**: 한 세션 안에서 띄우는 별도 창. 결과만 돌려주고 파일을 고치지 않는다. **하위 세션**: 사람이 열어 보고 멈출 수 있는 별도 세션. 파일을 바꾸는 큰 위임은 하위 세션이다(`docs/work/delegate.md` 4.3절).
- **게이트**: `scripts/verify.sh`가 돌리는 `config/ci/gates.json`의 검사. pnpm·브라우저·게이트는 누가 돌려도 desktop에서다. 리뷰어의 "통과"는 게이트를 대신하지 않는다.
## 1. 큰 그림을 읽는 순서
모든 전문가와 리드가 같은 순서로 읽는다.
1. 루트 `AGENTS.md`(무엇인가 · 꼭 지킬 것 · 지도)
2. 이 문서의 자기 칸
3. 자기 지식 스킬(「함정」부터). `reviewer`는 brief의 렌즈 스킬을, `arch-reviewer`는 시작할 때 실리는 `fe-structure`를, `verify-app`은 `fe-qa`를 읽는다
4. 작업 파일과 가장 가까운 `src/<계층>/AGENTS.md`
5. 스킬이 가리키는 정본 문서(필요한 절만)
## 2. 명단
지식 스킬은 `.claude/skills/<이름>/SKILL.md`이고, 그 분야 파일을 만질 때만 목록에 뜬다(`paths`). 본문 순서는 언제 쓰나·넘기는 곳 → 함정 → 실패는 이렇게 보인다 → 검증 → 이 repo에서 정한 것이다. 절차 스킬 `new-feature`·`desktop-gates`는 전문가가 아니라 순서표다.
| 전문가 | 형태 | 파일 | 언제 | 받는 것 | 내는 것 |
|---|---|---|---|---|---|
| 리드 | 메인 세션 + `lead` 스킬 | 플러그인 | 둘 이상 분야, PR 전, 의견 충돌 | 목표·기준 커밋 | 고른 렌즈, 합친 발견, 충돌 판정 |
| fe-qa | 스킬(`verify-app`에 실림) | `.claude/skills/fe-qa/` | 사용자 흐름 탐색·버그 재현·회귀 시험 | 고치는 사람 또는 렌즈 | 탐색 차터, 점검표, 검증 명령 |
| fe-ux | 스킬 | `.claude/skills/fe-ux/` | 위계·상태 화면·문구·폼 흐름·반응형·페이지 템플릿 | 같음 | 같음(차터 제외) |
| fe-design-system | 스킬 | `.claude/skills/fe-design-system/` | 토큰·테마·primitive API·아이콘·story·시각 골든 | 같음 | 같음 |
| fe-react | 스킬 | `.claude/skills/fe-react/` | 상태 소유·query·mutation·결과 불명·effect·오류 경계 | 같음 | 같음 |
| fe-structure | 스킬(`arch-reviewer`에 실림) | `.claude/skills/fe-structure/` | 계층·배럴·kernel·기능 경계·공유 타입 위치 | 같음 | 같음 |
| fe-testing | 스킬 | `.claude/skills/fe-testing/` | 시험 층·MSW·대역·흔들림·거짓 통과 | 같음 | 같음 |
| fe-a11y | 스킬 | `.claude/skills/fe-a11y/` | WCAG 2.2 AA·키보드·포커스·이름·대비·수동 기록 | 같음 | 같음 |
| fe-performance | 스킬 | `.claude/skills/fe-performance/` | 번들·청크·lazy·CWV·Service Worker 캐시 | 같음 | 같음 |
| fe-security | 스킬 | `.claude/skills/fe-security/` | XSS·CSP·인증·token·비밀·의존성·advisory | 같음 | 같음 |
| reviewer | 서브에이전트(렌즈 = brief의 스킬 경로) | `.claude/agents/reviewer.md` | PR 전, 여러 분야 변경, 고친 사람과 다른 눈 | 렌즈·목표·기준 커밋·diff 명령·판정하지 않을 것 | lead 공통 양식, 60줄 이하 |
| arch-reviewer | 서브에이전트(`skills: [fe-structure]`) | `.claude/agents/arch-reviewer.md` | 경계 규칙 판정, 커밋·PR 전 | 기준 커밋·diff·경로 | lead 공통 양식 |
| verify-app | 서브에이전트(`skills: [fe-qa]`) | `.claude/agents/verify-app.md` | desktop에서 빌드·preview·라우트 열기, 탐색 QA | 트리·라우트·기대 | 결과·라우트·발견·증거·남은 것 |
| code-simplifier | 서브에이전트 | `.claude/agents/code-simplifier.md` | 구현 뒤 단순화 제안(고를 때만) | 파일·diff | 제안(파일:줄), 범위 밖에서 본 것 |
## 3. 경로 → 전문가
리드가 바뀐 경로로 렌즈 후보를 고르는 표다. 지식 스킬의 `paths`와 맞춘다. 후보 중 변경 내용과 상관없는 것은 리드가 뺀다. `src/presentation/**`는 `fe-a11y` 후보이기도 하다.
| 경로(glob) | 1차 렌즈 | 이럴 때 더한다 |
|---|---|---|
| `tests/e2e/**`, `tests/features/**` | fe-qa(실행은 `verify-app`) | 시험이 흔들리거나 거짓 통과 → fe-testing, `accessibility.spec.ts` → fe-a11y |
| `src/presentation/{pages,layouts,templates,forms,components,i18n}/**` | fe-ux | 포커스·이름 → fe-a11y, 새 variant·토큰 → fe-design-system, 상태·데이터 → fe-react |
| `src/presentation/{design-system,styles}/**`, `.storybook/**`, `tests/{storybook,visual}/**`, `docs/styling/**` | fe-design-system | 키보드·대비 → fe-a11y, 초기 청크 → fe-performance |
| `src/**/*.tsx`, `src/features/**`, `src/application/**`, `src/presentation/adapters/**`, `src/adapters/{http,query-cache}/**`, `config/contracts/**` | fe-react | 자격 증명·저장소 → fe-security, 짝 백엔드 계약 → 백엔드 repo 세션(4절) |
| `src/adapters/*/index.ts`, `src/adapters/platform/**`, `src/{contracts,contexts,apps,bootstrap}/**`, `src/features/*.ts`, `.dependency-cruiser.json`, `docs/architecture/layers.md`, `docs/reviews/adapters/INVENTORY.md` | fe-structure(판정은 `arch-reviewer`) | 번들 경계 → fe-performance, 런타임 설정 키 → fe-security |
| `tests/**`, `vitest.config.ts`, `playwright*.config.ts`, `config/testing/**`, `config/ci/ungated-tests.json` | fe-testing | 시험이 지키는 동작 → 그 분야 렌즈 |
| `src/presentation/**`, `docs/accessibility/**` | fe-a11y | 대비·포커스 표시처럼 디자인 결정 → fe-ux |
| `vite.config.ts`, `vite.service-worker.config.ts`, `config/{performance,scale}/**`, `config/hosting/cache-policy.json`, `src/adapters/service-worker/**`, `src/presentation/routes/**` | fe-performance | 예산·기준선 상향 → 소유자(5절) |
| `src/adapters/{auth,http,storage}/**`, `src/presentation/security/**`, `config/security/**`, `config/hosting/security-headers.json`, `index.html`, `docs/security/**`, `recipes/session-owners/**` | fe-security | HTTP 실패 분류·재전송 → fe-react |
| `package.json`, `pnpm-lock.yaml` | fe-security + fe-performance | 시험 도구만 바뀜 → fe-testing |
| `config/ci/**`, `.gitea/**`, `scripts/**` | 지식 스킬 없음. `.claude/rules/gates-and-budgets.md`와 `desktop-gates` | 그 게이트가 지키는 분야의 렌즈 |
| `docs/**/*.md`, `**/AGENTS.md`, `.claude/**/*.md` | 지식 스킬 없음. `.claude/rules/docs.md`, `scripts/verify.sh docs` | 문서가 설명하는 동작 → 그 분야 렌즈 |
## 4. 넘김 지도
전문가가 「넘길 것」에 자주 쓰는 길이다. 넘김은 리드를 거친다(서로 직접 부르지 않는다). 리드는 받는 렌즈로 `reviewer`를 다시 띄우거나, 이미 띄운 `reviewer`에 이어 묻는다.
| 보낸 쪽 | 받는 쪽 | 무엇을 |
|---|---|---|
| fe-qa(`verify-app`) | fe-ux · fe-a11y · fe-performance | 보기 이상 · 키보드로 못 감 · 느림·청크 실패 |
| fe-qa | fe-testing | 재현은 되는데 시험이 못 잡음, 흔들리는 시험 |
| fe-a11y | fe-ux | 대비·포커스 표시처럼 디자인 결정이 필요한 것 |
| fe-a11y | fe-design-system | 공통 primitive의 의미·키보드 결함(페이지마다 고치지 않는다) |
| fe-ux | fe-design-system | 새 variant·토큰·primitive가 필요함 |
| fe-design-system · fe-structure | fe-performance | 디자인 시스템·배럴·side effect가 초기 청크를 바꿈 |
| fe-react | fe-security | 자격 증명·저장소·오류 원문 노출 |
| fe-security | fe-react | HTTP 실패 분류·결과 불명 재전송 입구 |
| fe-performance | 소유자 | 예산·기준선 상향(꼭 지킬 것 4) |
| fe-testing | 게이트 담당(`.claude/rules/gates-and-budgets.md`) | 그 시험을 어느 게이트도 돌리지 않음(`check:ci:gating`) |
| 누구든 | 백엔드 repo 세션(be-api-contract) | API 계약 차이: 응답 모양·오류 code·멱등성 응답·필드 검증 모양. 다른 repo라 총괄을 거친다. 짝 백엔드 repo는 읽기만 한다 |
## 5. 충돌 — 이 repo에서 정해 둔 것
사실 다툼(받는 쪽이 있나, 실제로 깨지나)은 반증으로 먼저 가린다. 가치가 부딪칠 때의 순위는 `lead` 스킬 ⑦이다(데이터 손실·보안 → 공개 계약 → 꼭 지킬 것 → 검증 가능 → 성능·접근성 예산 → 디자인·UX 일관성 → 단순함). 공개 계약을 바꾸는 선택, 되돌릴 수 없는 방식 고르기, 같은 순위끼리의 충돌은 소유자가 정한다. 이 repo에서는 게이트 기준(문턱·예산·기준선·skip·only)을 올리거나 넓히는 것도 소유자가 정한다(꼭 지킬 것 4, `docs/work/reference/decisions.md` 3절 형식). 같은 충돌이 두 번 나오면 여기에 한 줄 더한다.
- 이미 문서가 정한 것: 저장 중 버튼은 `disabled`가 아니라 `pending`이다(키보드 포커스를 잃지 않게, `docs/manual/02-decision-tables.md` 6절). 시각 골든은 기능 영역을 가리고 찍는다(`docs/work/reference/decisions.md` 2.2절).
- 소유자 결정을 기다리는 충돌(예: 보안 갱신이 초기 JS 예산을 넘기는 경우)은 `docs/work/reference/decisions.md` 3.1절 표에 있다. 여기에 상태를 옮겨 적지 않는다.
| 날짜 | 부딪친 것 | 정한 것 | 근거 |
|---|---|---|---|
## 6. 비용
- 서브에이전트 설명은 모든 세션의 컨텍스트에 들어간다. 설명의 합을 `grep -h '^description:' .claude/agents/*.md | wc -c`로 보고 늘면 줄인다. 분야 판정은 `reviewer` 하나에 렌즈로 주므로 분야를 더해도 서브에이전트 설명은 늘지 않는다.
- 지식 스킬은 `paths`를 걸어 그 파일을 만질 때만 목록에 뜨게 한다.
- 전문가를 더하거나 바꾼 뒤 첫 큰 일은 `harness-eval` 스킬로 바꾸기 전과 견준다. 작은 diff 리뷰는 판을 가르지 못하니 이 repo 규칙대로 구현하는 과제로 잰다.