adamsreview

Claude Code를 위한 다단계 코드 리뷰(Multi-stage code review) — 병렬 서브 에이전트(sub-agent) 탐지, 검증 단계(validation passes), 지속적인 JSON 상태 관리, 그리고 커밋 전 회귀(regressions)를 재검토하고 되돌리는 자동 수정 루프(automated fix loop)를 제공합니다.

제 개인적인 PR(Pull Request) 작업 시, Claude Code의 내장 기능인 /review, /ultrareview 및 CodeRabbit, Greptile, Codex의 내장 리뷰보다 훨씬 더 많은 실제 버그를 잡아내면서도 오탐(false positives)은 더 적게 발생했습니다. (개인적인 경험에 근거함, n=me.) 내장된 /review를 모델로 하여 6가지 명령어로 구성된 파이프라인으로 확장되었습니다. /ultrareview가 Extra Usage 풀에서 비용을 차감하는 것과 달리, 이 도구는 일반적인 Claude Code 구독(Max 플랜 권장)을 사용하여 실행됩니다.

/plugin marketplace add adamjgmiller/adamsreview
/plugin install adamsreview@adamsreview

6가지 명령어:

• /adamsreview:review — 브랜치(branch) 또는 PR에 대한 다각도(multi-lens) 코드 리뷰. 최대 7개의 병렬 서브 에이전트 렌즈(정확성, 보안, UX 등)가 중복 제거 단계(dedup pass), 저비용-고심도 검증 게이트(cheap-then-deep validation gate), 그리고 (선택적으로) 전체적인 Opus 교차 검토 단계(holistic Opus cross-cutting pass)로 이어집니다. 신뢰도가 높은 자동 수정 제안(auto-fix proposals)이 미리 계산되므로, :fix 및 :walkthrough를 통해 한 번의 확인으로 일괄 승인할 수 있습니다. --ensemble 옵션을 사용하면 내부 Claude 렌즈 외에 Codex CLI 단계와 PR 봇 댓글 스크래핑(scrape) 기능이 추가됩니다.
• /adamsreview:codex-review — :review와 대등한 Codex CLI 기능. 동일한 아티팩트(artifact) 형태를 가지며, 하위의 모든 기능(:fix, :add, :walkthrough, :promote)에 즉시 적용 가능합니다. --effort low|medium|high|xhigh 옵션(기본값 high)을 통해 노력 수준을 조정할 수 있습니다.
• /adamsreview:add — 외부에서 가져온 결과물(Claude Code 클라우드 /ultrareview 붙여넣기, Opus 검토 결과, 팀원의 메모 등)을 가장 최근 리뷰의 아티팩트에 주입합니다. 기존 내용과 중복을 제거하고 동일한 게이트를 통해 검증한 후, 기존 PR 댓글에 다시 게시합니다.
• /adamsreview:walkthrough — :fix가 건너뛸 결과물들을 위한 대화형 드라이버(interactive driver)입니다.

하네스(harness)의 AskUserQuestion UI를 사용하여 불확실하거나 인간의 판단이 필요한 항목들을 하나씩 검토합니다 — 자동 수정(auto-fix)을 원하는 항목은 승인(promote)하고, 나머지는 건너뜁니다. 미리 계산된 자동 수정 제안들은 사전에 일괄 승인되며, 나머지는 각 발견 사항(finding)에 대한 브리핑 + 옵션 + 권장 사항을 제공받습니다. 결정 로그(decisions log)를 PR에 게시합니다.

• /adamsreview:fix — 자동 수정 루프(automated fix loop)입니다. 수정 그룹별로 서브 에이전트(sub-agents)를 병렬로 파견한 후, Opus를 통해 작업 내용을 재검토(re-review)하며, 회귀(regressions)가 발생한 사항은 되돌리고(reverts) 통과된 사항만 커밋(commits)합니다 (기본적으로 하나의 통합 커밋으로 생성되며, --granular-commits 사용 시 그룹당 하나의 커밋이 생성됩니다).
• /adamsreview:promote — 단일 발견 사항을 자동 수정 가능 상태로 승인하는 인간 개입(human override) 기능으로, 레인 필터(lane filter)와 점수 임계값(score threshold)을 우회합니다.

명령어 파일은 commands/ 하위의 bare-stem 경로에 위치하며, 공유된 단계별 파편(phase fragments) 및 프롬프트 참조는 fragments/ 하위에, 헬퍼 스크립트(helper scripts)와 아티팩트 스키마(artifact schema)는 bin/ 하위에 위치합니다. 플러그인 런타임(runtime)은 로드 시 bin/을 $PATH에 자동으로 추가하므로, 심볼릭 링크(symlinks)나 별도의 설치 스크립트가 필요하지 않습니다.

권장 워크플로우 (Recommended flow)

