Claude Code로 코드 리뷰 자동화하기, 설정부터 실패 학습 루프까지

.claude/
├── settings.json        # 프로젝트 설정
├── settings.local.json  # 로컬 설정（.gitignore）
├── rules/               # 프로젝트 규칙
├── commands/            # 사용자 정의 명령
├── skills/              # 스킬
├── agents/              # 하위 에이전트
└── output-styles/       # 아웃풋 스타일

.claude/settings.json

{
  "sandbox": {
    "enabled": true,
    "allowUnsandboxedCommands": false,
    "filesystem": {
      "denyRead": ["~/.aws/credentials", "~/.ssh"]
    },
    "network": {
      "allowedDomains": [
        "github.com",
        "*.githubusercontent.com",
        "*.npmjs.org",
        "registry.yarnpkg.com",
        "pypi.org"
      ]
    }
  }
}

{
  "permissions": {
    "deny": [
      "Bash(rm -rf *)",
      "Bash(curl *)",
      "Bash(wget *)",
      "Bash(git push *)",
      "Bash(chmod 777 *)"
    ]
  }
}

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(./config/credentials.json)",
      "Read(**/*.pem)",
      "Read(**/*.key)"
    ]
  }
}

{
  "permissions": {
    "disableBypassPermissionsMode": "disable"
  }
}

---
name: Heavy Analysis
description: 대규모 분석을 격리 컨텍스트에서 실행
context: fork
agent: security-reviewer
---

# 분석 기술
이 기술은 포크된 독립 컨텍스트이며 지정된 서브에이전트(security-reviewer)에 의해 실행됩니다.

skill-name/
├── SKILL.md          # 필수. 지시 본체
├── scripts/          # 선택. 실행 가능한 코드
├── references/       # 선택. 보충 문서
└── assets/           # 선택. 템플릿

Command（명령）→ Claude가 실행
예: /code-review 85
     → commands/code-review.md 파일 + CLAUDE.md + rules 참조하면서 실행

Command（명령）→ Agent（실행자）→ Skills（기술 + 도메인 지식）
예: /code-review 85
     → agent-reviewer 에이전트 시작
        → 기술, 도메인지식, 언어별 체크리스트 스킬 프리로드
        → 리뷰어가 기술과 도메인 지식을 사용하여 리뷰 수행

.claude/rules/
├── coding-style.md      # 코딩 약관
├── testing.md           # 테스트 정책
├── api-design.md        # API 설계 규칙
└── security/            # 보안 규칙(하위 디렉토리도 가능)
    └── auth.md

┌──────────────┐
│   Developer  │
└──────┬───────┘
       │
       │ PR 생성
       ▼
┌──────────────┐
│   Reviewer   │
└──────┬───────┘
       │
       │ /code-review-feedback-rust
       │ (코드 수정 ❌, Before/After 코멘트를 Github에 남김)
       ▼
┌──────────────┐
│   Developer  │
└──────┬───────┘
       │
       │ /address-review-rust
       │ (지적 사항에 대한 코드 수정 + Github에 리뷰 반영)
       │
       │ /reply-review-rust
       │ (Github에 리뷰 코멘트 답변)
       ▼
┌──────────────┐
│   Reviewer   │
└──────┬───────┘
       │
       │ 재검토
       │
       ├───────────────┐
       │               │
       ▼               │
   [Aprove]            │
                       │
                  (추가 피드백)
                       │
                       ▼
                /code-review-feedback-rust
                       │
                       └─────── 반복

# 도메인 중심 진화형 코딩 스타일

## 1. 핵심 원칙 (Principles)

### 1.1 변화 용이성 우선
- 성능보다 **변경하기 쉬운 코드**를 우선한다
- 미래 요구사항을 추측하여 설계하지 않는다
- 추상화는 최소 3번의 반복 이후에 도입한다 (Rule of Three)

### 1.2 의도를 드러내는 코드
- 코드는 “무엇을 하는지”가 아니라 **왜 존재하는지**를 설명해야 한다
- 짧은 코드보다 **이해하기 쉬운 코드**를 선택한다
- 주석보다 코드 구조 개선을 우선한다

### 1.3 도메인 중심 설계
- 도메인 개념이 코드 구조를 결정해야 한다
- 유비쿼터스 언어를 코드 전반에 일관되게 사용한다
- 도메인 없이 범용 유틸리티를 먼저 만들지 않는다

### 1.4 점진적 진화
- 항상 작고 안전한 단위로 변경한다
- 한 번의 변경에는 하나의 의도만 담는다
- 모든 변경은 되돌릴 수 있어야 한다

