Claude Code로 AI가 코드를 짜고 AI가 리뷰하는 개발 워크플로 구축하기

Jaewoo Kim·2026년 3월 31일

Claude Code 설치가이드 (Windows용)

목록 보기

4/6

이 글에서는 Claude Code(코드 작성 담당)와 리뷰 담당 AI(서브에이전트)를 조합해 코드 품질을 자동으로 높이는 개발 방식을 소개한다.

보통은 하나의 AI에게 전부 맡긴다. 하지만 그렇게 하면 자신이 만든 것에는 관대해지기 쉬워 문제를 놓치는 경우가 생긴다.
사람 개발팀에서도 "만드는 사람"과 "검토하는 사람"을 나누듯, AI도 역할을 분담하면 결과물의 품질이 눈에 띄게 달라진다.

처음에는 Claude Code와 OpenAI의 Codex CLI를 조합하는 방식을 시도했다.
하지만 Claude Code만으로도 같은 체계를 구축할 수 있다는 것을 알았고, 이 글에서는 그 방법을 중심으로 설명한다.

💡 Codex CLI와 조합하는 방법이 궁금한 분은 맨 아래 "참고: Codex CLI 방식"을 참고하자.

검증 환경: Windows 11 / Claude Code (2026년 3월 기준)

용어 정리

이 글에서 사용하는 핵심 용어를 먼저 정리해둔다.

용어	의미
서브에이전트	Claude Code 안에서 동작하는 "별도의 AI 담당자". 메인 AI가 다른 AI에게 특정 작업을 위임하는 기능
Builder (빌더)	코드를 직접 작성하는 담당. 이 글에서는 Claude Code의 메인 AI
Auditor (오디터)	코드를 검토하는 담당. 이 글에서는 읽기 전용 서브에이전트
스킬	Claude Code에 등록해두는 "단축 명령어". `/review` 처럼 한 단어로 복잡한 작업을 실행할 수 있다

두 가지 방식 비교

역할 분담을 구현하는 방법은 크게 두 가지다. 특별한 이유가 없다면 서브에이전트 방식을 강력히 추천한다.

항목	서브에이전트 방식	Codex CLI 방식
추가 비용	없음 (Claude Pro/Max만으로 OK)	ChatGPT Plus($20/월) 또는 Pro($200/월) 별도 필요
셋업	파일 2개 만들기만으로 완료	WSL + Node.js + 계정 인증 필요
조작	같은 터미널 창 안에서 완결	터미널 2개를 오가며 작업
재사용성	한 번 만들면 모든 프로젝트에서 재사용	프로젝트마다 설정 필요
안정성	매우 안정적, 트러블 거의 없음	인증 오류 등 발생하기 쉬움

서브에이전트 방식 — 구조와 원리

어떻게 동작하나

Claude Code에는 메인 AI가 별도의 "서브 AI"에게 작업을 위임하는 서브에이전트 기능이 있다.

핵심 설계: 체크 담당 AI는 읽기 전용으로 제한한다

이 제한을 걸어두면 "리뷰 담당이 마음대로 코드를 수정해버리는" 문제를 완전히 방지할 수 있다.
Auditor는 문제를 지적만 하고, 실제 수정은 Builder(메인 AI)가 담당하는 명확한 분업 구조가 된다.

┌─────────────────────────────────────────────┐
│  Claude Code                                │
│                                             │
│  ┌─────────────┐      ┌─────────────┐      │
│  │  Builder    │ ──→  │  Auditor    │      │
│  │ (메인 AI)   │ ←── │ (서브 AI)   │      │
│  │             │      │             │      │
│  │ · 코드 작성  │      │ · 리뷰       │      │
│  │ · 수정       │      │ · 문제 지적  │      │
│  │ · 테스트 작성│      │ · 수정은 안 함│     │
│  └─────────────┘      └─────────────┘      │
└─────────────────────────────────────────────┘

환경 구축 (4단계)

전제 조건

항목	요건
Claude Code	설치 완료 (설치 가이드 참조)
Claude 플랜	Pro ($20/월) 또는 Max ($100~/월)
Git	설치 및 초기 설정 완료 (`git init` 또는 기존 저장소)

Step 1: 폴더 만들기

서브에이전트 설정 파일을 저장할 폴더를 생성한다.

Windows (PowerShell):

New-Item -ItemType Directory -Force -Path ".claude\agents\code-auditor"

macOS / Linux:

mkdir -p .claude/agents/code-auditor

Step 2: 서브에이전트 정의 파일 만들기

📝 .claude/agents/code-auditor/code-auditor.md 를 아래 내용으로 생성한다.

