AI가 작성한 코드의 품질이 불안하다면 — 직접 만든 'AI 리뷰어' 4가지 관점 목록 전체 공개

"AI에게 코드를 작성하게 하면, 품질이 불안해요." — AI 기반 개발에 대한 이야기를 하면 거의 확실하게 이 질문을 받습니다.

제 대답은 "인간이 코드를 모든 줄 읽는 것"이 아닙니다. 품질 게이트를 3단계로 쌓고, 그 게이트의 관리자까지 AI에게 맡기는 것입니다.

개인 개발 SNS 'ShippAI'(실패를 AI가 웃음과 교훈으로 바꾸는 SNS)를 Claude Code와 사양(spec) 18개의 SDD(Specification Driven Development, 사양 주도 개발)로 구현하며, 그 품질을 지탱해 온 것이 직접 만든 'AI 리뷰어' 4가지입니다. 이 글에서는 그 관점 목록 전체를 공개합니다. Claude Code를 사용하고 있다면 그대로 복사하여 자신의 프로젝트에 맞게 수정할 수 있을 것입니다.

전반적인 구조: 이중 리뷰 게이트

구조는 간단하며, 개발 파이프라인에 리뷰 게이트를 2곳 배치했습니다.

Gate ① (상류): requirements / design / tasks 작성을 완료하면 spec-review

— 구현에 들어가기 전에 사양의 결함을 감지합니다 -
Gate ② (하류): 테스트 선행(RED 확인) → 구현(GREEN) 후에 code-review

— 구현의 결함을 감지합니다

여기에 '테스트가 먼저 실패하는 것(RED)의 확인'을 더하면, 품질 보장이 3단계로 이루어집니다.

단계	무엇을 보장하는가	수단
1	사양의 정확성	spec-review (AI 리뷰어)
...
핵심은, 작성한 AI와 리뷰하는 AI를 분리하는 것입니다. 구현한 본인(과 같은 컨텍스트)에게 리뷰하게 하면 '내 판단이 옳다'는 전제를 끌고 가게 됩니다. 리뷰어는 독립적인 에이전트 정의로 분리하고, 쓰기 권한을 주지 않습니다. 지적 사항과 수정 제안까지 나오게 하고, 적용할지는 인간이 판단합니다.

리뷰어 4가지의 관점 목록