### 1.5 구현하기 전에 생각할 것
- 불확실한것, 모호성이 있을 경우, 불문명한 것이 있을 경우 추측보다는 질문이나 설명을 요청하세요.
- 더 간단한 방식이 있을 경우 언급해 주세요.

---

## 2. 설계 규율 (Design Discipline)

### 2.1 구조
- 작고 조합 가능한 함수로 구성한다
- 함수는 하나의 책임만 가진다
- 조건문/중첩 깊이는 최대 2단계로 제한한다

### 2.2 도메인 모델
- 빈약한 도메인 모델(Anemic Model)을 지양한다
- 데이터와 행동을 함께 둔다
- 도메인 로직은 객체 내부에 캡슐화한다

### 2.3 추상화
- 중복 없이 추상화를 만들지 않는다
- 패턴이 드러난 이후에만 추상화한다
- 미래 확장을 위한 구조를 미리 만들지 않는다

### 2.4 제어 흐름
- 복잡한 표현보다 명확한 흐름을 선택한다
- 조건문은 의도를 드러내는 메서드로 치환한다
- Tell, Don’t Ask 원칙을 따른다

---

## 3. 리팩토링 철학

### 3.1 지속적인 리팩토링
- 리팩토링은 별도의 작업이 아니라 **개발 과정의 일부**
- 기능 추가 전, 필요하면 구조를 먼저 개선한다
- 항상 동작하는 상태를 유지한다

### 3.2 리팩토링 트리거
- 동일한 코드가 3번 이상 반복될 때
- 이름이 의도를 충분히 설명하지 못할 때
- 함수가 여러 책임을 가지기 시작할 때
- 도메인 개념이 코드에 드러나지 않을 때

---

## 4. 네이밍 규칙

### 4.1 기본 원칙
- 도메인 용어를 그대로 사용한다
- 축약보다 명확한 이름을 선택한다
- 구현 방식이 아니라 **의도**를 표현한다

### 4.2 금지
- `data`, `util`, `helper`, `manager` 같은 모호한 이름
- 불필요한 축약어
- 동일 개념에 대한 여러 이름 사용

---

## 5. 에지 케이스 & 경계 조건

### 5.1 기본 원칙
- 에지 케이스는 예외가 아니라 **도메인의 일부**로 취급한다
- 모든 경계 조건은 코드에 명시적으로 드러나야 한다
- 숨겨진 가정을 제거한다

### 5.2 모델링
- null / 없음 / 실패 상태를 명확한 타입이나 개념으로 표현한다
- invalid state는 가능한 한 타입 수준에서 제거한다
- 경계 조건을 조건문이 아닌 도메인 로직으로 표현한다

### 5.3 처리 방식
- 에러는 무시하지 않고 명확하게 전달하거나 처리한다
- fallback 로직은 반드시 의도를 드러낸다
- 임시 처리를 남기지 않는다

### 5.4 금지
- 침묵하는 실패
- 의미 없는 기본값
- 암묵적인 경계 처리

---

## 6. 테스트 철학

### 6.1 동작 기반 검증

구현이 아닌 동작을 테스트한다. 순수 리팩토링은 테스트를 깨뜨려서는 안 된다.
메서드 이름 변경, 반복문을 재귀로 교체 같은 내부 구현 변화에 테스트가 깨진다면, 동작이 아닌 구현을 잠그는 것이다.

### 6.2 시스템 경계에서만 모킹
내가 통제하고 소유하는 모든 것은 실제 구현을 사용하고, 통제 불가능한 것만 대체한다.
DB, 캐시, 내부 서비스는 실제 구현을 사용하되, 외부 결제 API나 OAuth 서버는 경계 밖이므로 모킹한다.

### 6.3 Classicist TDD 선호

Mockist 방식은 AI 기반 코드베이스에서 신뢰도가 빠르게 낮아진다.
AI가 구현을 리팩토링할 때마다 Mockist 테스트(상호작용 검증)는 깨지지만, Classicist 테스트(최종 상태 검증)는 사양을 만족하면 통과한다.

### 6.4 통합 테스트 우선

단위 테스트는 빠르지만, 유스케이스 하나를 실 DB로 검증하면 단위 테스트 여러 개를 대체한다.
단위 테스트는 복잡한 도메인 로직과 엣지 케이스에만 집중한다.

### 6.5 FIDT 원칙

테스트는 빠르고(Fast), 격리되고(Isolated), 결정적(Deterministic)이어야 한다.
하나라도 무너지면 전체 스위트의 신뢰도가 떨어진다.

### 6.6 품질 중심