중요도가 높은 PR(non-trivial PR)의 경우, 명령어는 다음 순서로 사용할 때 가장 효과적입니다:

1. Review. /adamsreview:review — 또는 Codex CLI가 설치되어 있고 내부 Claude 렌즈 (lenses) 위에 Codex 패스와 PR 봇 코멘트 스크랩 (scrape)을 결합하고 싶은 경우 /adamsreview:review --ensemble을 사용하세요 (토큰 비용이 더 높음). 또는 Codex 기반의 피어 리뷰 (peer review)를 위해 /adamsreview:codex-review [--effort <level>]을 사용하세요 (모든 후속 단계에 바로 적용 가능하며, effort 조절이 가능하지만 --ensemble은 사용할 수 없음).
2. Add. (선택 사항) /adamsreview:add <paste...> — 만약 병렬 리뷰(cloud /ultrareview, Opus 1회 검토, 수동 스캔 등)를 실행하여 원래 리뷰에서 놓친 버그가 발견되었다면, 그 결과를 여기에 붙여넣으세요. 발견된 사항은 Phase 4에서 검증되며, 기존 내용과 중복 제거된 후 동일한 아티팩트 (artifact)에 저장됩니다. 자동 적격 (auto-eligible) 추가 사항은 4단계로 전달되며, 부적격 사항은 3단계에 나타납니다.
3. Walkthrough. (선택 사항) /adamsreview:walkthrough [threshold] — 수정 명령어 (fix command)가 건너뛸 발견 사항들(deep-manual, deep-report, 그리고 light confirmed_mechanical을 포함한 전체 light lane)을 단계별로 살펴봅니다. 신호가 낮은 항목이 세션을 채우지 않도록 $threshold(기본값 60) 이상의 점수를 받은 항목으로 제한됩니다. Phase 4.5는 사전 계산된 자동 수정 제안 (auto-fix proposal)이 포함된 모든 발견 사항을 한 번의 확인으로 일괄 승인합니다 (fast path). 나머지는 harness의 AskUserQuestion UI를 통해 항목별 브리핑 + 옵션 + 권장 사항을 제공받습니다. 맞춤형 수정 힌트 (fix-hints)와 함께 자동 수정하기를 원하는 항목은 승인(promote)하고, 나머지는 건너뜁니다. 감사(audit)를 위해 결정 로그 (decisions log)를 PR에 게시합니다. 더 낮은 임계값(예: /adamsreview:walkthrough 30)을 전달하고 사전 점검 프롬프트에서 Full 티어를 선택하면 Phase 3에서 강등된 below_gate 발견 사항도 감사할 수 있습니다.
4. Fix. /adamsreview:fix — 모든 자동 적격 발견 사항(2단계에서 추가되고 3단계에서 승인된 모든 사항 포함)을 적용합니다. Phase 7.5는 Phase 8 배포 (dispatch) 전, 남은 자동 수정 제안(light-lane / manual / report 발견 사항)을 한 번의 확인으로 일괄 승인할 수 있도록 노출합니다. 기본값은 생존한 모든 수정 사항에 대해 하나의 결합된 커밋 (combined commit)을 생성하는 것이며, 수정 그룹당 하나의 커밋을 생성하려면 --granular-commits를 전달하세요.

어떤 방식이든 그룹별 Phase-9 결과는 커밋 메시지에 포함됩니다.

각 명령은 독립적입니다. 자동 승인 가능한(auto-eligible) 결과에만 관심이 있다면 리뷰에서 바로 수정으로 넘어갈 수 있으며, 리뷰를 완전히 건너뛰고 기존 아티팩트(artifact)에 대해 :fix를 실행할 수도 있습니다. 2~4단계는 1단계 이후 며칠 또는 몇 주 뒤에 진행될 수 있습니다. 리뷰 아티팩트(review artifact)는 ~/.adams-reviews/<slug>/<branch>/ 경로에 유지됩니다.

/adamsreview:promote <id>는 워크스루(walkthrough) 흐름 이외의 일회성 수동 승인(manual promotion) 시 여전히 유용합니다 (예: --force를 사용하여 disproven 결과를 승인하거나, 개념적으로 일련의 ID들 — F003, F037, F039 — 에 대해 각각 --defer-publish를 사용하여 루프를 돌린 뒤 마지막 호출에서만 PR에 다시 게시하는 경우).

문서 (Documents)

