📋 Consensus Review 결과

문서: SKILL.md (consensus-review 스킬 정의)
경로: ./SKILL.md
리뷰어: 3명 독립 (Consensus Review 스킬)
생성일: 2026-05-12 11:57:36

총 24개 🔴 High 7 🟡 Mid 11 ⚪ Low 6

리뷰어별 발견 수 자세히 보기

리뷰어별 결함 발견 수
리뷰어	발견 결함 수
Reviewer 1	30건
Reviewer 2	36건
Reviewer 3	30건
병합 후 통합	24건

💡 먼저 처리할 일 (Top Actions)

도구명 표기 통일 — write_file/Write/write, read_file/Read 혼용을 Claude Code 실제 도구명(Write/Read)으로 통일 (🔴 ISS-1).
doc_type_hint 키워드/값 매핑 정의 — Step 1 영문 키워드(prd/spec/requirements/nda/rfc/architecture)와 Step 2-3 허용 값(사업계획서/기능정의서/구현계획서/architecture/general)의 매핑 테이블 추가 (🔴 ISS-2).
Tier 분류 규칙을 SKILL.md에 명시 — 🔴/🟡/⚪ 결정 임계치(N/N, ceil(N/2)/N, 그 외)를 본문에 직접 정의하여 aggregate.md 외부 의존 제거 (🔴 ISS-3).
측정 기준 3종 정의 — 토큰 카운트(어떤 tokenizer), 인라인 임계치(500단어 OR/AND 2KB), 한글 50% 분모(전체/공백제외/자모) (🔴 ISS-4, ISS-5, ISS-6).
외부 파일 의존성 명시 — review.md, aggregate.md, output_template.md/html의 위치/필수 여부/누락 시 동작을 본문에 추가 (🔴 ISS-7).

상세 가이드는 페이지 하단 권장 조치 섹션을 참고하세요.

🔴 High Confidence

— 전원 합의 (7개)

3명 전원이 지적한 이슈입니다. 우선 처리 대상.

ISS-1 🔴 도구명 표기 불일치 (write_file/Write/write, read_file/Read)

Terminology MAJOR Agents 3/3 Confidence 9/10 (R1: 8, R2: 9, R3: 10) Evidence 5/5

📍 "서브에이전트는 리뷰 결과를 **파일로 저장** (`write_file` 또는 `Write`)" (Step 2-2)R1
📍 "이 단계에서 `write` 툴을 호출합니다." (Step 4a)R1
📍 "Main은 **파일을 직접 `read_file`** — 문자 그대로 읽음, 요약 개입 없음" (Step 2-2)R2
📍 "서브에이전트가 `read_file` (또는 `Read`) 도구로 직접 파일을 읽습니다." (Step 2-6)R2
📍 "결과 전체를 `{output_path}`에 `write_file`로 저장." (Step 2-4)R3

동일 도구를 write_file/Write/write·read_file/Read로 혼용. Claude Code 실제 도구명은 Write/Read이므로 표기를 통일해야 한다. 3명 전원 지적 — 동일 root cause.

ISS-2 🔴 doc_type_hint 옵션 목록 불일치 — Step 1 vs Step 2-3

Inconsistency MAJOR Agents 3/3 Confidence 9/10 (R1: 9, R2: 8, R3: 8) Evidence 5/5

📍 "`{doc_type_hint}`: 파일명에 `prd|spec|requirements|nda|rfc|architecture` 매치 또는 본문 첫 200자에서 직접 매치되는 키워드 → 해당 유형. 매치 없으면 \"general\"." (Step 1)R1·R2·R3
📍 "`{doc_type_hint}` ← \"사업계획서\", \"기능정의서\", \"구현계획서\", \"architecture\", \"general\" 중 하나" (Step 2-3)R1·R2·R3
📍 "**예시**: `requirements.md` → \"requirements\"; 본문에 \"1조(목적)\", \"비밀유지\" → \"NDA\"." (Step 1)R3

Step 1은 영문 키워드 6개로 매칭하고, Step 2-3은 한국어 3개+architecture+general을 허용 값으로 제시. 두 목록의 매핑 규칙(prd→무엇?)이 누락되어 어떤 값이 전달되는지 결정 불가.

ISS-3 🔴 Tier 결정 규칙 SKILL.md에 부재 — aggregate.md에 외부화

Omission CRITICAL Agents 3/3 Confidence 9/10 (R1: 7, R2: 9, R3: 8) Evidence 5/5