리뷰어는 .claude/agents/*-reviewer.md에 넣은 단순 Markdown 파일입니다. 특별한 메커니즘을 사용하지 않습니다. '역할・관점・출력 포맷・판정 기준'을 작성해 두고, 리뷰 시 Claude Code가 이 정의를 읽어 들여 그 인격으로 리뷰합니다.

1. requirements-reviewer (Gate 1: 요구사항의 관리자)

## 리뷰 관점
1. **비전 일관성**: 사용자 경험이 제품 비전에 부합하는가?
2. **EARS 5 패턴 통일**: 모든 수용 기준(AC)이 WHEN-SHALL / IF-THEN /
...

효과적인 것은 2번과 4번입니다. 수용 기준을 EARS 표기법(WHEN ~ THE SYSTEM SHALL ~ 형식)으로 강제하면, '좋게 보이는' 같은 모호한 요구사항을 작성할 수 없게 됩니다. R1.2와 같은 번호 체계는 후속 design・tasks에서 '이 태스크는 R1.2를 충족하기 때문에'라고 추적하는 데 필수입니다.

2. design-reviewer (Gate 2: 설계의 관리자)

## 리뷰 관점 (발췌)
- **컨셉 일관성**: 제품의 컨셉이 시각적으로 표현되었는가
- **레이아웃 원칙 준수**: 확정된 레이아웃 구성이 유지되는가
...

설계 리뷰의 핵심은, 기술적으로 불가능한 설계를 구현 전에 막는 것입니다. 예를 들어 Next.js에서는 'use client' 파일에서 generateMetadata를 export 할 수 없습니다. 이러한 종류의 '작성은 가능하지만 작동하지 않는 설계'는, 구현에 들어가서야 발견되면 design 단계까지 되돌아갑니다.

3. tasks-reviewer (Gate 3: 태스크 분해의 관리자)

## 리뷰 관점
1. **태스크의 세분성**: 1개의 태스크가 1커밋에 해당하며 '수직 슬라이스(기능이 작동하는 단위)'인가?
2. **종속 관계의 일관성**: 종속 설정에 병렬 작업이나 순서상의 무리가 없는가
...

개인적으로 가장 좋아하는 것은 5. 빌드 연속성입니다. AI에게 태스크를 순차적으로 구현하게 하면, 태스크 3 도중에 빌드가 깨지는 분해를 거리낌 없이 합니다. '어떤 태스크 완료 시점에서도 빌드가 통과하는' 것을 태스크 분해 단계에서 요구하면, 원자적인 커밋이 자연스럽게 만들어집니다.

4. code-reviewer (Gate ②: 구현의 관리자)

리뷰 관점 (발췌)

1. RSC/CC 분리: 기본적으로 Server Component인가? 'use client' 사용은 최소한인가?
2. TypeScript & 안전성: any가 사용되지 않았는가? API 키와 같은 기밀 정보가
   ...

사령탑과 파수꾼을 분리하기

리뷰어 정의(관점)와 그것을 "언제·어떻게 호출할 것인가"(운영)는 별도의 파일로 나누어 관리합니다. 운영 측면은 .claude/skills/spec-review/SKILL.md라는 스킬로 구성되어 있으며, 설계는 다음과 같습니다.

• 인자 없이 호출하면, 최신 spec의 "가장 진전된 미리뷰 단계"를 자동 추정하여 리뷰
• all 지정 시 3개 단계를 병렬 서브 에이전트 (Parallel Sub-agent) (독립 컨텍스트)로 리뷰하여 통합 리포트 생성
• 리뷰 시 대상 파일뿐만 아니라 상류의 결과물도 읽음 (tasks 리뷰 시에는 requirements와 design도 읽으며, R1.2와 같은 참조 번호가 실제로 존재하는지 검증)
• 지적 사항은 CRITICAL / HIGH / MEDIUM / LOW의 심각도(Severity)를 포함
• CRITICAL이 단 1건이라도 있으면 Gate 통과 불가
• 수정 제안까지는 제시하지만, 자동으로 적용하지는 않음. 적용은 인간의 승인 후에 진행

스킬 본체에는 다음과 같이 적혀 있습니다.

Skill은 사령탑, Agent는 관점의 격리 장치입니다. 관점의 정의는 .claude/agents/*-reviewer.md에 집약되어 있으며, 이 스킬은 그것을 "언제·어떻게 호출할 것인가"만을 담당합니다. 관점을 이중으로 관리하지 않습니다.

실제로 무엇이 포착되었나

도입 이후의 실적을 숨김없이 그대로 적습니다.

• CRITICAL 포착: 동적 OGP 이미지 (next/og)에서 일본어 폰트를 명시적으로 로드하지 않았던 문제. 로컬에서는 렌더링되지만, 프로덕션 배포 후 일본어가 깨지는(□□□) 현상입니다. code-review가 "CJK 폰트의 서브셋 fetch가 없다"고 지적하여 배포 전에 수정할 수 있었습니다.
• HIGH 포착: 게시물의 "교훈" 필드를 공유 기능으로 전달하는 경로의 불일치. 기능 단독으로는 작동하지만, 조합했을 때 오래된 데이터 구조를 참조하는 케이스입니다.
• spec-review의 HIGH/MEDIUM: 최근 spec에서도 구현 전 리뷰를 통해 요구사항의 누락(예외 상황의 fallback 미정의 등)이 여러 건 포착되어, requirements 단계에서 수정하고 있습니다.
• 오탐(False Positive)도 있음: 심각도 LOW인 지적에 대해서는 "고치지 않아도 된다"고 판단하여 넘긴 것도 있습니다. 리뷰어의 지적을 모두 따르는 것이 아니라, 판단 재료로 삼아야 합니다. 최종 판단은 인간이 한다는 것이 운영의 전제입니다.

함정: 리뷰어 스스로가 노후화된다

이것은 이 메커니즘의 약점이기에 솔직하게 적어둡니다. 리뷰어 정의는 프로덕트의 진화에 뒤처지게 됩니다.

실제로 저희의 design-reviewer에는 초기 컨셉의 어휘(이후 사양 변경으로 폐지된 기능명)가 한동안 남아 있었습니다. 리뷰어가 오래된 사양을 "정답"으로 간주하고 리뷰하면, 올바른 변경에 대해 잘못된 지적을 하게 됩니다.

대책은 간단합니다. 사양을 크게 변경한 spec의 태스크에 "리뷰어 정의 동기화"를 포함하는 것입니다. CLAUDE.md나 문서 동기화와 동일하게 취급합니다. AI 리뷰어는 작성하는 순간부터 열화가 시작된다고 생각하는 것이 적당합니다.

요약

• AI의 코드 품질은 "인간이 모든 행을 읽는 것"이 아니라, spec-review → RED 확인 → code-review의 3단계 Gate로 담보한다.
• 리뷰어는 .claude/agents/에 있는 단순한 Markdown이다. 관점·출력 형식·판정 기준을 적어두기만 하면 된다.
• 쓰는 AI와 리뷰하는 AI를 분리하고, 리뷰어에게 쓰기 권한을 주지 않는다.
• CRITICAL 1건이면 Gate 통과 불가. 단, 적용 판단은 항상 인간이 한다.
• 리뷰어 정의는 열화된다. 사양 변경 시 동기화하는 태스크를 잊지 말 것.

이 메커니즘으로 개발 중인 "ShippAI" (실패를 AI가 웃음과 교훈으로 바꾸는 SNS)는 곧 출시 예정입니다. 개발 진행 상황은 X @ShippAI_dev 에서 실시간으로 공개하고 있으니, AI-driven development의 실례에 관심이 있다면 팔로우해 보세요. SDD(Specification Driven Development)의 진행 방식 자체는 별도의 글로 작성하겠습니다.

Discussion