• CLAUDE.md — 이 저장소에서 작업하는 Claude Code 세션을 위한 운영 가이드입니다. 일상적인 작업을 위해 독립적으로 구성되어 있으며, 새로운 세션 시작 시 가장 먼저 읽어야 합니다.
• docs/state-and-gates.md — 결과 상태 모델(finding state model), 점수 게이트(score gates), 딥/라이트 레인(deep/light lanes) (규범적 사양).
• docs/pipeline.md — 모든 명령에 대한 단계 트리(phase trees) 및 토큰 합계(token-tally) 의미론.
• docs/helpers.md — 헬퍼 스크립트 목록 및 배치 헬퍼(batched-helper) 패턴.
• bin/schema-v1.json — artifact.json을 위한 JSON 스키마 (아티팩트 구조의 진실의 원천).
• docs/archive/ — 고정된 설계 및 빌드 문서 (2026-04-19 이후). DESIGN.md (rev 8)는 원래의 규범적 사양이며, BUILD.md는 단계별 저널입니다. 유지 관리되지 않으므로 역사적 근거를 확인하는 용도로만 참조하십시오.
• plans/ — 브랜치별 계획 파일입니다. 활성 후속 작업은 GitHub 이슈에 있으며, 과거 백로그는 plans/old-backlog.md (2026-05-04 고정)에 있습니다.

의존성 (Dependencies)

런타임 (Runtime)