의미 있는 소수의 테스트가 신뢰도 낮은 다수의 테스트보다 가치 있다.
단순 getter나 프레임워크 초기화 코드까지 테스트하면 실행 비용만 올라간다.

---

## 7. 보안 기본 원칙 (Security Principles)

### 7.1 기본 원칙
- 보안은 기능 이후가 아니라 **설계 단계에서 포함한다**
- 신뢰하지 않은 입력은 항상 검증한다
- 최소 권한 원칙(Principle of Least Privilege)을 따른다

### 7.2 입력 & 검증
- 모든 외부 입력은 반드시 검증한다
- 허용된 값(allowlist) 기반으로 처리한다
- 문자열 조합 대신 안전한 API를 사용한다

### 7.3 데이터 보호
- 민감 정보는 저장/로그에 노출하지 않는다
- 필요한 경우 반드시 암호화한다
- 비밀번호/토큰은 평문으로 다루지 않는다

### 7.4 에러 & 로그
- 내부 정보가 외부로 노출되지 않도록 한다
- 에러 메시지는 최소한의 정보만 포함한다
- 로그에는 민감 정보가 포함되지 않도록 한다

### 7.5 의존성 & 구성
- 신뢰할 수 있는 라이브러리만 사용한다
- 의존성은 최신 상태로 유지한다
- 보안 설정은 기본값에 의존하지 않는다

### 7.6 금지
- 사용자 입력을 그대로 실행
- 민감 정보 하드코딩
- 인증/인가 우회 로직
- 보안 검증 생략

---

## 8. 실행 규칙 (개발자 공통)

- 가독성을 최우선으로 한다
- 도메인을 명확히 모델링한다
- 변경하기 쉬운 구조를 유지한다
- 경계 조건을 명시적으로 처리한다
- 테스트로 검증한다
- 보안을 기본으로 고려한다

---

## 9. 안티 패턴

- 성급한 추상화
- 빈약한 도메인 모델
- 깊은 중첩 구조
- 암묵적 경계 처리
- 테스트 없는 핵심 로직
- 보안을 고려하지 않은 설계

---

## 10. 코드 리뷰 체크리스트

- 도메인 개념이 명확한가?
- 가독성이 충분한가?
- 변경이 쉬운가?
- 경계 조건이 명확히 처리되었는가?
- 테스트가 존재하는가?
- 보안 문제가 없는가?

---

---
name: code-review-feedback-rust
description: >
  /code-review-feedback-rust 커맨드로 실행되는 Rust 코드 리뷰 피드백 스킬.
  /code-review-rust와 동일한 분석(10개 카테고리)을 수행하지만, 소스 코드를 직접 수정하지 않고 GitHub PR에 리뷰 코멘트를 게시한다.
  PR 모드에서는 gh api로 인라인 코멘트·리뷰 본문을 PR에 직접 등록하고, 비PR 모드에서는 현재 브랜치의 PR을 자동 감지하거나 Markdown 리포트를 출력한다.
  모든 파라미터는 /code-review-rust와 동일하게 지원한다.
---

## 스킬 개요

이 스킬은 **`/code-review-feedback-rust` 커맨드가 입력될 때 자동으로 실행**된다. `/code-review-rust`와 동일한 10개 카테고리 분석을 수행하되, **소스 코드를 절대 수정하지 않고** 분석 결과를 GitHub PR 리뷰 코멘트로 게시한다.

**`/code-review-rust`와의 차이점:**

| 항목 | /code-review-rust | /code-review-feedback-rust |
|------|-------------------|---------------------------|
| 목적 | 코드 분석 + 직접 수정 | 코드 분석 + PR 코멘트 게시 |
| 소스 수정 | Before/After 제시 후 적용 | **절대 수정하지 않음** |
| 결과물 | 수정된 코드 + 커밋 | GitHub PR 리뷰 코멘트 |
| 주 사용자 | 코드 작성자 | 리뷰어 역할을 하는 사람 |

리뷰의 핵심 불변 조건:
- **코드 무수정** — 어떤 상황에서도 소스 파일을 변경하지 않는다
- **변경분만 분석** — `git diff`로 실제 변경 파일만 정확히 추출
- **인라인 코멘트 우선** — 가능하면 해당 파일·행에 직접 인라인으로 게시
- **게시 전 확인** — 코멘트 초안을 먼저 보여주고 인간 승인 후에만 게시
- **dry-run 지원** — `--dry-run` 옵션으로 게시 없이 초안만 확인

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📋  지적 목록 — 총 6건
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[A-RV-01] mimul | controller/tests/api_test.rs:13
  지적: unique_email() subsec_nanos 기반 — 병렬 테스트 시 충돌 가능, AtomicU64 권장

