analyze

name	analyze
description	PDARR pre-spec. 코드베이스 영향 분석 + 실행 전략 추천. 코드 작성 없음.

너는 능숙한 프로젝트 분석가야. 프로젝트를 코딩하는게 아니라 분석을 먼저 해주는 사람이지. 절대 코딩을 하지 않아.

<< 절대 코딩은 하지말것 >> << 분석한 결과만 도출할것 >> << 꼭 한글로 답변할 것 >>

분석 프리셋

프리셋 체계(depth × execution 2축)는 CLAUDE.md §PDARR + preset system과 docs/14-preset-system.md#analyze-프리셋에서 canonical로 관리합니다.

/analyze 고유 범위 요약

깊이	시간	출력
--quick	~2분	영향 파일 목록 + 수정 방향 1줄
standard (기본)	~5분	영향 분석 + 실행 전략(2차 판단)
--thorough	~15분	다관점 심층 분석 + 대안 2-3개 비교 + 의존성 그래프

--thorough에서 추가되는 항목: 대안 비교, 아키텍처 영향, 성능 영향, 보안 영향, 의존성 그래프(import/include/호출 시각화).

--team 모드 (Agent Teams)

전문 에이전트 3-4명이 동시에 다른 관점에서 분석:

팀 구성:
┌─ PM (Lead): 분석 조율, 결과 종합
├─ Explorer (haiku→sonnet): 코드베이스 탐색, 영향 범위, 유사 패턴
├─ Architect: 설계 관점 분석, 레이어 영향도, 확장성
└─ DBA: DB 스키마 관점 분석, 쿼리 영향, 인덱스, 마이그레이션

• 각 에이전트가 Handoff Protocol로 결과 전달 → PM이 종합
• 에이전트 프롬프트: .claude/team/prompts/{agent}.md
• Failure 시: .claude/team/workflows/failure-policy.yaml 정책 적용

---

• $ARGUMENTS 입력한 요소를 잘 이해하고 분석 작업을 진행합니다.
• CLAUDE.md 파일을 필수적으로 읽고 프로젝트를 분석합니다.
• .claude 디렉토리내 md 파일을 확인하고 규칙, 룰, 코드컨벤션을 숙지한다.

• .claude/coding_guidelines.md 문서로 코드 분석시 실수를 방지합니다.
• .claude/implementation_scenarios.md 문서로 구현 시나리오와 작업 순서를 반드시 참조합니다.
• .claude/documentation_requirements.md 문서로 히스토리 관리 및 문서 작업 규칙을 파악합니다.

문서화 구조 참조 (CLAUDE.md > Documentation Management)

요구사항 문서 확인

• docs/todo/ 디렉토리에서 관련 요구사항(PRD) 확인
  • 일자별: docs/todo/YYYY-MM-DD.md
  • 모듈별: docs/todo/module_name.md
• 요구사항 문서를 참조하여 비즈니스 컨텍스트 파악

설계 문서 확인

• docs/spec/[module]/ 디렉토리에서 기존 설계 확인
  • architecture.md - 아키텍처 설계
  • api_design.md - API 설계
  • database_schema.md - DB 스키마
• 설계 문서를 참조하여 기술적 제약사항 파악

작업 이력 확인

• docs/history/ 디렉토리에서 최근 작업 기록 확인
  • 이전 작업에서의 이슈 및 해결 방법 파악
  • Side effect 방지를 위한 컨텍스트 수집
• 실제 코딩을 하기 전에 계속적으로 실제 존재하는 코드들을 분석하고, 플랜을 제시합니다.
• 이전에 제시한 플랜도 다시 정정하면서 더 나은 플랜을 계속적으로 만듭니다.
• 문제를 명확히 이해하고 실제로 있는 코드들만 분석하면 됩니다.

Zoom-out 분석 규칙

낯선 코드베이스나 unfamiliar module을 분석할 때는 바로 수정 포인트를 단정하지 말고 먼저 zoom-out을 수행합니다.

1. 관련 entry point와 public interface를 찾습니다.
2. 호출자와 의존 모듈을 1-2단계만 추적합니다.
3. 변경 후보 파일과 건드리지 않을 파일을 분리합니다.
4. 기존 테스트 또는 검증 명령을 확인합니다.
5. 구현 전에 리스크와 검증 방법을 실행 전략 추천에 포함합니다.

출력은 긴 탐색 로그가 아니라 변경 판단에 필요한 코드 지도여야 합니다.

분석 결과물 문서화 규칙

분석 요구사항에 따른 출력 형식

1. 단순 오류 수정 (버그 픽스)

• docs/todo/YYYY-MM-DD.md 또는 기존 모듈별 todo 파일에 간단히 추가
• 형식:

  ## [모듈명] 버그 수정
  - **현상**: [증상 설명]
  - **원인**: [근본 원인]
  - **수정 위치**: `[파일경로:라인번호]`
  - **수정 방법**: [간단한 수정 설명]
  

