~/.claude

디렉토리 구조

~/.claude/
├── CLAUDE.md                    # 전역 코딩 행동 규칙│
├── agents/                      # 서브에이전트 정의 (Task 도구로 호출)
│   └── refactor/
│       ├── pipeline/            #   파이프라인 에이전트 (조율 계층)
│       │   ├── analyzer.md      #     L1~L5 이슈 탐지
│       │   ├── planner.md       #     의존성·위험도 기반 실행 계획
│       │   ├── executor.md      #     전문가 위임 및 실행
│       │   ├── reviewer.md      #     tsc/eslint/test 검증
│       │   └── reporter.md      #     서사 중심 보고서 생성
│       └── specialists/         #   전문가 에이전트 (실행 계층)
│           ├── L1-data.md       #     데이터·상태 수준
│           ├── L2-logic.md      #     명령문·로직 수준
│           ├── L3-function.md   #     함수·훅 수준
│           ├── L4-structure.md  #     컴포넌트·모듈 구조
│           └── L5-architecture.md #   시스템·아키텍처 수준
│
├── commands/                    # 사용자 호출 가능 커맨드 (슬래시 커맨드)
│   ├── refactor/
│   │   └── refactor-team.md     #   리팩토링 팀 오케스트레이터
│
.
.
.

핵심 개념: 3계층 아키텍처

┌─────────────────────────────────────────────┐
│          commands/ (오케스트레이션)             │
│  사용자가 슬래시 커맨드로 호출하는 진입점             │
│  예: /refactor-team, /plan, /e2e             │
└──────────────────┬──────────────────────────┘
                   │ Task 도구로 호출
┌──────────────────▼──────────────────────────┐
│          agents/pipeline/ (조율)             │
│  분석→계획→실행→검증→보고 흐름을 제어               │
└──────────────────┬──────────────────────────┘
                   │ Task 도구로 호출
┌──────────────────▼──────────────────────────┐
│        agents/specialists/ (실행)            │
│  L1~L5 각 추상화 수준의 전문 리팩토링 수행           │
└─────────────────────────────────────────────┘

commands: "무엇을 할지" 정의. 사용자와의 접점.
agents/pipeline: "어떤 순서로 할지" 조율. 에이전트 간 데이터 전달.
agents/specialists: "어떻게 할지" 실행. 레벨별 패턴과 규칙.

리팩토링 팀 상세

설계 배경

Code Complete의 리팩터링 체크리스트가 출발점이다. 리팩터링을 추상화 수준별로 계층화하는 관점에서, OOP 용어를 React + TypeScript 프론트엔드 생태계로 번역했다.

수준	원문 (OOP)	프론트엔드 대응	위험도
L1	데이터	변수명, 상수, 타입, 상태	safe
L2	명령문	조건문, 반복문, 널 처리	safe
L3	루틴	함수, 훅 추출/인라인	safe~moderate
L4	클래스 구현/인터페이스	컴포넌트 구조, 상태 이동, Prop Drilling	moderate
L5	시스템	의존성, 타입 스키마, Error Boundary	risky

실행 흐름

/refactor-team <경로>
    │
    ▼
Phase 0: git checkout -b refactor/<scope>
    │
    ▼
Phase 1: Analyzer ─→ 이슈 JSON (L1~L5 분류)
    │
    ▼
Phase 2: Planner ─→ 실행 계획 JSON
    │                  ↓
    │            ⏸️ 사용자 승인
    ▼
Phase 3: 각 Step 반복
    │
    │  ┌──────────────────────────────┐
    │  │ Executor → Specialist(L1~L5) │
    │  │          ↓                   │
    │  │      Reviewer (검증)          │
    │  │       ╱          ╲           │
    │  │   ✅ PASS      ❌ FAIL       │
    │  │   → commit     → 1회 재시도    │
    │  │                → 2회 실패: 스킵 │
    │  └──────────────────────────────┘
    │
    ▼
Phase 4: Reporter ─→ 서사 보고서
    │                  ↓
    │            ⏸️ 머지 확인
    ▼
완료

안전 장치

장치	설명
사용자 게이트 2곳	Phase 2 계획 승인, Phase 4 머지 확인
Step 단위 커밋	1 step = 1 commit, 개별 롤백 가능
자동 검증	매 step마다 tsc + eslint + test
실패 허용	2회 연속 실패 시 롤백 + 스킵, 전체 중단 안 함
L1→L5 순서	안전한 변경부터 시작, 이전 성과 보존
의존성 기반 정렬	leaf 파일부터 처리, 순환 충돌 방지