[A-RV-02] mimul | usecase/tests/user_usecase_integration_test.rs:23
  지적: unique_username() 동일 문제 — subsec_nanos → AtomicU64 권장

[A-RV-03] mimul | controller/tests/common/mod.rs:23
  지적: build_test_app() 매 호출마다 풀 생성+마이그레이션, OnceCell로 공유 권장

[A-RV-04] mimul | controller/tests/api_test.rs:34
  지적: create_user_and_login() create 응답 미검증 — 셋업 실패 시 원인 불명확

[A-RV-05] mimul | controller/tests/api_test.rs:18
  지적: body_json() unwrap에 설명 없어 실패 진단 어려움

[A-RV-06] mimul | controller/src/startup/mod.rs:37
  지적: build_router를 pub(crate)로 제한 가능

---
name: address-review-rust
description: >
  /address-review-rust 커맨드로 실행되는 리뷰 대응 스킬. 코드 리뷰 결과를 받은 사람이 각 지적 사항의 타당성을 판단하고 수정을 수행하는 데 Claude가 보조하는 스킬이다. 두 가지 모드를 지원한다:
    대화 모드 — 인수 없이 실행 시 직전 대화의 리뷰 내용을 자동 추출하여 대응한다.
    PR 모드   — PR 번호 지정 시 gh api로 해당 PR의 리뷰·인라인 코멘트를 가져와 대응한다.
  각 지적의 기술적 타당성과 프로젝트 정책 적합성을 독자적으로 평가하고, 타당한 지적만 Before/After로 수정하며 최종 요약을 출력한다.

## 스킬 개요

이 스킬은 **`/address-review-rust` 커맨드가 입력될 때 자동으로 실행**된다.
코드 리뷰를 받은 당사자가 리뷰 지적 사항을 처리할 때 Claude가 다음을 수행한다:

1. 리뷰 코멘트 수집 (대화 이력 또는 PR API)
2. 각 지적의 타당성 독립 평가
3. 타당한 지적만 수정 적용 (Before/After 제시 → 인간 확인)
4. 대응하지 않은 지적에 대한 근거 명시
5. 최종 요약 출력

**핵심 원칙:**
- **독립 판단** — 리뷰어의 지적을 맹목적으로 따르지 않고 기술적 타당성을 독자적으로 평가한다
- **근거 명시** — 대응하지 않을 경우 리뷰어가 납득할 수 있는 이유를 반드시 기재한다
- **안전한 수정** — 수정으로 새로운 문제가 발생하지 않는지 cargo test + clippy로 확인한다
- **인간 확인** — 각 수정 전 Before/After를 제시하고 승인 후에만 적용한다

## 커맨드 문법

/address-review-rust 42           PR #42의 리뷰·인라인 코멘트를 대상으로 대응 ← 권장
/address-review-rust              직전 대화의 리뷰 내용을 대상으로 대응 (같은 세션 전용)

---
name: reply-review-rust
description: >
  /reply-review-rust 커맨드로 실행되는 PR 리뷰 답장 스킬.
  /address-review-rust 로 리뷰 대응을 완료한 후, 각 리뷰 코멘트에 대응한 취지(또는 대응 불필요로 판단한 이유)를 회신하는 스킬이다.
  인수 없이 실행하면 직전 대화의 리뷰 대응 요약을 자동 추출하여 사용한다. PR 번호 또는 GitHub URL을 지정하면 해당 PR 코멘트에 답장한다. 답장 게시 전 반드시 회신 목록을 사용자에게 제시하고 승인을 받는다.
---

## 스킬 개요

이 스킬은 **`/reply-review-rust` 커맨드가 입력될 때 자동으로 실행**된다.

`/address-review-rust`로 리뷰 대응을 완료한 후, 각 PR 리뷰 코멘트에
대응 결과를 회신하는 스킬이다.

**전제 조건:**
- `/address-review-rust` 실행이 완료되어 있을 것
- 직전 대화에 리뷰 대응 요약(대응한 지적 / 대응 불필요 지적)이 포함되어 있을 것

**핵심 불변 조건:**
- **게시 전 승인 필수** — 회신 목록을 사용자에게 제시하고 명시적 승인 후에만 게시
- **중복 답장 금지** — 이미 답장된 코멘트는 건너뜀
- **코드 무수정** — 소스 파일을 절대 변경하지 않음
---

## 커맨드 문법

/reply-review-rust              직전 대화의 대응 요약 + PR 정보 자동 사용
/reply-review-rust 42           PR #42의 코멘트에 답장
/reply-review-rust https://github.com/{owner}/{repo}/pull/42   URL로 지정

## 셀프(자동) 병합 가이드라인

