From 9735c3366c2145b413a90f6c8b44db7333ec1454 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Wed, 11 Nov 2026 22:22:10 +0900 Subject: [PATCH] =?UTF-8?q?docs(lead):=20cold-read=EC=97=90=EC=84=9C=20?= =?UTF-8?q?=EB=82=98=EC=98=A8=20=EB=B9=88=ED=8B=88=EC=9D=84=20lead=20?= =?UTF-8?q?=EC=A0=88=EC=B0=A8=EC=99=80=20=EB=AA=85=EB=8B=A8=20=EC=96=91?= =?UTF-8?q?=EC=8B=9D=EC=97=90=20=EB=A9=94=EC=9A=B4=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: 이 대화를 모르는 서브에이전트에게 lead·명단 양식·new-expert·설계 일부만 주고 리뷰를 시켰더니(cold-read) 짐작한 곳 22개가 나왔다. 실질적인 것: 크기 기준이 없음, 물결과 라운드가 같은지 모름, 사실 다툼과 가치 충돌의 순서, 남의 브랜치를 리드가 고쳐도 되나, 넓은 paths로 렌즈가 다섯 붙음, 렌즈를 묶는 기준, 시험 파일을 누구 렌즈에, 심각도 단계, reviewer·arch-reviewer·verify·simplifier를 언제, 기준 커밋 정의, 리뷰어가 시험을 돌려도 되나, 소유자가 누구인가, 멈춤 조건. 고른 방법: lead에 물결·라운드 정의와 그림, 크기 기준(brief 우선), merge-base 기준 커밋, 렌즈는 후보이고 상관없는 것은 뺌, 묶는 기준 (같은 물음끼리, 반대 입장은 나눔), 시험 파일 배정, 리뷰어 종류, 심각도 네 단계, 사실 먼저 반증 → 가치 충돌만 순위, 소유자 정의, 남의 브랜치는 돌려줌, 멈춤 조건을 넣는다. 명단 양식에는 말뜻(렌즈·물결· 라운드·하위 세션·게이트)과 소유자 단서를 넣는다. 설계 4절에 규칙 셋, 5.1에 초안이 실제 repo로 맞춘 백엔드 경로를 반영한다. 버린 대안: 말뜻을 lead 스킬 안에 모두 두기. 스킬 본문이 길어지고 repo마다 쓰는 이름이 달라 명단 문서가 맞는 자리다. 위험: lead 본문이 약 120줄로 늘었다(상한 500줄 안). 프론트 경로는 아직 실제 repo와 맞추지 않았다. 검증: python3 -m unittest discover -s tests → 11건 통과, claude plugin validate --strict plugins/harness → 통과. --- docs/experts.md | 24 +++++++------ plugins/harness/skills/lead/SKILL.md | 51 ++++++++++++++++------------ template/docs/work/experts.md | 20 +++++++---- 3 files changed, 57 insertions(+), 38 deletions(-) diff --git a/docs/experts.md b/docs/experts.md index 5e166e6..ee0cb51 100644 --- a/docs/experts.md +++ b/docs/experts.md @@ -116,28 +116,30 @@ | 반증 | High 이상은 리드가 직접, 또는 "틀렸음을 보여라" 서브에이전트로 반증해 살아남은 것만 | 공식 code-review·claude-security와 Claude Code 팀 리뷰는 발견 → 독립 투표·반증 → 통과분만 게시한다(S15, S27) | | 넘김 | 리뷰어끼리 직접 부르지 않는다. 리드가 모아 두 번째 물결 한 번. 세 번째는 없다 | 서브에이전트는 서로 대화하지 못한다(S29). 끝없는 상호 호출을 막는다 | | 충돌 | 데이터 손실·보안 → 공개 계약 → 꼭 지킬 것 → 검증 가능 → 성능·접근성 예산 → 디자인 일관성 → 단순함. 되돌릴 수 없는 선택·같은 순위는 소유자 | 리드가 매번 새로 따지지 않게 순서를 미리 정한다 **[내 판단]** | -| 재확인 | 리뷰-수정 세 번까지, 두 번째부터 고친 diff만, 지난 발견 목록을 brief에 | Claude Code 팀: 작성·리뷰 에이전트가 한 PR에서 밤새 50번 넘게 돌았고, 상한 3과 diff만 재리뷰로 풀었다(S27) | +| 재확인 | 라운드(리뷰 → 고치기 → 재확인)는 세 번까지, 두 번째 라운드부터 고친 diff와 지난 발견 목록만. 물결(리뷰어를 띄우는 차례)은 한 라운드에 두 번까지 | Claude Code 팀: 작성·리뷰 에이전트가 한 PR에서 밤새 50번 넘게 돌았고, 상한 3과 diff만 재리뷰로 풀었다(S27) | +| 사실과 가치 | "받는 쪽이 있나" 같은 사실 다툼은 반증으로 먼저, 가치 충돌만 순위로 | 순위는 가치만 정한다. 사실을 순위로 정하면 틀린 쪽이 이길 수 있다(cold-read에서 나온 빈틈) | +| 남의 브랜치 | 리드는 고치지 않고 작성자에게 돌려준다. 리드가 이미 새 눈이어도 렌즈가 셋을 넘으면 리뷰어로 나눈다 | 고친 사람과 리뷰한 사람이 섞이면 누가 책임지는지 흐려진다 | --- ## 5. 전문가 목록 -경로는 기준 커밋의 것이다. 백엔드 relayout이 병합되면 적용 때 다시 맞춘다. +경로는 기준 커밋의 것이다. 백엔드 표는 초안을 쓴 서브에이전트가 `git ls-tree`로 실제 경로와 맞췄고(proto는 grpc-library로 옮겨 빠짐, 시험 source set은 `*Test`·`*Testkit`, 관측·메시징·계약·보안·빌드 경로를 더함), 프론트 표는 아직 맞추지 않았다. 백엔드 relayout이 병합되면 적용 때 다시 맞춘다. 초안 원본은 공유 노트 폴더 `w3-harness-v2/be-drafts/`다. ### 5.1 백엔드 — 지식 스킬 10 | 분야 | 지식 스킬 | `paths` 요지 | 렌즈로 자주 같이 쓰는 것 | |---|---|---|---| | 도메인 모델링 | `be-domain` | `src/domain-core/**`, `src/application-*/**`, `src/shared-contract/**` | `arch-reviewer`가 미리 싣는다 | -| 영속성(JPA·마이그레이션) | `be-persistence` | `src/adapter/outbound/persistence-*/**`, `**/db/migration/**` | `be-performance`(조회), `be-api-contract`(저장 모양이 응답에 드러날 때) | -| 메시징 | `be-messaging` | `src/adapter/*/messaging*/**`, `src/composition/{outbox-relay,idempotency,durable-operation}/**` | `be-persistence`(전달 보장은 저장과 같은 판정) | -| 보안 | `be-security` | `src/adapter/inbound/**`, `src/app-bootstrap/**`, `**/security/**`, `docs/registries/secrets-*` | `be-observability`(로그의 개인 정보), 공격 시험은 red team 플러그인 | -| 관측 | `be-observability` | `docs/registries/{metrics,mdc-keys}.yaml`, `src/composition/service-runtime/**`, `**/*Metrics*` | `be-security` | -| 성능 | `be-performance` | `src/adapter/outbound/**`, `**/*Performance*`, `**/jmh/**` | `be-persistence` | -| API 계약 | `be-api-contract` | `src/adapter/inbound/**`, `docs/architecture/*-api-surface.txt`, `docs/registries/{error-codes,env-keys,headers}.yaml`, `**/*.proto`, `**/*.graphqls` | `be-testing`(계약 시험) | -| 빌드·CI | `be-build-ci` | `src/build-logic/**`, `**/build.gradle`, `src/gradle/**`, `.gitea/**`, `scripts/**` | 실패한 모듈의 분야 | -| 시험 | `be-testing` | `**/src/test/**`, `**/src/testFixtures/**`, `**/src/integrationTest/**` | 고친 분야(기능을 고친 사람이 시험도 고친다, S28) | -| 문서 | `be-docs` | `docs/**`, `**/AGENTS.md`, `**/README.md` | 문서 검사 스크립트가 판정 | +| 영속성(JPA·마이그레이션) | `be-persistence` | `src/adapter/outbound/persistence-*/**`, `**/db/migration/**`, `docs/jpa/**`, `docs/mongodb/**` | `be-performance`(조회), `be-api-contract`(저장 모양이 응답에 드러날 때) | +| 메시징 | `be-messaging` | `src/adapter/*/messaging*/**`, `src/composition/{outbox-relay,idempotency,durable-operation}/**`, `**/outbox/**`, `**/idempotency/**` | `be-persistence`(전달 보장은 저장과 같은 판정) | +| 보안 | `be-security` | `src/adapter/inbound/**`, `src/app-bootstrap/**`, `**/security/**`, `**/authz/**`, `docs/security/**`, `docs/registries/secrets-*` | `be-observability`(로그의 개인 정보), 공격 시험은 red team 플러그인 | +| 관측 | `be-observability` | `docs/registries/{metrics,mdc-keys}.yaml`, `**/observability/**`, `**/observation/**`, `**/tracing/**`, `**/logback-spring.xml`, `**/*Metrics*` | `be-security` | +| 성능 | `be-performance` | `src/adapter/outbound/**`, `**/*PerformanceTest/**`, `**/*Performance*` | `be-persistence` | +| API 계약 | `be-api-contract` | `src/adapter/inbound/**`, `docs/web/**`, `docs/architecture/*-api-surface.txt`, `docs/registries/{error-codes,env-keys,headers}.yaml`, `docs/upgrade/**`, `**/*.graphqls` | `be-testing`(계약 시험) | +| 빌드·CI | `be-build-ci` | `src/build-logic/**`, `**/build.gradle`, `src/gradle/**`, `src/settings.gradle`, lockfile, `.gitea/**`, `scripts/**` | 실패한 모듈의 분야 | +| 시험 | `be-testing` | `**/src/test/**`, `**/src/testFixtures/**`, `**/src/*Test/**`, `**/src/*Testkit/**` | 고친 분야(기능을 고친 사람이 시험도 고친다, S28) | +| 문서 | `be-docs` | `docs/**/*.md`, `**/AGENTS.md`, `**/README.md` | 문서 검사 스크립트가 판정 | 서브에이전트: `reviewer`(새) · `arch-reviewer`(+`skills: [be-domain]`) · `verify-api` · `code-simplifier`. 있는 스킬 `new-feature`·`desktop-gates`는 그대로. diff --git a/plugins/harness/skills/lead/SKILL.md b/plugins/harness/skills/lead/SKILL.md index 110bf6f..f13b147 100644 --- a/plugins/harness/skills/lead/SKILL.md +++ b/plugins/harness/skills/lead/SKILL.md @@ -5,36 +5,44 @@ description: Use when a change, review, or design spans more than one expert are # lead — 분야 지식을 고르고, 맡기고, 합친다 -리드는 지금 대화하는 메인 세션(또는 총괄)이다. 명단·경로표·넘김 지도는 그 repo의 `docs/work/experts.md`이고, 이 스킬은 어느 repo에서나 같은 절차다. 둘이 다르면 repo 문서가 맞다. 이유는 claude-harness `docs/experts.md`다. +리드는 지금 대화하는 메인 세션이다(하위 세션을 나눠 맡기는 총괄이면 총괄). 명단·경로표·넘김 지도·말뜻은 그 repo의 `docs/work/experts.md`이고, 이 스킬은 어느 repo에서나 같은 절차다. 둘이 다르면 repo 문서가 맞다. 이유는 claude-harness `docs/experts.md`다. ```text 분야 전문가 = 지식 스킬(paths). 고칠 때는 메인이 그 스킬을 부르고 직접 고친다. 새 눈이 필요하면 = reviewer 서브에이전트에 렌즈(읽을 지식 스킬)를 주고 띄운다. -변경 ─> ①쓸지 ─> ②렌즈 고르기 ─> ③brief ─> ④병렬 ─> ⑤합치기·반증 ─> ⑥넘김 한 번 ─> ⑦충돌 ─> ⑧고치기 ─> ⑨재확인(≤3회) +①쓸지 ─> ②렌즈 ─> ③brief ─> ④물결 1(병렬) ─> ⑤합치기·반증 ─> ⑥물결 2(넘김) ─> ⑦충돌 ─> ⑧고치기 ─> ⑨재확인 + └────────────────── 라운드 하나 ──────────────────┘ 라운드는 세 번까지 ``` +- **물결**: 리뷰어를 한꺼번에 띄우는 차례. 한 라운드에 두 번까지(처음 + 넘김). +- **라운드**: 리뷰 → 고치기 → 재확인 한 바퀴. 세 번까지. + ## ① 쓸지 정하기 - 서브에이전트 하나는 별도 컨텍스트이고 토큰을 몇 배 쓴다. 역할(계획·구현·시험·리뷰)이나 분야마다 나누지 않는다. 쓸 때는 셋뿐이다: 새 눈이 필요한 리뷰·검증, 파일 10개 넘게 읽어야 하는 조사, 출력이 긴 실행(앱·브라우저·게이트). -- 크기별 상한: 작음 0명(그 분야 스킬만) · 중간 1~2명 · 큼 2~4명. 한 물결에 4명을 넘기지 않는다. +- 크기는 brief가 정한 것을 쓴다. 없으면: 분야 하나·파일 몇 개는 작음, 분야 둘은 중간, 분야 셋 이상이거나 공개 계약·마이그레이션·인증이 걸리면 큼. +- 크기별 리뷰어 수: 작음 0명(그 분야 스킬만) · 중간 1~2명 · 큼 2~4명. 한 물결에 4명을 넘기지 않는다. +- 남이 쓴 브랜치를 리뷰할 때 리드는 이미 새 눈이다. 그래도 렌즈가 셋을 넘으면 넓은 읽기라서 리뷰어로 나눈다. - 기능을 고치는 사람이 그 시험도 고친다. 시험만 따로 맡기지 않는다. ## ② 렌즈 고르기 -1. `git diff --name-only <기준>...`로 바뀐 경로를 본다. -2. `docs/work/experts.md` 「경로 → 전문가」로 경로마다 지식 스킬을 고른다. 이것이 렌즈다. +1. 기준 커밋은 `git merge-base <들어갈 브랜치> HEAD`다. `git diff --name-only <기준>...HEAD`로 바뀐 경로를 본다. +2. `docs/work/experts.md` 「경로 → 전문가」로 경로마다 지식 스킬을 고른다. 이것이 렌즈 **후보**다. 변경 내용과 상관없는 후보는 뺀다(뺀 이유 한 줄). 3. 위험 신호가 있으면 그 렌즈를 더한다: 공개 계약(경로·필드·오류 코드·이벤트·env 키), 되돌릴 수 없는 것(마이그레이션·데이터 삭제), 인증·인가·비밀, 성능·접근성 예산, 빌드·CI 설정. -4. 렌즈는 리뷰어 하나에 1~3개. 같은 렌즈를 두 리뷰어에게 주지 않는다. 관점이 다르면(보안과 계약) 나눠 준다. +4. 리뷰어 하나에 렌즈 1~3개. 같은 코드를 같은 물음으로 보는 렌즈끼리 묶는다(영속성+성능 = 조회 비용, 계약+시험 = 호환을 증명하나). 반대 입장이 필요한 렌즈는 나눈다(보안과 계약). 같은 렌즈를 두 리뷰어에게 주지 않는다. +5. 시험 파일은 그 시험이 지키는 분야의 렌즈에 붙인다. 시험 렌즈(`*-testing`)는 시험 자체의 품질(거짓 통과, 흔들림)만 본다. +6. 리뷰어 종류: 분야 판정은 `reviewer`+렌즈, 계층 경계·「꼭 지킬 것」은 `arch-reviewer`, 앱을 띄워 봐야 아는 것은 `verify-*`, 정리 제안은 `code-simplifier`(고를 때만). 이름은 그 repo `docs/work/experts.md` 명단이 정한다. ## ③ brief — 리뷰어는 이 대화를 못 본다 ```text 목표: 한 문장. 무엇을 판정하나 렌즈: 읽을 지식 스킬 경로(.claude/skills/<이름>/SKILL.md) 1~3개 -큰 그림: 이 변경이 하려는 것 3줄, 관련 결정(내용으로, 번호만 쓰지 않는다) +큰 그림: 이 변경이 하려는 것 3줄, 관련 결정(그 repo 결정 기록과 experts.md 「정해 둔 것」에서, 내용으로) 범위: 기준 커밋과 diff 명령. 판정하지 않을 것(다른 리뷰어 몫) -제약: 파일을 고치지 않는다. 무거운 실행은 정해진 곳에서만(그 repo AGENTS.md 「검증」) +제약: 파일을 고치지 않는다. 읽기 명령(git·grep·문서 검사)은 써도 되고, 시험·빌드·앱 실행은 하지 않는다(그것은 리드나 verify-*) 출력: 아래 공통 양식, 60줄 이하 ``` @@ -44,7 +52,7 @@ description: Use when a change, review, or design spans more than one expert are ## ④ 병렬 실행 -- 서로 기다릴 것이 없는 리뷰어는 한 메시지에서 함께 띄운다. 오래 걸리는 실행 검증은 백그라운드로 띄우고 리드는 다른 일을 한다. +- 한 물결의 리뷰어는 한 메시지에서 함께 띄운다. 오래 걸리는 실행 검증은 백그라운드로 띄우고 리드는 다른 일을 한다. - 결과를 기다리며 같은 일을 리드가 따로 하지 않는다. ## ⑤ 합치기와 반증 @@ -53,16 +61,17 @@ description: Use when a change, review, or design spans more than one expert are ```text 판정: 통과 / 고칠 것 있음 / 판단 못 함 -발견: [심각도] 파일:줄 — 무엇이 문제인가 — 근거(규칙·문서·실행 결과) — 고치는 방향 +발견: [Critical|High|Medium|Low] 파일:줄 — 무엇이 문제인가 — 근거(규칙·문서·실행 결과) — 고치는 방향 넘길 것: → <렌즈 또는 사람>: 확인할 것 (왜 내 몫이 아닌가) 확인 못 한 것: 읽지 못한 것, 실행해야만 알 것 ``` +- 심각도: Critical(데이터 손실·보안 사고·운영 중단) · High(공개 계약 깨짐, 꼭 지킬 것 위반, 틀린 동작) · Medium(고쳐야 하지만 당장 깨지지 않음) · Low(작은 개선). 렌즈 밖에서 본 것은 판정하지 않고 「넘길 것」에 쓴다. - 같은 원인·같은 위치는 하나로 묶고 찾은 리뷰어를 모두 적는다. 같은 부류가 여러 곳이면 "부류"로 묶어 모든 곳을 고치게 한다. -- 스타일·취향 발견은 버린다(Low 3건까지만 남긴다). 근거 칸이 빈 발견, 추측은 「확인 못 한 것」으로 내린다. -- 심각도 High 이상(데이터 손실, 보안, 공개 계약 깨짐, 꼭 지킬 것 위반)은 반증을 시도해 살아남은 것만 남긴다. 리드가 코드에서 직접 보거나, 발견 하나를 general-purpose 서브에이전트에 "이 발견이 틀렸음을 `파일:줄`로 보여라. 못 보이면 참이다"로 맡긴다. 보고는 증거가 아니다. +- 스타일·취향 발견은 버린다(리뷰어 하나에 Low 3건까지). 근거 칸이 빈 발견, 추측은 「확인 못 한 것」으로 내린다. +- High 이상은 반증해서 살아남은 것만 남긴다. 리드가 코드에서 직접 보거나, 발견 하나를 general-purpose 서브에이전트에 "이 발견이 틀렸음을 `파일:줄`로 보여라. 못 보이면 참이다"로 맡긴다(물결과 따로 세고, 한 번에 둘까지). 보고는 증거가 아니다. -## ⑥ 넘김 — 한 번만 더 +## ⑥ 넘김 — 물결 한 번 더 - 「넘길 것」을 모아 두 번째 물결을 한 번 띄운다. 받는 쪽 brief에 넘긴 쪽의 발견 한 줄을 넣는다. - 세 번째 물결은 없다. 남은 넘김은 보고의 「남은 문제」다. 다른 repo로 넘길 것(예: 프론트가 본 API 계약 차이)은 총괄에게 넘긴다. @@ -70,34 +79,34 @@ description: Use when a change, review, or design spans more than one expert are ## ⑦ 충돌 판정 -의견이 부딪치면 이 순서로 정한다. 위가 이긴다. +먼저 사실인지 가린다. "받는 쪽이 있나", "실제로 깨지나" 같은 사실 다툼은 ⑤의 반증으로 먼저 푼다. 사실이 같은데 무엇이 중요한지가 갈릴 때만 이 순서로 정한다. 위가 이긴다. 1. 데이터 손실·보안 -2. 공개 계약 호환(이미 받는 쪽이 있는 경로·필드·이벤트·오류 코드) +2. 공개 계약 호환(이미 받는 쪽이 있거나 있을 수 있는 경로·필드·이벤트·오류 코드) 3. 그 repo의 「꼭 지킬 것」(아키텍처 불변식) 4. 검증할 수 있음(시험·게이트로 증명되는가) 5. 성능·접근성 예산 6. 디자인·UX 일관성 7. 단순함 -- 되돌릴 수 없거나 공개 계약을 바꾸는 선택, 같은 순위끼리의 충돌은 리드가 정하지 않는다. 근거와 권하는 안을 붙여 소유자에게 묻는다. +- 리드가 정하지 않고 소유자(그 repo에 목표를 준 결정권자)에게 묻는 것: 공개 계약을 바꾸는 선택, 되돌릴 수 없는 방식 고르기(예: 데이터를 지우는 마이그레이션과 남기는 마이그레이션 중), 같은 순위끼리의 충돌. 근거와 권하는 안을 붙인다. - 정한 것은 보고에 "무엇과 무엇이 부딪쳤고 몇 번으로 정했다"로 남긴다. 같은 충돌이 두 번 나오면 `docs/work/experts.md` 「정해 둔 것」에 한 줄 더한다. ## ⑧ 고치기 - 서브에이전트는 파일을 고치지 않는다. 고치는 것은 리드가 직접, 크거나 소유자가 열어 봐야 하면 하위 세션이다. +- 남의 브랜치는 리드가 고치지 않는다. 발견을 그 브랜치의 작성자(사람이나 그 하위 세션)에게 돌려준다. brief가 고치라고 했을 때만 고친다. - 고칠 때는 그 분야 지식 스킬을 부르고 「함정」과 「검증」을 따른다(리뷰어가 본 기준과 같은 기준). -## ⑨ 재확인 — 세 번까지 +## ⑨ 재확인 — 라운드 세 번까지 -- 고친 뒤 "내 발견이 풀렸나"는 그 리뷰어에게 `SendMessage`로 **고친 diff만** 주고 묻는다. -- 리뷰-수정은 세 번까지다. 세 번째에도 새 High가 나오면 멈추고 접근을 다시 정한다(설계 문제다). 고치는 쪽과 리뷰하는 쪽이 서로를 끝없이 부르지 않게 한다. -- 이미 낸 지적을 되풀이하지 않게 brief에 "지난 발견 목록"을 한 줄씩 넣는다. +- 두 번째 라운드부터는 고친 diff와 지난 발견 목록(한 줄씩)만 준다. "내 발견이 풀렸나"는 그 발견을 낸 리뷰어에게 `SendMessage`로 묻는다. "새 결함이 있나"는 새 인스턴스에 맡긴다(이어 물으면 전에 본 것에 끌려간다). - 게이트는 그 repo의 검증 진입점으로 돌린다. 리뷰어의 "통과"는 게이트를 대신하지 않는다. +- 멈춤: High 이상이 없고 게이트가 통과하면 끝. Medium·Low는 이번에 고치거나 보고의 「남은 문제」로 넘긴다. 세 번째 라운드가 끝났는데 High가 남거나 새로 나오면 더 돌지 않고 멈춘다. 접근 자체가 문제라는 신호이니 소유자에게 다시 정할 것을 묻는다. ## 보고 -끝 보고에 칸 하나를 더한다: 쓴 렌즈와 리뷰어 수, 물결·라운드 수, 발견 수(묶은 뒤), 반증으로 버린 수와 이유, 충돌 판정. 평가 중이면 `harness-eval` 스킬대로 장부에 실행 한 줄을 남긴다. +끝 보고에 칸 하나를 더한다: 쓴 렌즈와 리뷰어 수, 물결·라운드 수, 발견 수(묶은 뒤), 반증으로 버린 수와 이유, 충돌 판정. 하네스 판을 비교하는 평가 중이면(`harness-eval` 스킬) 장부에 실행 한 줄을 남긴다. ## 하지 않는 것 diff --git a/template/docs/work/experts.md b/template/docs/work/experts.md index 9b17647..ce22a7c 100644 --- a/template/docs/work/experts.md +++ b/template/docs/work/experts.md @@ -1,20 +1,27 @@ # 전문가 — 누가 무엇을 보고 어떻게 주고받나 -이 repo의 분야 전문가 명단과 협업 규칙이다. 절차(렌즈 고르기 → brief → 병렬 → 합치기·반증 → 넘김 → 충돌 판정 → 재확인 세 번까지)는 하네스 플러그인의 `lead` 스킬이고, 왜 이 모양인지는 claude-harness `docs/experts.md`다. 이 문서는 이 repo에서 다른 것만 적는다. 전문가를 더할 때는 `new-expert` 스킬. +이 repo의 분야 전문가 명단과 협업 규칙이다. 절차(쓸지 → 렌즈 고르기 → brief → 병렬 → 합치기·반증 → 넘김 → 충돌 판정 → 고치기 → 재확인 세 라운드까지)는 하네스 플러그인의 `lead` 스킬이고, 왜 이 모양인지는 claude-harness `docs/experts.md`다. 이 문서는 이 repo에서 다른 것만 적는다. 전문가를 더할 때는 `new-expert` 스킬. ```text 고치는 메인 세션 ──그 분야 파일을 만짐──> 지식 스킬이 목록에 뜸 ──부름──> 함정·점검표·검증대로 직접 고친다 리드(메인 세션) ──brief + 렌즈(지식 스킬 경로)──> reviewer(새 눈, 판정만) ──발견·넘길 것──> 리드 ──> 고치기 ``` -분야 전문가는 **지식 스킬**이다. 서브에이전트는 분야가 아니라 일(새 눈 리뷰, 실행 검증)마다 둔다. +**이 문서에서 쓰는 말** + +- **분야 전문가 = 지식 스킬**: 한 분야의 함정·점검표·검증 명령. `paths`를 걸어 그 파일을 만질 때만 목록에 뜬다. +- **렌즈**: 리뷰어에게 "이 지식 스킬로 보라"고 주는 스킬 경로 1~3개. +- **리드**: 렌즈를 고르고 리뷰어를 띄우고 합치는 메인 세션. 하위 세션을 나눠 맡기는 총괄이면 총괄. +- **물결**: 리뷰어를 한꺼번에 띄우는 차례(한 라운드에 두 번까지). **라운드**: 리뷰 → 고치기 → 재확인 한 바퀴(세 번까지). +- **서브에이전트**: 한 세션 안에서 띄우는 별도 창. 결과만 돌려준다. **하위 세션**: 사람이 열어 보고 멈출 수 있는 별도 세션. 파일을 바꾸는 큰 위임은 하위 세션이다. +- **게이트**: 이 repo 검증 진입점(`scripts/verify.sh` 등)이 돌리는 검사. 리뷰어의 "통과"는 게이트를 대신하지 않는다. ## 1. 큰 그림을 읽는 순서 메인 세션과 리뷰어가 같은 순서로 읽는다. 1. 루트 `AGENTS.md`(무엇인가 · 꼭 지킬 것 · 지도) -2. 이 문서의 자기 칸 +2. 이 문서의 명단에서 맡은 렌즈의 줄 3. 렌즈인 지식 스킬(「함정」부터) 4. 작업 파일과 가장 가까운 폴더의 `AGENTS.md` 5. 스킬이 가리키는 정본 문서(필요한 절만) @@ -25,11 +32,12 @@ |---|---|---|---|---| | 리드 | 메인 세션 + `lead` 스킬 | 플러그인 | 둘 이상 분야, PR 전, 의견 충돌 | 고른 렌즈, 합친 발견, 충돌 판정 | | (채울 것: 분야) | 지식 스킬 | `.claude/skills/<접두>-<분야>/` | (발동 조건, `paths`) | 함정·점검표·검증 | -| (채울 것: 일) | 서브에이전트 | `.claude/agents/<이름>.md` | (새 눈 리뷰·실행 검증) | lead 공통 양식 | +| reviewer | 서브에이전트 | `.claude/agents/reviewer.md` | 분야 판정(렌즈를 받아) | lead 공통 양식 | +| (채울 것: 일) | 서브에이전트 | `.claude/agents/<이름>.md` | (계층 경계 리뷰, 실행 검증 등) | lead 공통 양식 | ## 3. 경로 → 전문가(렌즈) -리드가 바뀐 경로로 렌즈를 고르는 표다. 지식 스킬의 `paths`와 맞춘다. +리드가 바뀐 경로로 렌즈 후보를 고르는 표다. 지식 스킬의 `paths`와 맞춘다. 후보 중 변경 내용과 상관없는 것은 리드가 뺀다. | 경로(glob) | 렌즈(지식 스킬) | 이럴 때 더한다 | |---|---|---| @@ -45,7 +53,7 @@ ## 5. 충돌 — 이 repo에서 정해 둔 것 -순위는 `lead` 스킬 ⑦이다(데이터 손실·보안 → 공개 계약 → 꼭 지킬 것 → 검증 가능 → 성능·접근성 예산 → 디자인 일관성 → 단순함). 같은 충돌이 두 번 나오면 여기에 한 줄 더한다. +사실 다툼(받는 쪽이 있나, 실제로 깨지나)은 반증으로 먼저 가린다. 가치가 부딪칠 때의 순위는 `lead` 스킬 ⑦이다(데이터 손실·보안 → 공개 계약 → 꼭 지킬 것 → 검증 가능 → 성능·접근성 예산 → 디자인·UX 일관성 → 단순함). 공개 계약을 바꾸는 선택, 되돌릴 수 없는 방식 고르기, 같은 순위끼리의 충돌은 소유자가 정한다. 같은 충돌이 두 번 나오면 여기에 한 줄 더한다. | 날짜 | 부딪친 것 | 정한 것 | 근거 | |---|---|---|---|