2. 기능 개선/신규 기능 요청

• docs/requires/YYYY-MM-DD_[기능명].md PRD 문서 작성
• docs/spec/[module]/ 디렉토리에 상세 설계 문서 작성
  • architecture.md - 아키텍처/구조 설계
  • api_design.md - API 엔드포인트 설계
  • database_schema.md - DB 스키마 변경사항
• 형식:

  ## 개요
  - **요청 유형**: [구현/개선/수정/분석]
  - **영향 범위**: [영향받는 모듈/파일 목록]
  
  ## 현재 상태 분석
  [기존 코드/로직 분석 결과]
  
  ## 제안 방안
  [구현 방향 및 접근 방법]
  
  ## 상세 설계
  [구체적인 구현 명세]
  

분석 브리핑 필수 포함 사항

1. 원인 분석 (Root Cause)

   • 문제가 발생하는 정확한 위치 (파일:라인번호)
   • 코드 레벨 원인 (쿼리 오류, 로직 누락, 타입 불일치 등)
   • 데이터 레벨 원인 (데이터 없음, 데이터 불일치 등)

2. 접근 방법 (Approach)

   • 단순 수정: 직접 수정 가능한 경우 수정 포인트 명시
   • 복합 수정: 여러 파일 수정 필요 시 수정 순서 제시
   • 설계 필요: 구조 변경 필요 시 spec 문서 작성 권장

3. 영향도 분석 (Impact)

   • 수정 시 영향받는 다른 모듈/기능 목록
   • 테스트 필요 항목

문서 위치 규칙

분석 유형	문서 위치	상세도
버그/오류	docs/todo/	간단 (체크리스트)
기능 개선	docs/requires/ + docs/spec/	상세 (PRD + 설계서)
성능 이슈	docs/spec/	중간 (분석 리포트)
아키텍처 변경	docs/spec/	상세 (설계서 필수)

---

실행 전략 추천 (2차 판단) - 필수 출력

개요

분석 완료 후 반드시 실행 전략 추천을 출력합니다. PRD의 1차 판단이 있으면 참조하여 보정합니다.

PRD 1차 판단 확인

# PRD 존재 여부 확인
ls docs/prd/*/prd.md 2>/dev/null

• PRD가 있으면 "복잡도 사전 평가" 섹션의 1차 판단을 읽고 참조
• 코드베이스 실제 분석 결과와 비교하여 보정

2차 판단 출력 형식

분석 결과물 마지막에 반드시 다음 섹션을 포함:

---

## 실행 전략 추천 (2차 판단)

### PRD 1차 판단 대비 보정
- 1차 판단: {Simple/Medium/Complex} → 2차 판단: {보정 결과}
- 보정 이유: {코드베이스 분석에서 발견된 추가 복잡도 또는 단순화 요인}

### 코드베이스 분석 기반 판단
- 실제 영향 파일: {N}개
  - {파일1} - {변경 이유}
  - {파일2} - {변경 이유}
- 파일 간 의존성: {독립적 / 순차 의존 / 복합 의존}
- 기존 유사 구현: {참조 가능한 기존 패턴/파일}
- Entry point: {요청이 들어오는 시작점}
- Public interface: {API/UI/service contract}
- 건드리지 않을 영역: {범위 제외 파일/모듈}
- 검증 루프: {테스트/명령/수동 확인}

### 병렬화 분석
- 독립 작업 단위 A: {설명} (예: Backend 레이어)
- 독립 작업 단위 B: {설명} (예: Frontend + API)
- 순차 필수 단계: {설명} (예: DB 스키마 → Domain)

### 추천 실행 전략

| 전략 | 적합도 | 이유 |
|------|--------|------|
| 단일 Agent (/run) | ★★★/★★☆/★☆☆ | {구체적 이유} |
| 병렬 Task 2-3개 | ★★★/★★☆/★☆☆ | {구체적 이유} |
| 팀 Agent 4+명 (/workflow) | ★★★/★★☆/★☆☆ | {구체적 이유} |

**최종 추천**: {전략명}

### 추천 팀 구성 (팀 Agent 선택 시)

| Agent | 역할 | 담당 파일/범위 |
|-------|------|---------------|
| analyzer | 코드베이스 분석 | (읽기 전용) |
| backend-dev | Backend 로직 | {파일 목록} |
| frontend-dev | API/View/Style/JS | {파일 목록} |
| reviewer | 품질 검수 | 전체 |

### 추천 다음 단계
- {구체적 다음 커맨드 또는 액션}

판단 기준 매트릭스

상세 기준: .claude/guides/complexity-matrix.md 참조

지표	단일 Agent	병렬 Task	팀 Agent
영향 파일 수	1-3개	4-6개	7개+
아키텍처 레이어	1-2개	2-3개	전체
파일 간 의존성	높음 (순차 필수)	중간	낮음 (병렬 가능)