📍 "N명의 독립 서브에이전트 리뷰어를 병렬 실행해 문서 결함을 탐지하고 🔴/🟡/⚪ Tier로 분류합니다." (개요)R2·R3
📍 "집계 결과는 🔴/🟡/⚪ Tier가 붙은 ISS-1, ISS-2 … 형태의 통합 목록입니다." (Step 3-3)R2·R3
📍 "🔴 high / 🟡 medium / ⚪ low" (frontmatter description)R3
📍 "위반 시 이 스킬의 핵심 효과(확률적 커버리지로 +6.5~30.6%p 재현율 향상)가 사라집니다." (Step 2)R1

스킬의 핵심 결과물인 Tier 분류(N/N=🔴, ≥ceil(N/2)=🟡)가 SKILL.md에 정의되지 않고 aggregate.md에 외부화. SKILL.md만으로는 동작 예측이 불가능하고 N=2/N=5 변경 시 임계치 도출 불명확.

ISS-4 🔴 60K 토큰 한계와 200K context 요구치 정합성 결여 + 측정 방법 누락

Inconsistency MAJOR Agents 3/3 Confidence 8/10 (R1: 8, R2: 8/9, R3: 6) Evidence 5/5

📍 "최소 요구치: context window ≥ 200K. 그 미만 모델이 감지되면 사용자에게 알리고 중단." (Step 2-7)R1·R2·R3
📍 "**문서 > 60K 토큰**: 청크 분할은 아직 미구현. 사용자에게 알리고 중단" (Step 2-8)R1·R2·R3
📍 "문서가 60K 토큰을 초과합니다(X 토큰). 현재 버전은 청크 분할을 지원하지 않습니다." (Step 2-8)R1·R2

200K context 요구하면서 60K로 차단하는 근거 미설명. 또한 토큰 측정 방법(어떤 tokenizer, 모델별 차이)이 정의되지 않아 사용자가 "X 토큰"을 알 수 없음. R1·R2·R3 동일 root cause(임계치 정합성+측정 미정의).

ISS-5 🔴 인라인 텍스트 임계값 측정 기준(500단어/2KB) 미정의

Ambiguity MAJOR Agents 3/3 Confidence 8/10 (R1: 7, R2: 9, R3: 7) Evidence 5/5

📍 "인라인 텍스트면 500 단어 / 2KB 미만일 때만 그대로, 초과 시" (Step 1)R1·R2·R3
📍 "**AND** 문서가 500 단어 / 2KB **미만**일 때." (Step 2-6)R1·R2
📍 "NOT for: simple typo/grammar fixes, translation proofreading, documents under 500 words" (frontmatter description)R3

"500 단어 / 2KB"가 OR/AND인지 명시되지 않고 한글 단어 카운트 기준(공백 분리/토큰)도 미정의. description은 500 단어 미만은 적용 대상 아니라고 하면서 Step 1은 그 미만 인라인을 그대로 처리하는 분기 제공해 충돌.

ISS-6 🔴 외부 파일 의존성 명시 부재 (aggregate.md, output_template.md/html, review.md)

Omission MAJOR Agents 3/3 Confidence 8/10 (R1: 7, R2: 8, R3: 8) Evidence 5/5

📍 "`examples/output_template.md`의 형식으로 최종 Markdown 리포트를 생성합니다." (Step 4)R1·R3
📍 "`prompts/aggregate.md` 프롬프트에 다음 변수 치환" (Step 3-3)R1·R2·R3
📍 "`examples/output_template.html`을 베이스로 .html 파일을 생성하세요." (Step 4)R3
📍 "자세한 분기 규칙은 `examples/output_template.md`의 **C 섹션**을 참고." (Step 4)R2·R3
📍 "#### 2-4. 서브에이전트가 반드시 따라야 할 것 (review.md에도 명시)" (Step 2-4 헤더)R2·R3

SKILL.md가 다수 외부 파일에 의존하지만 위치 규약/존재 보장/누락 시 동작이 명시되지 않음. 외부 파일 변경/누락 시 스킬이 깨지며 무결성 검증 불가.

ISS-7 🔴 "+6.5~30.6%p 재현율 향상" 벤치마크 출처/조건 누락

Omission MINOR Agents 3/3 Confidence 7/10 (R1: 7, R2: 8, R3: 6) Evidence 4/5

📍 "위반 시 이 스킬의 핵심 효과(확률적 커버리지로 +6.5~30.6%p 재현율 향상)가 사라집니다." (Step 2)R1·R2·R3
📍 "벤치마크(6 LLM × 3 benchmark) 기준 temperature=0.7~1.0 구간에서 재현율이 단조 증가." (Step 2-7)R1·R2·R3