이 파일이 Auditor의 "역할 설명서"다. 어떤 관점으로 코드를 검토하고, 어떤 형식으로 결과를 출력할지를 정의한다.

---
name: code-auditor
description: 코드 품질·보안 감사 전문가
tools: Read, Grep, Glob, Bash
model: sonnet
disallowedTools: Write, Edit, NotebookEdit
---

당신은 시니어 코드 리뷰어입니다.
변경된 코드를 다음 관점으로 엄격하게 감사해주세요.

## 감사 관점

### 1. 보안 (🔴 중대)
- XSS, 커맨드 인젝션
- 기밀 정보 하드코딩
- 외부 입력값을 검증 없이 그대로 사용

### 2. 버그 가능성 (🔴 중대)
- null/undefined 참조 오류
- 경계 조건 미처리 (빈 배열, 0, 음수값)
- 비동기 처리의 에러 핸들링 누락
- 타입 불일치 오류

### 3. 성능 (🟡 개선 권고)
- 불필요한 재렌더링 (useCallback, useMemo 부재)
- 과도하게 큰 컴포넌트 (분리 검토)
- 반복 호출되는 무거운 연산의 메모이제이션

### 4. 코딩 규약 (🟡 개선 권고)
- 네이밍 규칙 준수 여부
- 함수 길이 (50줄 이상은 분리 검토)
- 사용되지 않는 변수·import

## 출력 형식

## 감사 결과

### 🔴 중대한 문제 (blocking)
（반드시 수정해야 할 문제. 없으면 「없음」）

### 🟡 개선 권고 (advisory)
（가능하면 개선하면 좋은 항목. 없으면 「없음」）

### 🟢 잘 된 점
（좋은 코딩 프랙티스가 있으면 기재）

### 📝 총평
（전체적인 평가와 다음에 할 일）

💡 disallowedTools의 역할
disallowedTools: Write, Edit를 명시하면 이 서브에이전트는 파일 쓰기·편집이 불가능해진다.
읽기 전용 모드로 동작하므로 리뷰 담당이 코드를 마음대로 수정하는 사태를 방지할 수 있다.

Step 3: 리뷰 스킬(단축 명령어) 만들기

/review라고 입력하는 것만으로 즉시 리뷰를 실행할 수 있도록 단축 스킬을 만든다.

Windows (PowerShell):

New-Item -ItemType Directory -Force -Path ".claude\skills\review"

macOS / Linux:

mkdir -p .claude/skills/review

📝 .claude/skills/review/SKILL.md 를 아래 내용으로 생성한다.

---
name: review
description: 코드 리뷰를 실행. 「리뷰해줘」「이 코드 봐줘」「PR 확인해줘」「품질 확인해줘」로 호출됨
context: fork
agent: code-auditor
---

최근 변경사항을 리뷰해주세요.

## 리뷰 대상 파일
!`git diff --name-only HEAD~1 2>/dev/null || git diff --name-only`

## 변경 내용
!`git diff HEAD~1 2>/dev/null || git diff`

💡 ! 기법이란?
!로 시작하는 줄은 명령어 실행 결과를 그 위치에 자동으로 삽입하는 기법이다.
위 예시에서는 git diff 결과(변경된 코드 전체)가 자동으로 Auditor에게 전달된다.

Step 4: 글로벌 배치 (모든 프로젝트에서 재사용)

한 번 만든 설정을 모든 프로젝트에서 재사용할 수 있도록 글로벌 디렉터리에 복사한다.

Windows (PowerShell):

$claudeDir = "$env:USERPROFILE\.claude"

# 에이전트 글로벌 배치
New-Item -ItemType Directory -Force -Path "$claudeDir\agents\code-auditor"
Copy-Item ".\.claude\agents\code-auditor\code-auditor.md" "$claudeDir\agents\code-auditor\"

# 스킬 글로벌 배치
New-Item -ItemType Directory -Force -Path "$claudeDir\skills\review"
Copy-Item ".\.claude\skills\review\SKILL.md" "$claudeDir\skills\review\"

macOS / Linux:

mkdir -p ~/.claude/agents/code-auditor
mkdir -p ~/.claude/skills/review

cp .claude/agents/code-auditor/code-auditor.md ~/.claude/agents/code-auditor/
cp .claude/skills/review/SKILL.md ~/.claude/skills/review/

이것으로 준비 완료. 이후 어떤 프로젝트에서도 /review 명령어를 즉시 사용할 수 있다.

실전: 수정 사이클 전체 흐름