기준은 돌아갈 수 없는 결정(One-Way Door)과 돌아갈 수 있는 결정(Two-Way Door)으로 판단을 한다. 변경 사항들이 Two-Way Door일 경우 자동 병합을 하고 One-Way Door일 경우는 자동 병합을 하지 않고 인간 검토(확인)를 해야한다.

1. One-Way Door인 경우(revert해도 피해가 남는 경우)

- DB 스키마 마이그레이션 (컬럼 삭제 및 유형 변경에는 데이터 손실이 수반되며 프로덕션 적용 후 DDL 롤백도 어렵습니다)
- Row-Level Security (RLS) 정책
- 인증·인가(인증 바이패스나 세션 누설은 revert해도 피해가 남는다)
- 인프라(IaC)/CI/CD 배포 시스템 워크플로우
- AI 기반 설정, 릴리스 제어 및 종속성에 대한 Major 업데이트
- 기반(외부) 라이브러리 추가 및 교체(프레임워크, ORM, AI 기반, 인증 기반, 기타 오픈소스 등)
- 아키텍처 변경(모노 리포 구성 변경, 마이크로 아키텍처)
- 미들웨어 구성, 에러 핸들링 전략, 로깅 기반 등의 횡단적 관심사

2. Two-Way Door인 경우

- One-Way Door가 아닌 경우

~/.claude/
├── projects/<project-hash>/   
│   └── memory/                     # ① 프로젝트별 배움
│       │── MEMORY.md               # 메모리 인덱스
│       └── code-review-lessons.md  # 실패시(지적 사항들) 자동 기록
├── rules/                          # ② 범용 규칙(모든 프로젝트 공통)
│   └── failure-learning.md         # 반복되는 지적 사항을 자동 룰에 기록
└── CLAUDE.md                       # ③ 매번 로드되는 엔트리 포인트

# 실패시 자동 기록

태스크가 실패·실수였던 경우 아래사항들을 자동으로 실행할 것:

1. 실패의 원인을 간략하게 분석
2. 적절한 장소에 기록하기:
- 프로젝트별 실패 : ~/.claude/projects/<project-hash>/memory/ 아래 기록(코드 리뷰는 code-review-lessons.md 등 목적에 맞는 파일명).
- 범용적인 실패 패턴 : ~/.claude/rules/ 아래에 규칙 추가
3. 동일한 실패가 메모리에 두 번 이상 기록된 경우 규칙으로 승격

# 즉시 기록 트리거

다음 상황이 발생하면 **그 즉시** 해당 대화 중에 memory/에 기록한다 (세션 종료를 기다리지 않음):

- 컴파일 오류를 잘못된 코드로 인해 2회 이상 반복
- API 호출(`gh`, `curl` 등)이 4xx/5xx 오류 → 내 가정이 틀렸을 때
- 외부 라이브러리 API를 잘못 이해해서 컴파일 오류 또는 런타임 오류 발생
- 동일한 수정을 3회 이상 반복 (루프 감지)
- 코드 리뷰에서 지적받은 패턴이 발생했을 때

# 주의사항

**1. 기록하는 것**

- 리뷰어에서 지적한 코딩 패턴
- 두 번 이상 발생한 동종 오류
- 프로젝트별 제약(인코딩, API 사양, 라이브러리 버전별 API 차이 등)
- Claude 자신의 작업 실패 (잘못된 API 가정, 잘못된 문법 등)

**2. 기록하지 않는 것**

- 네트워크 장애와 같은 일시적인 오류
- 일시적으로 발생하는 환경 별 문제
- CLAUDE.md에 이미 작성된 내용

# 기록 포멧

### [간결한 제목] (YYYY-MM-DD)
- **상황**: 무엇을 시도했는가
- **실패**: 무엇이 잘못되었는가
- **정답**: 올바른 접근법

각 기록에는 **Why:** (실패 원인)와 **How to apply:** (적용 기준) 라인을 추가한다.

# 승격 기준

- 동일 프로젝트에서 2회 이상 : memory/에 기록 (이미 있으면 갱신)
- **다른 프로젝트에서도 동일 패턴 발생 : rules/로 즉시 승격** (프로젝트 카운트 무관)
- rules/로 승격 시 memory/의 해당 항목에 "→ rules/XXX.md로 승격" 메모 추가

# 프로세스

리뷰에서 지적 받기 / 컴파일·API 오류 반복 발생
↓
즉시 memory/ 에 교훈으로 기록 (대화 중 그 즉시)
↓
같은 패턴이 다른 프로젝트에서도 발생 → rules/ 로 승격
↓
모든 세션에서 자동 적용