+6.5~30.6%p와 6 LLM × 3 benchmark의 측정 조건(N, 모델, 데이터셋, 비교 기준)이 본문에 정의되지 않아 사용자가 결과를 검증/조정 불가. 두 곳에서 인용되지만 출처 링크 없음.

🟡 Needs Review

— 다수 합의 (11개)

2/3이 지적한 이슈. 검토 권장.

ISS-8 🟡 SESSION_ID 4자 난수의 문자 집합 정의 누락

Ambiguity MINOR Agents 2/3 Confidence 8/10 (R1: 7, R3: 9) Evidence 4/5

📍 "`SESSION_ID` 생성: `{YYYYMMDD-HHMMSS}-{4자 난수}` 형태. 예: `20260428-022810-a3f7`" (Step 2-1)R1·R3
📍 "예: `{PROJECT_DIR}/.consensus-review-output/20260428-022810-a3f7/reviewer-1.md`" (Step 2-3)R1·R3

4자 난수의 문자 집합(16진수만 vs 영숫자, 대소문자 허용 여부)이 정의되지 않아 구현체가 다른 형식 생성 가능. 충돌 확률 보장도 불명확.

ISS-9 🟡 temperature 0.3 미만 금지 — 측정 범위 외 + 구현 주체 불명확

Ambiguity MINOR Agents 3/3 Confidence 7/10 (R1: 7, R2: 7, R3: 7) Evidence 3/5

📍 "벤치마크(6 LLM × 3 benchmark) 기준 temperature=0.7~1.0 구간에서 재현율이 단조 증가." (Step 2-7)R1·R2·R3
📍 "**0.3 미만으로 낮추지 마세요** — 독립성이 깨집니다." (Step 2-7)R1·R2·R3
📍 "temperature는 서브에이전트 기본값 사용." (Step 2-7)R3

벤치마크는 0.7~1.0만 측정한 채 0.3 미만 금지. 0.3~0.7 구간 권장값/허용 미정의. 또한 서브에이전트 기본값 사용한다면서 "낮추지 마세요"의 명령 대상(메인/사용자/서브에이전트)이 모호.

ISS-10 🟡 HTML 모드 트리거 기준 모호 + 채팅 요약 경로 표기 부정확

Ambiguity MINOR Agents 3/3 Confidence 7/10 (R1: 7, R2: 8, R3: 7) Evidence 4/5

📍 "사용자가 명시적으로 HTML 출력을 요청하면(\"HTML로\", \"인터랙티브로\", \"단일 HTML 파일\")" (Step 4)R1·R2
📍 "사용자가 \"둘 다\"라고 하면 같은 타임스탬프로 .md + .html 두 개 생성." (Step 4a)R1·R2
📍 "📄 저장 경로: ./consensus-review-{원본}-{YYYYMMDD-HHMMSS}.md" (Step 4b)R3

"HTML로"/"인터랙티브로"/"단일 HTML 파일" 외 변형 표현이 트리거에 해당하는지 모호. 영어 트리거 미정의. HTML 모드 활성화 시 4b 채팅 요약의 ".md" 표기가 부정확함.

ISS-11 🟡 서브에이전트 1명 실패 시 N=2 진행 — 비권장 정책과 자동 fallback 충돌

Inconsistency MAJOR Agents 2/3 Confidence 7/10 (R1: 7, R2: 7) Evidence 4/5

📍 "**서브에이전트 1명 `write_file` 실패 또는 타임아웃**: 남은 2명으로 진행. 최종 리포트 상단에 `\"Reviewer X 실패 — N=2로 집계됨\"`을 명시." (Step 2-8)R1·R2
📍 "\"2명만\" → N=2 (비권장)." (설정 변경)R1
📍 "독립성이 이 스킬의 존재 이유입니다. 위반 시 이 스킬의 핵심 효과(확률적 커버리지로 +6.5~30.6%p 재현율 향상)가 사라집니다." (Step 2)R2

사용자 요청 N=2는 비권장이지만 1명 실패 시 자동 N=2 fallback은 허용. 동일 N=2 상태에 대해 다른 정책 적용. N=2의 재현율 효과 예상치 미정의.

ISS-12 🟡 200K context 미만 모델 감지 메커니즘 부재

Omission MAJOR Agents 2/3 Confidence 7/10 (R1: 7, R2: 8) Evidence 3/5