도구	버전	사용처	비고
uv	0.7+	artifact-patch.py, artifact-render.py	brew install uv. 스크립트는 PEP 723 인라인 스크립트 shebang (#!/usr/bin/env -S uv run --quiet --script)을 사용하여 uv가 첫 실행 시 jsonschema를 가져와 캐싱합니다 — 가상 환경(venv)이나 글로벌 pip 설치가 필요 없습니다
...

설치 (Installation)

macOS / Linux

설치 (Installation)

macOS / Linux

1. 의존성 설치: brew install uv jq gh git (macOS) 또는 해당 배포판의 상응하는 명령어를 사용하세요. (macOS의 기본 /bin/bash 3.2 버전도 괜찮습니다. 헬퍼(helpers)들은 3.2 버전에서도 호환됩니다.)
2. Claude Code 세션에서: /plugin marketplace add adamjgmiller/adamsreview를 실행합니다.
3. 동일한 세션에서: /plugin install adamsreview@adamsreview를 실행합니다.

Windows (native)

1. Git for Windows를 설치하세요. 이는 Claude Code가 내부적으로 사용하는 Git Bash (bash 5+) 및 git을 제공합니다. Claude Code는 #!/usr/bin/env bash 헬퍼를 Git Bash를 통해 자동으로 라우팅합니다. 만약 Git Bash가 기본 위치가 아닌 곳에 설치되어 있다면 CLAUDE_CODE_GIT_BASH_PATH를 설정하세요 (Troubleshooting 섹션 참조).
2. uv, jq, 그리고 GitHub CLI를 설치하세요.
3. Claude Code 세션에서: /plugin marketplace add adamjgmiller/adamsreview 및 /plugin install adamsreview@adamsreview를 실행합니다.

로컬 체크아웃(local checkout)에서 설치

이 리포지토리(repo)를 클론(clone)했으며 소스에서 직접 실행하는 것을 선호하거나, 특정 커밋(commit)에 고정하고 싶은 경우, GitHub 마켓플레이스를 거치지 않고도 작동하는 두 가지 경로가 있습니다:

• 로컬 경로를 통한 영구 설치. Claude Code 세션에서 /plugin marketplace add /path/to/adamsreview를 실행한 다음 /plugin install adamsreview@adamsreview를 실행합니다. 이는 위의 GitHub 마켓플레이스 흐름과 동일한 최종 상태를 가집니다. 플러그인은 ~/.claude/에 등록되며 재시작 후에도 유지됩니다. 현재 작업 디렉토리(cwd)가 이미 클론된 위치라면 절대 경로 대신 .을 사용하세요.
• --plugin-dir을 통한 일회성 실행. claude --plugin-dir /path/to/adamsreview를 실행하면 해당 세션에서만 클론된 내용이 플러그인으로 로드된 상태로 Claude Code가 실행됩니다. ~/.claude/에 아무것도 기록되지 않으며, 플래그 없이 다시 실행하면 플러그인은 사라집니다. 영구적인 상태 변경 없이 플러그인을 테스트하거나, 설치된 버전과 특정 체크아웃 버전을 병행하여 실행할 때 유용합니다.

두 경로 모두 위에 나열된 런타임 의존성(uv, jq, gh, bash, git)이 필요합니다.

명령어 (설치 후)

모든 호출은 플러그인 네임스페이스(plugin-namespaced)를 사용합니다:

• /adamsreview:review [--ensemble] [--full]
• /adamsreview:codex-review [--effort <low|medium|high|xhigh>] [--full]
• /adamsreview:add [<paste...>] [--file <path> --line <N> --claim "..."]
• /adamsreview:walkthrough [threshold]
• /adamsreview:fix [threshold]
• /adamsreview:promote <finding_id> [--reason "..."] [--fix-hint "..."]

--full (:review 및 :codex-review에서 사용 가능) 옵션은 사소한 모드(trivial-mode) 최적화를 해제하여, 작거나 문서 전용인 디프(diff)에서도 모든 탐지 렌즈(detection lens)가 실행되도록 강제합니다. 의도적으로 작게 만든 PR에 대해 전체 커버리지를 원할 때 유용합니다. 그렇지 않다면 기본값인 사소한 모드 분류기(trivial-mode classifier)를 사용하는 것이 적절합니다.

별도의 Python 의존성(dependency) 설치가 필요하지 않습니다. 모든 *.py 헬퍼의 첫 호출 시 uv가 선언된 의존성(jsonschema 등)을 해결하고 캐시합니다. 새 기기에서는 몇 초 정도 걸릴 수 있습니다 (Troubleshooting 참조). 이후 실행은 빠릅니다.

플러그인 개발자 반복 작업 (Plugin-author iteration)

플러그인을 단순히 사용하는 것이 아니라 직접 수정 중이라면, scripts/dev-run.sh를 통해 작업 트리(working tree)를 claude --plugin-dir "$(pwd)"로 플러그인으로서 로드된 Claude Code를 실행할 수 있습니다. 마켓플레이스 설치가 필요하지 않습니다. 작업 트리로부터 설치 경로를 시뮬레이션하려면 Claude Code 세션 내부에서 /plugin marketplace add .을 실행하세요.

리뷰 상태 저장 위치 (Review state location)

/adamsreview:review는 실행당 상태(아티팩트(artifact), 트레이스(trace), 단계 로그(phase logs), 토큰 로그(token logs))를 ~/.adams-reviews/<repo-slug>/<branch>/<review_id>/ 아래에 기록합니다. 상태를 다른 곳에 저장하고 싶다면 export ADAMS_REVIEW_REVIEWS_ROOT=/some/other/path로 재정의할 수 있습니다.

왜 ~/.claude/reviews/를 사용하지 않나요? Claude Code는 ~/.claude/...에 대한 쓰기 작업 시 민감한 파일 권한 프롬프트를 하드코딩하여 제공하며, 이는 bypassPermissions 모드에서도 유지됩니다. 또한 ~/.claude/reviews는 예외 하위 디렉토리 목록(.claude/commands, .claude/agents, .claude/skills)에 포함되어 있지 않습니다. 리뷰 상태를 ~/.claude/ 외부로 유지함으로써 실행당 수십 번 발생하는 권한 프롬프트를 방지할 수 있습니다.

Stage-2.5 이전 상태로부터의 마이그레이션. 만약 ~/.claude/reviews/ 아래에 리뷰가 있다면, 다음 중 하나를 수행하세요:

# 옵션 A: 상태를 새로운 표준 루트로 이동 (권장).
mv ~/.claude/reviews ~/.adams-reviews

...

토큰 수 (Token counts): 측정 항목

렌더링된 보고서에는 두 가지 숫자가 나타날 수 있습니다:

• 서브 에이전트 토큰 (Sub-agent tokens) — 각 리뷰별 tokens.jsonl 로그에서 합산됩니다. 이 특정 리뷰를 위해 파견된 모든 서브 에이전트(lenses, validators, fix agents, post-fix reviewer 등)를 계산합니다. 정확하며 항상 표시됩니다.
• 오케스트레이터 토큰 (Orchestrator tokens) — ~/.claude/projects/<cwd-slug>/ 아래의 Claude Code 세션 트랜스크립트(transcripts)에서 timestamp >= review_started_at인 어시스턴트 턴(assistant turns)만 필터링하여 합산됩니다. subagent_tokens가 의도적으로 제외한 메인 세션 비용을 포착합니다. 선택 사항 (Opt-in) — 아래 내용을 참조하세요.

두 값이 모두 채워지면 서로 보완적이며(중복 없음), 이를 통해 총 비용을 추정할 수 있습니다.

오케스트레이터 토큰은 선택 사항 (opt-in)입니다

macOS Sequoia 및 Tahoe에서는 셸 헬퍼(shell helper)가 com.apple.provenance 확장 속성(extended attribute)이 표시된 파일을 처음 읽을 때 "kitty(또는 사용 중인 터미널)가 다른 앱의 데이터에 접근하려고 합니다"라는 프롬프트를 표시합니다. 모든 Claude Code 트랜스크립트에는 이 속성이 포함되어 있으며, bin/orchestrator-tokens.sh가 이를 읽습니다. 따라서 헬퍼는 모든 리뷰의 첫 번째 라이프사이클(lifecycle) 명령에서 프롬프트를 트리거하게 되며, (이 게이트에 대한 TCC 캐시가 부분적이기 때문에) 그 이후에도 반복적으로 발생하게 됩니다. 사용자에게 번거로움을 주지 않기 위해, 헬퍼는 기본적으로 건너뛰도록 설정되어 있습니다.

활성화하려면 다음 중 하나를 수행하세요: