Files
clean-architecture-frontend…/docs/work/experts.md
T
DongHyeonka c0ddc0328e fix(hooks): 살아 있는 지침 문서 편집도 desktop 확인을 알린다
편집 훅 N5는 CLAUDE.md, src/**/AGENTS.md·CLAUDE.md, .claude/ 아래
문서를 노트북 검사(check-work-docs.py)로 끝나는 파일로 센다. 그러나
desktop 게이트 verify:documentation도 그 문서들을 읽는다(경로·명령·
script·FE-GATE ID). 그래서 지침 문서만 고친 턴은 desktop 실행 없이
끝나고, 루트 AGENTS.md와 experts.md도 노트북 검사만 안내한다.

고른 방법: LAPTOP_ONLY에서 문서(.md)를 빼고 .claude/의 문서 밖 파일
(설정·훅 상태)만 남긴다. AGENTS.md 검증 줄과 experts.md 경로표에
desktop verify:documentation을 더한다. 버린 대안: 훅은 두고 문서만
고치기(턴 끝 알림이 계속 빠진다).

위험·한계: 지침 문서만 고친 턴도 이제 desktop 실행 전까지 한 번
막힌다. 막지는 않고 이유를 알린다(N5 동작 그대로).

검증: python3 -m unittest discover -s scripts/tests 72개 통과(노트북).
새 시험 test_living_instruction_documents_need_the_desktop은 고치기 전
코드에서 다섯 경로 모두 실패했다.

Refs: 1112/08-04
2026-11-12 22:46:05 +09:00

12 KiB

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

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

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

리드(메인 세션) ──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와 desktop verify:documentation 문서가 설명하는 동작 → 그 분야 렌즈

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 규칙대로 구현하는 과제로 잰다.