📍 "최소 요구치: context window ≥ 200K. 그 미만 모델이 감지되면 사용자에게 알리고 중단." (Step 2-7)R1·R2

"감지되면"의 구체적 메커니즘(API 메타데이터 조회/모델명 매칭/사용자 설정) 미정의. 사용자가 모델 명시 안 한 경우 처리 절차 누락.

ISS-13 🟡 PROJECT_DIR 결정 모호성 — cwd 정의/상대경로/dirname 기준

Ambiguity MAJOR Agents 3/3 Confidence 7/10 (R1: 5/6, R2: 8, R3: 8) Evidence 4/5

📍 "입력이 **파일 경로**면 → `PROJECT_DIR = dirname(document_path)` (해당 파일이 있는 디렉토리)" (Step 1)R1·R2·R3
📍 "입력이 **인라인 텍스트**면 → `PROJECT_DIR = cwd` (현재 작업 디렉토리)" (Step 1)R1·R3
📍 "📄 저장 경로: ./consensus-review-{원본}-{YYYYMMDD-HHMMSS}.md" (Step 4b)R3

cwd 주체(메인/사용자 셸/서브에이전트), 상대경로/~ 처리, 절대경로 정규화가 미정의. 동일 사용자가 같은 문서를 파일경로/인라인으로 입력 시 PROJECT_DIR이 달라져 의도와 다른 위치 저장 위험.

ISS-14 🟡 aggregate.md {document} 변수 — "경로 또는 전문" 결정 규칙 누락

Inconsistency MAJOR Agents 2/3 Confidence 8/10 (R1: 7, R2: 8) Evidence 4/5

📍 "`{document_path}` ← 원본 문서의 파일 경로 (기본)." (Step 2-3)R1
📍 "`{document}` ← 원본 문서 경로 또는 전문" (Step 3-3)R1·R2
📍 "**기본 규칙: 항상 파일 경로만 전달하세요.**" (Step 2-6)R2

서브에이전트는 경로만 강제하면서 aggregate는 "경로 또는 전문" 둘 다 허용. 결정 규칙이 없어 큰 문서 시 토큰 한도 사고 위험 재발 가능.

ISS-15 🟡 N 동적 처리 vs 본문 N=3 하드코딩 불일치

Inconsistency MAJOR Agents 3/3 Confidence 8/10 (R1: 8, R2: 9, R3: 6) Evidence 5/5

📍 "Review Korean/English documents for defects by running N=3 independent LLM reviewers as parallel subagents" (frontmatter description)R2·R3
📍 "서브에이전트 3명을 **동시에** 호출 (병렬)." (Step 2-3)R1
📍 "각 서브에이전트의 output 경로: `{PROJECT_DIR}/.consensus-review-output/{SESSION_ID}/reviewer-{N}.md` (N=1,2,3)" (Step 2-1)R1
📍 "**N 변경**: \"리뷰어 5명으로 해줘\" → N=5. \"2명만\" → N=2 (비권장). 기본은 3." (설정 변경)R1·R2·R3

description과 본문은 N=3 하드코딩, 설정 변경은 N 변경 가능. N=5 시 reviewer-1~5 사용/디렉토리 명명 절차가 본문에 명시되지 않아 트리거/동작 정의 일관성 결여.

ISS-16 🟡 최종 리포트 파일명 충돌 — SESSION_ID 난수 vs timestamp만

Inconsistency MINOR Agents 3/3 Confidence 6/10 (R1: 7, R2: 7, R3: 5) Evidence 3/5

📍 "`{YYYYMMDD-HHMMSS}`: 실행 시점 기준 초 단위 타임스탬프 (같은 초에 겹칠 확률 ≈ 0)" (Step 4a)R1·R2·R3
📍 "**같은 문서를 여러 번 리뷰해도 타임스탬프가 달라 덮어쓰지 않습니다.**" (Step 4a)R1·R3
📍 "`SESSION_ID` 생성: `{YYYYMMDD-HHMMSS}-{4자 난수}` 형태." (Step 2-1)R1·R2·R3

SESSION_ID는 4자 난수로 충돌 방지하면서 최종 리포트는 timestamp만 사용. 자동화/배치 동시 실행 시 충돌 가능. 일관성 결여.

ISS-17 🟡 "raw 복사 금지"와 "raw_1, raw_2, raw_3" 변수의 의미 충돌

Ambiguity MINOR Agents 3/3 Confidence 6/10 (R1: 6, R2: 7, R3: 6) Evidence 3/5