구현 → 커밋 → /review → 문제 있음? → 수정 의뢰 → 재리뷰 → 완료
                              ↑_______________|

Step 1: Claude Code로 기능 구현

평소처럼 Claude Code에 요건을 전달한다. "어떻게 만들지"는 Claude에게 맡겨도 된다.

간단한 할 일 목록 앱을 만들어줘.
태스크 추가·완료·삭제 기능이 있어야 하고, 페이지를 새로고침해도 데이터가 유지되도록 해줘.

Step 2: 리뷰 의뢰

구현이 끝나면 단 한 줄로 리뷰를 요청한다.

/review

스킬이 자동으로 실행되어 Auditor가 최근 변경된 파일 전체를 검토하고 결과를 반환한다.

💡 스킬 없이 직접 지시하는 방법도 있다
code-auditor 서브에이전트를 사용해서 최근 변경사항을 리뷰해줘
단, /review 쪽이 훨씬 간단하므로 스킬 방식을 권장한다.

Step 3: 리뷰 결과 확인

Auditor가 아래 형식으로 결과를 반환한다:

중요도	파일	문제	권고 대응
🔴 blocking	todo.js	삭제 후 화면이 갱신되지 않음	상태 재렌더링 처리 추가
🟡 advisory	todo.js	빈 문자열도 태스크로 추가됨	입력값 유효성 검사 추가
🟢 good	app.js	async/await 일관되게 사용	—

Step 4: 수정 의뢰

리뷰 결과를 바탕으로 Builder(메인 AI)에게 수정을 요청한다.

code-auditor의 리뷰 결과에 나온 문제점을 모두 수정해줘

💡 "어떻게 고칠지"는 지시하지 않아도 된다
Claude Code가 리뷰 결과를 참고해 스스로 최선의 수정 방법을 찾아서 구현한다.
오히려 세세하게 지시하면 Claude의 판단 범위를 좁혀 역효과가 날 수 있다.

Step 5: 재리뷰 → 완료

수정 완료 후 다시 리뷰를 돌린다.

/review

🔴 중대한 문제: 없음 이 되면 해당 기능은 완료다.

자주 쓰는 명령어 모음

명령어	용도
`/review`	최근 변경사항 전체를 리뷰
`/review 123`	PR #123을 리뷰 (커스텀 커맨드 설정 시)
`〇〇 파일을 리뷰해줘`	특정 파일만 리뷰
`프로젝트 전체를 리뷰해줘`	저장소 전체를 종합 검토

💡 PR(Pull Request)란
GitHub에서 코드 변경 내용을 팀원에게 제안하고 리뷰를 받는 기능이다.
개인 프로젝트에서는 사용하지 않는 경우도 많으니, 모른다면 일단 건너뛰어도 무방하다.

효과적으로 활용하는 요령

1. "무엇을"만 전달하고 "어떻게"는 Claude에게 맡긴다

✅ 좋은 예	❌ 나쁜 예
"삭제 버튼이 작동하지 않습니다. 고쳐주세요"	"○번째 줄의 △을 □으로 바꿔줘"처럼 세세하게 지정
"리뷰 결과의 blocking 항목을 모두 수정해줘"	수정 코드를 직접 작성해서 전달
"로그인 기능을 추가해줘"	"JWT로 인증하고 Redis에 세션을 저장해줘"처럼 구현 방법 지정

요건(무엇을 달성하고 싶은가)만 전달하면 Claude가 최적의 방법을 스스로 선택한다.

2. 오류 메시지는 그대로 복붙한다

빌드 오류, 런타임 오류가 발생하면 오류 메시지를 가공하지 말고 그대로 붙여넣기 후 "고쳐줘"만 하면 된다.
오류 스택 트레이스 전체를 전달할수록 Claude가 원인을 정확하게 파악한다.

3. 작업 단위로 커밋한다

AI가 의도치 않은 변경을 했을 때 즉시 되돌릴 수 있도록, CLAUDE.md에 자동 커밋 규칙을 추가해두면 편하다:

## Git 운용 규칙

### 자동 커밋 타이밍
다음 타이밍에 반드시 커밋을 생성해주세요:
1. 기능 구현이 완료되었을 때
2. 버그 수정이 완료되었을 때
3. 사용자가 「구분」「일단락」이라고 말했을 때

### 커밋 메시지 형식
변경 내용을 한눈에 알 수 있는 한국어 메시지를 사용해주세요.
예: feat: 할 일 삭제 기능 추가 / fix: 빈 태스크 추가 방지 유효성 검사

4. 리뷰 타이밍 기준

