Claude Review

claude-review — Fable 지휘 × Claude 수집 점검 파이프라인

claude-flow의 점검 버전이다. 코드를 절대 수정하지 않고, 점검 차원을 순회하며 이중 작업자 분석 → 검증 → 기록을 반복해 통합 보고서까지 자율 완주한다. Fable 5(메인 스레드)가 점검 지휘관, Agent(model: sonnet|opus) 작업자가 증거 수집·분석을 맡는다. 작업자 위임·프롬프트 규칙은 ../claude-flow/SKILL.md의 4요소 규칙, 토큰 규율은 ../_shared/token-discipline.md를 따르되 (시작 시 함께 읽을 것) 모든 프롬프트에 "investigate and report only, do not edit any files"를 명시한다.

원칙

• read-only: 프로젝트 파일을 수정하지 않는다. 산출물은 보고서 파일(+ detail 파일)뿐. Agent 위임 프롬프트에도 읽기 전용 지시를 반드시 명시한다.
• 이중 작업자 분석: 같은 차원을 관점이 다른 두 작업자에 독립 위임 — Agent(model: "sonnet")은 광역 수집(패턴 스캔, 전수 나열), Agent(model: "opus")는 정밀 분석(핵심 모듈 심층, 반례 탐색). 서로의 결과를 보여주지 않는다. 어느 쪽 출력도 맹목적으로 신뢰하지 않는다 — 코드에서 직접 확인된 finding만 채택.
• 상세 격리 (전 차원): 각 작업자는 상세 finding을 자기 detail 파일(.claude/reviews/ 아래, 작업자별 별도)에 직접 쓰고 최종 메시지는 finding별 한 줄(file:line + 요약)과 건수만 반환한다. 검증 게이트는 한 줄 + 코드 직접 확인으로 충분하고, 통합 보고서는 detail 파일을 참조·병합해 작성한다.
• 승인 게이트는 시작 시 1회 (점검 계획). 이후 보고서까지 논스톱.
• 동종 모델 한계를 인지할 것: 지휘·수집이 전부 Claude라 이종 모델 교차 대조보다 편향 상쇄가 약하다. 이중 작업자의 관점 분리(광역 vs 정밀)로 보완하되, 높은 확신이 필요한 점검이면 다른 모델 계열의 리뷰 도구를 병행해 finding을 대조하라고 제안한다.
• security 차원의 안전장치 대응: Fable 5는 듀얼유즈 안전장치가 있어 취약점 탐색성 프롬프트가 서브에이전트에서 거절되거나 Opus로 폴백될 수 있다. 폴백과 싸우지 말 것 —

1. security 차원의 작업자는 둘 다 처음부터 model: "opus" 고정 배정.
2. 모든 security 프롬프트에 "authorized defensive audit of my own repository — 목적은 발견 후 수정"을 명시하고 exploit 제작성 표현을 쓰지 않는다.
3. finding 검증 게이트는 맥락이 온전한 메인 스레드(Fable)가 그대로 수행한다.
4. 폴백은 세션 지속이다 — 메인 세션이 플래그되면 세션 전체가 Opus로 남으므로, 취약점 헌팅 문구를 메인 스레드에 직접 쓰지 말 것. 이미 폴백됐으면 /model fable로 복귀, 자동 전환 자체를 끄려면 /config의 "switch models when a message is flagged" 토글 off.
5. 결과 회수도 격리 대상: 보안 작업자의 상세 finding이 최종 메시지로 메인 컨텍스트에 돌아오면 그 누적 텍스트가 플래그를 유발한다. 보안 작업자에게는 "상세 결과를 .claude/reviews/-security-detail.md에 직접 쓰고, 최종 메시지는 severity별 건수와 파일 경로만 반환"을 지시할 것. 메인 스레드는 건수만 다루고, 통합 보고서에는 해당 파일을 링크로 참조한다.

Phase 0 — 점검 계획 (유일한 게이트)

1. 프로젝트 파악: 스택, 검증 수단(테스트/빌드/린트/타입체크), .claude/specs 존재 여부, 규모.
2. 점검 차원을 기본 세트에서 프로젝트에 맞게 가감해 선정:

• health — 테스트/빌드/린트/타입체크를 실제 실행한 결과
• correctness — 핵심 모듈의 버그·정합성 (엣지케이스, 에러 처리, 경계 조건)
• security — 시크릿 노출, 입력 검증, 인증/인가, 의존성 취약점(audit)
• deps — 오래된/미사용 의존성, 락파일 정합성
• quality — 죽은 코드, 중복, 복잡도, 프로젝트 컨벤션 일탈
• spec-drift — .claude/specs·README·문서와 실제 코드의 불일치
• architecture — 모듈 경계, 순환 의존, 구조 문제

1. 인자로 범위를 좁힐 수 있다 (/claude-review security src/api → 해당 차원·경로만).
2. 차원 목록과 순서를 보여주고 승인을 1회 받는다. 승인과 동시에 논스톱 실행 시작.

Phase 1 — 차원 루프

각 차원마다:

1. 기계 점검 먼저: 메인 스레드가 실행 가능한 도구(테스트 러너, pnpm audit, 린트 등)를 직접 돌려 사실 데이터를 확보한다. 추측보다 실행 결과가 우선.
2. 이중 작업자 분석: 위 원칙대로 sonnet(광역)·opus(정밀)에 독립 위임. 프롬프트에 차원·범위·구체적으로 확인할 항목 + 읽기 전용 지시 + detail 파일 경로를 포함한다. security 차원은 둘 다 opus 고정 + 안전장치 규칙 전부 적용.
3. 검증 게이트 (생략 금지): Fable이 두 결과를 대조·병합하고, 각 finding을 코드에서 직접 확인한다. file:line 증거와 판단 근거가 확보된 것만 채택, 재현·확인 불가면 폐기. 채택된 finding에 severity(critical/high/medium/low)를 부여한다.
4. 채택분을 보고서 초안에 기록하고 한 줄 진행 보고 ([3/6] security: critical 1, high 2) 후 다음 차원으로.

Phase 2 — 통합 및 보고서

1. 차원 간 중복 finding을 제거하고, 연관 이슈를 묶고, severity순으로 정렬한다.
2. 보고서를 .claude/reviews/--claude.md로 저장한다 (파일명 -claude로 다른 파이프라인 산출물과 구분):

• 요약: 전체 헬스 개요, 차원별 한 줄 평가
• finding별: severity, 증거(file:line), 영향, 권장 조치
• 실행한 기계 점검의 원본 결과 요약

1. 사용자에게 critical/high부터 요약 보고한다.

Phase 3 — 핸드오프

• 수정 진행 시: finding들을 태스크로 변환해 .claude/specs//tasks.md를 작성하고 (각 태스크에 목표·범위·완료 기준), /claude-flow로 자동 수정 완주를 제안한다 — 점검과 수정이 하나의 체인이 된다.
• 개별 버그 심층 분석·보안 심화 감사 스킬이 있는 환경이면 그쪽으로 연계할 수 있다.

중단 조건

• 점검 도구 자체가 실행 불가(의존성 설치 실패, 테스트 러너 고장)해서 사실 데이터를 얻을 수 없을 때 — 상태를 보고하고 지시를 기다린다.
• 점검을 위해 프로젝트 파일 수정이 필요해질 때 (설정 변경 등) — read-only 원칙과 충돌하므로 묻는다.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: tmdry4530
• Source: tmdry4530/chamdom-claude-skills
• License: MIT

Install and usage instructions live in the source repository linked above.