Files
claude-harness/template/docs/work/experts.md
T
DongHyeonka bd6cbf0b2a feat(template): 새 프로젝트에 분야 전문가 명단 양식을 둔다
문제: new-project.sh로 만든 프로젝트에는 분야 전문가를 어디에 적고,
리드가 바뀐 경로로 무엇을 고르고, 넘김과 충돌을 어떻게 남기는지 정한
자리가 없다. lead 스킬은 그 repo의 docs/work/experts.md를 읽는다.

고른 방법: template/docs/work/experts.md(큰 그림 읽는 순서, 명단,
경로 → 렌즈, 넘김 지도, 정해 둔 충돌, 비용 재는 법)를 빈 양식으로 두고,
루트 AGENTS.md 「일하는 방식」에 한 줄, CLAUDE.md에 플러그인 새 스킬과
전문가 모양 한 줄을 더한다. 루트 40줄 상한은 그대로 지킨다.
버린 대안: 빈 .claude/skills·agents 예시 파일. 예시가 그대로 남으면
모든 세션 목록에 들어가는 빈 전문가가 된다.

위험: 양식만이라 채우기 전에는 lead가 경로표 없이 고른다(스킬이
그때는 바뀐 경로와 위험 신호로만 고르게 되어 있다).

검증: python3 -m unittest discover -s tests → 11건 통과
(새 시험: 양식의 여섯 절, AGENTS.md·CLAUDE.md가 가리키는지).
2026-11-11 22:05:18 +09:00

3.0 KiB

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

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

고치는 메인 세션 ──그 분야 파일을 만짐──> 지식 스킬이 목록에 뜸 ──부름──> 함정·점검표·검증대로 직접 고친다
리드(메인 세션) ──brief + 렌즈(지식 스킬 경로)──> reviewer(새 눈, 판정만) ──발견·넘길 것──> 리드 ──> 고치기

분야 전문가는 지식 스킬이다. 서브에이전트는 분야가 아니라 일(새 눈 리뷰, 실행 검증)마다 둔다.

1. 큰 그림을 읽는 순서

메인 세션과 리뷰어가 같은 순서로 읽는다.

  1. 루트 AGENTS.md(무엇인가 · 꼭 지킬 것 · 지도)
  2. 이 문서의 자기 칸
  3. 렌즈인 지식 스킬(「함정」부터)
  4. 작업 파일과 가장 가까운 폴더의 AGENTS.md
  5. 스킬이 가리키는 정본 문서(필요한 절만)

2. 명단

전문가 형태 파일 언제 내는 것
리드 메인 세션 + lead 스킬 플러그인 둘 이상 분야, PR 전, 의견 충돌 고른 렌즈, 합친 발견, 충돌 판정
(채울 것: 분야) 지식 스킬 .claude/skills/<접두>-<분야>/ (발동 조건, paths) 함정·점검표·검증
(채울 것: 일) 서브에이전트 .claude/agents/<이름>.md (새 눈 리뷰·실행 검증) lead 공통 양식

3. 경로 → 전문가(렌즈)

리드가 바뀐 경로로 렌즈를 고르는 표다. 지식 스킬의 paths와 맞춘다.

경로(glob) 렌즈(지식 스킬) 이럴 때 더한다
(채울 것)

4. 넘김 지도

리뷰어가 「넘길 것」에 자주 쓰는 길이다. 넘김은 리드를 거친다(서로 직접 부르지 않는다).

보낸 렌즈 받는 렌즈 무엇을
(채울 것)

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

순위는 lead 스킬 ⑦이다(데이터 손실·보안 → 공개 계약 → 꼭 지킬 것 → 검증 가능 → 성능·접근성 예산 → 디자인 일관성 → 단순함). 같은 충돌이 두 번 나오면 여기에 한 줄 더한다.

날짜 부딪친 것 정한 것 근거

6. 비용

  • 서브에이전트 설명은 모든 세션의 컨텍스트에 들어간다. 이 repo 서브에이전트 설명의 합을 재고(예: grep -h '^description:' .claude/agents/*.md | wc -c) 늘면 줄인다.
  • 지식 스킬은 paths를 걸어 그 파일을 만질 때만 목록에 뜨게 한다.
  • 전문가를 더하거나 바꾼 뒤 첫 큰 일은 harness-eval로 바꾸기 전과 견준다.