타이밍	이유
새 기능 구현 완료 직후	기능 단위로 품질 보증
5개 이상의 파일을 변경했을 때	대규모 변경에는 예상치 못한 문제가 숨어있기 쉬움
커밋 or PR 생성 전	저장소에 문제 코드가 남아있지 않도록
작업 세션 종료 전	다음 세션 시작 전에 깨끗한 상태로 마무리

잘 안 될 때 체크 포인트

① description이 너무 모호하다

SKILL.md의 description이 막연하면 Claude가 적절한 타이밍에 스킬을 호출하지 않는다.

❌ 문제 있는 설정	✅ 개선 예시
`description: 리뷰`	`description: 코드 리뷰를 실행. 「리뷰해줘」「이 코드 봐줘」「PR 확인해줘」로 호출됨`

구체적인 트리거 문구를 여러 개 명기해두면 의도한 타이밍에 자동 호출될 확률이 크게 높아진다.

② SKILL.md 파일이 너무 길다

SKILL.md가 지나치게 길면 Claude의 컨텍스트(처리 가능한 정보량)를 압박해 전체 성능이 저하된다.

기준: 500줄 이하로 유지
자세한 예시나 템플릿은 examples.md로 분리하고 SKILL.md에서는 해당 파일을 참조하는 형식으로 구성한다

③ 컨텍스트가 꽉 찼다

장시간 작업으로 대화 이력이 쌓이면 응답이 느려지거나 스킬 호출이 불안정해진다:

/compact

대화를 자동 요약해 컨텍스트를 정리한다. 이후 동작이 안정될 때가 많다.

실제로 해보고 알게 된 것

잘 됐던 포인트

포인트	구체적인 내용
역할 분담의 효과	Builder 혼자서는 놓쳤을 법한 보안 취약점이나 엣지 케이스를 Auditor가 잡아줬다
맡기는 자세의 중요성	구현 방법을 세세하게 지정하는 것보다 요건만 전달했을 때 결과물이 더 깔끔했다
글로벌 설정의 편의성	한 번 설정해두니 새 프로젝트를 시작할 때마다 즉시 `/review`를 사용할 수 있었다
커밋 규칙 추가 효과	자동 커밋 덕분에 `/rewind` 없이도 원하는 시점으로 언제든 돌아갈 수 있었다

처음에 막혔던 포인트

문제	해결책
GitHub 인증 오류	Personal Access Token(PAT)으로 대응 (트러블슈팅 편 참조)
빌드 오류 해결이 잘 안 됨	오류 메시지 전체를 가공 없이 Claude Code에 붙여넣기
지시가 너무 구체적이었다	"어떻게"가 아닌 "무엇을"만 전달하는 방식으로 바꾸자 결과가 좋아졌다
SKILL.md 호출이 불안정했다	description에 트리거 문구를 여러 개 추가하자 안정적으로 호출됨

시작 전에 확인해두면 좋은 것

확인 항목	이유
Git 초기 설정 완료 여부	`/review` 스킬이 `git diff`를 사용하기 때문
배포 방법 및 공개 범위	Claude가 배포 방식을 고려해 코드를 작성할 수 있도록
로컬 실행 확인 방법	빌드·테스트 명령어를 CLAUDE.md에 명시해두면 좋다

정리

방식	추천도	이유
서브에이전트 방식	⭐⭐⭐	간단, 추가 계약 불필요, 안정적
Codex CLI 방식	⭐	설정 복잡, 추가 유료 계약 필요, 트러블 多

"만드는 사람"과 "검토하는 사람"을 나누면 한 명(하나의 AI)이 모두 하는 것보다 결과물의 품질이 올라간다.
Claude Code의 서브에이전트 기능을 사용하면 추가 비용 없이 이 분업 체계를 즉시 구축할 수 있다.

발전편: GitHub Actions 연동

GitHub Actions 연동의 자세한 내용 (클릭해서 펼치기)

자동 리뷰 구조

GitHub Actions와 연동하면 PR을 생성할 때마다 Claude Code가 자동으로 리뷰를 실행한다.

PR 생성 → 자동으로 리뷰 코멘트가 게시됨
PR 코멘트에 @claude로 멘션하면 추가 지시 가능
리뷰 완료까지 약 3~4분 소요

커스텀 명령어 `/review {PR번호}` 만들기

.claude/commands/review.md를 만들면 /review 123으로 PR #123을 바로 리뷰할 수 있다.

PR #$ARGUMENTS 를 리뷰해주세요.

1. `gh pr view $ARGUMENTS` 로 PR 개요 확인
2. `gh pr diff $ARGUMENTS` 로 변경 내용 취득
3. code-auditor 서브에이전트를 사용해서 리뷰
4. 결과를 표 형식으로 출력

