Code Review & Team Refactor

프로젝트의 규칙/스킬/에이전트 설정을 먼저 파악하고, 그에 맞는 전문가 관점으로 리뷰합니다. 사용자가 개선 범위를 지정하면 Agent Team을 스폰하여 병렬로 수정합니다.

전체 흐름

Phase 1: 컨텍스트 탐색 → 전문가 패널 구성 → 리뷰 → 사용자 전달
  ── 사용자 검토 (개선 범위 지정) ──
Phase 2: 범위 확정 → TeamCreate → 병렬 개선 → 완료 보고

Phase 1: 코드 리뷰

Step 1. 프로젝트 컨텍스트 탐색

변경 사항을 보기 전에 프로젝트 설정을 파악합니다.

탐색 대상 (순서대로):

| 우선순위 | 경로 | 파악할 내용 | |----------|------|-------------| | 1 | CLAUDE.md, .claude/CLAUDE.md | 프로젝트 개요, 핵심 규칙, 컨벤션 | | 2 | .claude/settings.json | 허용 도구, 권한 설정 | | 3 | .claude/skills/*/SKILL.md (frontmatter만) | 프로젝트가 사용하는 스킬 목록 | | 4 | .claude/agents/*/AGENT.md (frontmatter만) | 등록된 에이전트 역할 | | 5 | 프로젝트 루트 설정 파일 | package.json, pyproject.toml, go.mod 등 → 언어/프레임워크 판별 | | 6 | lint/format 설정 | .eslintrc, ruff.toml, .prettierrc 등 → 코드 스타일 규칙 |

결과물: 프로젝트 프로파일 요약

프로젝트 프로파일:
- 언어/프레임워크: {감지 결과}
- 핵심 규칙: {CLAUDE.md에서 추출한 규칙들}
- 코드 스타일: {lint/format 설정 요약}
- 등록된 스킬: {스킬 목록}
- 등록된 에이전트: {에이전트 목록}

Step 2. 전문가 패널 구성

프로젝트 프로파일을 기반으로 리뷰에 참여할 전문가 관점을 동적으로 결정합니다.

전문가 패널 구성 가이드 참조.

기본 관점 (항상 포함):

프로젝트 규칙 준수 — CLAUDE.md, lint 설정 등 프로젝트 자체 규칙 위반 여부
정확성 — 로직 오류, 에러 처리, 엣지 케이스

조건부 관점 (프로파일에 따라 추가):

웹 프레임워크 감지 → 보안 관점 추가
DB/ORM 감지 → 데이터 계층 관점 추가
테스트 프레임워크 감지 → 테스트 커버리지 관점 추가
등등 (상세는 references 참조)

Step 3. 변경 사항 분석

다음 우선순위에 따라 diff 범위를 결정합니다.

3-1. Diff 범위 결정

| 우선순위 | 조건 | diff 범위 | |----------|------|-----------| | 1 | 사용자가 커밋/태그 지정 | git diff <ref>..HEAD | | 2 | 피처 브랜치 (비-기본 브랜치) | git diff $(git merge-base <base> HEAD)..HEAD | | 3 | Fallback | 사용자에게 질문 |

베이스 브랜치 자동 탐지 (Priority 2에서 사용):

# 존재하는 첫 번째 브랜치를 베이스로 사용
for base in origin/dev origin/develop origin/main; do
  git rev-parse --verify "$base" &>/dev/null && break
done

기본 브랜치 판별: dev, develop, main, master 중 하나면 기본 브랜치로 간주.

3-2. TICKET_ID 추출

git branch --show-current

브랜치명에서 TICKET_ID 패턴 추출:

feature/ABC-123-desc → ABC-123
fix/PROJ-456 → PROJ-456
ABC-123-some-desc → ABC-123
패턴: [A-Z]+-[0-9]+ (첫 매칭)
실패 시 → 사용자에게 질문

3-3. 변경 사항 수집

git diff {범위} --name-only    # 변경 파일 목록
git diff {범위}                 # 전체 diff
git log {범위} --oneline        # 커밋 히스토리 (컨텍스트 파악용)

Step 4. 리뷰 수행

각 전문가 관점에서 변경된 코드를 검토합니다.

리뷰 원칙:

프로젝트 컨텍스트 우선 — 일반론보다 이 프로젝트의 규칙/컨벤션 기준으로 판단
이슈 위치를 정확히 지정 (파일:라인)
왜 문제인지 근거 제시
개선 방향을 제안하되, 구체적 수정 코드는 Phase 2에서 처리

이슈 등급:

| 등급 | 기준 | |------|------| | CRITICAL | 보안 취약점, 데이터 손실, 시스템 장애 유발 | | MAJOR | 기능 오류, 프로젝트 핵심 규칙 위반, 심각한 성능 저하 | | MEDIUM | 코드 품질, 컨벤션 불일치, 유지보수 어려움 | | LOW | 사소한 개선, 스타일 |

Step 5. 리뷰 문서 저장 및 전달

경로: .ai/tasks/{TICKET_ID}/review.md 형식: 리뷰 문서 템플릿

기존 파일 있으면 review-01.md, review-02.md로 버전 증가.

사용자에게 전달:

📋 코드 리뷰 완료
📄 문서: .ai/tasks/{TICKET_ID}/review.md

프로젝트 컨텍스트: {언어}, {프레임워크}, {핵심 규칙 요약}
리뷰 관점: {적용된 전문가 목록}

| 등급 | 건수 |
|------|------|
| 🔴 CRITICAL | N |
| 🟠 MAJOR | N |
| 🟡 MEDIUM | N |
| 🟢 LOW | N |

주요 이슈:
1. src/auth.ts:45 — [보안] 사용자 입력 검증 누락
2. src/service.ts:120 — [프로젝트 규칙] CLAUDE.md의 에러 처리 규칙 미준수
...

개선을 진행하려면 범위를 지정해주세요.
예: "CRITICAL 전부", "1, 3번", "전부"

Phase 2: 팀 개선

사용자가 범위를 지정하면 Agent Team을 스폰합니다.

Step 1. 범위 확정 및 작업 그룹핑

대상 이슈를 파일 단위로 그룹핑:

같은 파일 / 의존 관계 파일 → 하나의 Task
독립 파일 → 별도 Task
최대 Worker 5명

Step 2. Team SPAWN

팀 스폰 상세 가이드 참조.

다음 절차를 순서대로 실행합니다.

2-1. 팀 생성

TeamCreate 도구를 호출합니다.

| 파라미터 | 값 | |----------|-----| | team_name | "review-{TICKET_ID}" | | description | "{TICKET_ID} 코드 리뷰 이슈 개선" |

2-2. 태스크 생성

이슈 그룹마다 TaskCreate 도구를 호출합니다. 모든 태스크를 동시에 생성합니다.

| 파라미터 | 값 | |----------|-----| | subject | "개선: {파일명} ({이슈 수}건)" | | description | 프로젝트 컨텍스트 + 담당 파일 + 수정할 이슈 목록 | | activeForm | "{파일명} 개선 중" |

2-3. Worker 스폰

이슈 그룹 수만큼 Task 도구를 호출하여 Worker를 스폰합니다. 모든 Worker를 동시에 스폰합니다.

| 파라미터 | 값 | |----------|-----| | subagent_type | "general-purpose" | | team_name | "review-{TICKET_ID}" | | name | "refactor-worker-{N}" (1부터 순번) | | description | "코드 개선 Worker {N}" | | mode | "bypassPermissions" | | prompt | Worker 프롬프트 (아래 참조) |

Worker 프롬프트에 반드시 포함할 내용:

프로젝트 규칙/컨벤션 (CLAUDE.md에서 추출한 핵심 규칙)
담당 파일 및 이슈 목록 (리뷰 문서에서 해당 그룹의 이슈 전체)
이슈별 개선 방향
작업 절차 지시 (TaskList → TaskUpdate in_progress → 파일 수정 → SendMessage로 리더에게 보고 → TaskUpdate completed)
담당 파일만 수정하라는 규칙

Worker 프롬프트 상세 템플릿은 팀 스폰 상세 가이드를 참조합니다.

2-4. 태스크 할당

Worker가 스폰되면 TaskUpdate 도구로 각 Worker에게 Task를 할당합니다.

| 파라미터 | 값 | |----------|-----| | taskId | 해당 태스크 ID | | owner | "refactor-worker-{N}" (Worker name과 동일) |

2-5. 완료 대기

Worker들이 작업을 완료하면 SendMessage로 결과를 보고합니다. 자동으로 수신됩니다. 모든 Worker의 보고가 도착할 때까지 대기합니다.

Step 3. 정리 및 보고

3-1. Worker 종료

모든 Worker에게 SendMessage 도구로 종료를 요청합니다.

| 파라미터 | 값 | |----------|-----| | type | "shutdown_request" | | recipient | "refactor-worker-{N}" | | content | "작업 완료. 종료합니다." |

3-2. 팀 삭제

모든 Worker가 종료된 후 TeamDelete 도구를 호출합니다.

3-3. 완료 보고

✅ 개선 완료

수정된 이슈: N/M건
수정된 파일:
- src/auth.ts: 2건 (입력 검증 추가, 에러 처리 규칙 적용)
- ...

팀 정리 완료. 커밋하시려면 말씀해주세요.