📍 "서브에이전트 return 메시지는 **한 단어**: `\"done\"` (raw 복사 금지)" (Step 2-2)R1·R2·R3
📍 "**서브에이전트가 \"done\" 대신 raw 내용을 return한 경우**: 해당 내용 무시하고 파일을 `read_file`로 직접 읽으세요." (Step 2-8)R1·R3
📍 "=== Reviewer 1 ===\n{raw_1}" (Step 3-2)R2·R3

"raw 복사", "raw 내용", "raw 리뷰", "raw_1/2/3"의 의미 분화 미정의. 서브에이전트 강제 메커니즘이 없으면서 위반 시 처리 분기가 정의되어 자기모순 구조.

ISS-18 🟡 write 툴 검증 실패 시 분기 매핑 부정확 (4a vs 2-8)

Inconsistency MINOR Agents 2/3 Confidence 7/10 (R2: 7, R3: 7) Evidence 4/5

📍 "**저장 후 검증**: `write` 툴 반환값을 확인한 뒤 Step 4b 요약을 출력하세요. 실패하면 차단 상황 분기의 `.consensus-review-output/ 저장 실패` 항목을 따르세요" (Step 4a)R2·R3
📍 "**`.consensus-review-output/` 저장 실패** (디스크 풀/권한/읽기전용 디렉토리): 사용자에게 원인과 함께 보고하고 중단." (Step 2-8)R2·R3

4a 최종 리포트 저장 위치는 원본 문서 디렉토리, 2-8 분기는 .consensus-review-output/ 디렉토리. 서로 다른 위치인데 같은 분기 적용 지시. 검증 기준(파일 경로/바이트/에러 코드)도 미정의.

⚪ Low

— 소수 지적 (6개)

1명만 지적. 환각 가능성이 상대적으로 큼.

ISS-19인라인 텍스트 저장과 SESSION_ID 디렉토리 미생성 시점 충돌 — Step 1에서 input-*.md를 .consensus-review-output/에 저장하지만 이 디렉토리는 Step 2-1에서 생성됨. 절차 순서 명시 누락 (R1).
ISS-20한글 50% 판정 분모 정의 누락 — 전체 문자수/공백 제외/자모 비율 중 어느 기준인지 미정의. 영문 코드 섞인 한글 문서에서 잘못 분류 가능 (R2).
ISS-21중간 산출물 자동 정리 정책 부재 — 자동 정리 안 함 정책으로 디스크 무한 증가 위험. 사용량 모니터링/한계 정책 미정의 (R2).
ISS-22인라인 텍스트 자동 저장 시 사용자 컨센트 미정의 — 잠재 민감 정보를 디렉토리에 자동 저장 시 사용자 동의/사후 안내가 미정의. 보안/프라이버시 누락 (R3).
ISS-23description 트리거 파일명 vs Step 1 키워드 불일치 — description은 design 포함/nda·rfc 누락, Step 1은 nda·rfc 있고 design 없음. 두 목록 불일치 (R3).
ISS-24슬래시 명령 트리거 미정의 + 영어 트리거 누락 — description은 자연어 트리거만, /consensus-review 슬래시 지원 여부 불명확. 영어 명시 트리거(as html, interactive) 미정의 (R1·R2).

💡 권장 조치

🔴부터 우선 검토 — 3명 전원 합의라 진짜 결함일 확률이 높습니다. 특히 도구명 통일(ISS-1)과 doc_type_hint 매핑(ISS-2), Tier 분류 규칙 명시(ISS-3)는 스킬이 일관되게 동작하기 위한 필수 수정입니다.
측정 기준 3종(토큰/단어/한글%, ISS-4·5·6)을 본문에 정의하세요. "X 토큰", "500 단어/2KB", "≥50%"가 모두 측정 방법이 미정의되어 실행자마다 결과가 달라질 수 있습니다.
외부 파일 의존성 명시(ISS-6) — SKILL 패키지 디렉토리 구조와 필수 파일 목록(prompts/review.md, prompts/aggregate.md, examples/output_template.md/html)을 본문에 추가하면 무결성 검증이 가능해집니다.
🟡까지 시간 여유가 있으면 — 다수 합의라 정밀도 중간 이상입니다. 특히 ISS-11(N=2 자동 fallback)과 ISS-15(N 동적 처리)는 N 변경 시 동작 일관성에 직접 영향을 줍니다.
⚪는 리소스 여유 시에만 — 환각 가능성이 상대적으로 큽니다. 다만 ISS-22(컨센트)는 보안 관점에서 검토 가치가 있습니다.