$ARGUMENTS란?
/review 123을 입력하면 $ARGUMENTS 부분이 123으로 자동 치환된다.

참고 자료

GitHub Actions 연동의 자세한 설정은 아래를 참고:

Claude Code "skills"로 리뷰 자동화를 구조화하기 - Zenn

참고: Codex CLI 방식

Codex CLI 방식의 자세한 내용 (클릭해서 펼치기)

GPT 계열 모델의 시각도 도입하고 싶거나 이미 ChatGPT Plus/Pro를 구독 중인 경우의 대체 방식.

구조

Claude Code(Builder)와 OpenAI Codex CLI(Auditor)를 터미널 2개에서 병렬 실행한다.

┌──────────────────┐      ┌──────────────────┐
│  PowerShell      │      │  WSL Ubuntu      │
│                  │      │                  │
│  Claude Code     │ ───→ │  Codex CLI       │
│  (Builder)       │ ←─── │  (Auditor)       │
└──────────────────┘      └──────────────────┘

비용

툴	필요한 구독
Claude Code	Claude Pro 또는 Max
Codex CLI	ChatGPT Plus 또는 Pro (별도 비용)

셋업 흐름

WSL2 설치
WSL 안에서 Node.js 설치
Codex CLI 설치
ChatGPT 계정으로 인증

WSL2 설치

WSL2 셋업이 되어 있지 않다면 Microsoft 공식 문서를 참조한다.

Codex CLI 설치

WSL 안에서:

# 패키지 업데이트
sudo apt update && sudo apt upgrade -y

# wslu 설치 (브라우저 인증용)
sudo apt install -y wslu

# nvm 설치
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
source ~/.bashrc

# Node.js v22 설치
nvm install 22

# Codex CLI 설치
npm i -g @openai/codex

인증

WSL 안에서:

codex

최초 실행 시 "Sign in with ChatGPT"를 선택하면 브라우저가 열린다.

주의사항

ChatGPT Plus/Pro 별도 구독 필요 (월 $20~$200)
브라우저 인증 시 ERR_CONNECTION_REFUSED 오류가 발생하는 경우가 있다
- 이 경우 Personal Access Token 방식으로 우회한다
한국 네트워크 환경에서 방화벽이나 보안 소프트웨어(V3, 알약 등)로 인해 연결이 차단될 수 있다

Jaewoo Kim

이전 포스트

Claude Code가 실행되지 않을 때 보는 페이지 (Windows 트러블슈팅)

다음 포스트

Claude Code로 AI가 코드를 짜고 AI가 리뷰하는 개발 워크플로 구축하기

Claude Code 설치가이드 (Windows용)

용어 정리

두 가지 방식 비교

서브에이전트 방식 — 구조와 원리

어떻게 동작하나

환경 구축 (4단계)

전제 조건

Step 1: 폴더 만들기

Step 2: 서브에이전트 정의 파일 만들기

Step 3: 리뷰 스킬(단축 명령어) 만들기

Step 4: 글로벌 배치 (모든 프로젝트에서 재사용)

실전: 수정 사이클 전체 흐름

Step 1: Claude Code로 기능 구현

Step 2: 리뷰 의뢰

Step 3: 리뷰 결과 확인

Step 4: 수정 의뢰

Step 5: 재리뷰 → 완료

자주 쓰는 명령어 모음

효과적으로 활용하는 요령

1. "무엇을"만 전달하고 "어떻게"는 Claude에게 맡긴다

2. 오류 메시지는 그대로 복붙한다

3. 작업 단위로 커밋한다

4. 리뷰 타이밍 기준

잘 안 될 때 체크 포인트

① description이 너무 모호하다

② SKILL.md 파일이 너무 길다

③ 컨텍스트가 꽉 찼다

실제로 해보고 알게 된 것

잘 됐던 포인트

처음에 막혔던 포인트

시작 전에 확인해두면 좋은 것

정리

발전편: GitHub Actions 연동

자동 리뷰 구조

커스텀 명령어 /review {PR번호} 만들기

참고 자료

참고: Codex CLI 방식

구조

비용

셋업 흐름

WSL2 설치

Codex CLI 설치

인증

주의사항

Claude Code가 실행되지 않을 때 보는 페이지 (Windows 트러블슈팅)

Claude Code 이전 완전 가이드: 웹 버전 지식을 CLI로 완벽하게 옮기는 법

0개의 댓글

커스텀 명령어 `/review {PR번호}` 만들기