aiwf/docs/guides/ai-personas-guide-ko.md

AI Workflow Framework for Claude Code with multi-language support (Korean/English)

[Read in English](ai-personas-guide.md)

# AI 페르소나 사용 가이드

## 개요

AIWF의 AI 페르소나 시스템은 개발 작업의 특성에 맞춰 Claude Code의 행동 패턴을 최적화하는 기능입니다. 5개의 전문화된 페르소나를 통해 각 작업에 가장 적합한 AI 어시스턴트를 활용할 수 있습니다.

## 페르소나 유형

### 1. Architect (아키텍트)
**목적**: 시스템 설계 및 아키텍처 결정

**특징**:
- 큰 그림과 시스템 전체 구조에 집중
- 확장성과 유지보수성 우선 고려
- 디자인 패턴과 아키텍처 원칙 적용
- 기술 스택 선택과 통합 전략 수립

**사용 시나리오**:
- 새로운 기능의 설계 단계
- 시스템 리팩토링 계획
- 기술 스택 결정
- 모듈 간 인터페이스 설계

**명령어**:
```bash
/project:aiwf:ai_persona:architect
# 또는 한국어
/프로젝트:aiwf:ai_페르소나:아키텍트
```

### 2. Debugger (디버거)
**목적**: 버그 찾기 및 문제 해결

**특징**:
- 상세한 코드 분석과 오류 추적
- 단계별 실행 흐름 검증
- 엣지 케이스와 예외 상황 고려
- 성능 병목 현상 식별

**사용 시나리오**:
- 버그 재현 및 원인 분석
- 성능 문제 해결
- 메모리 누수 추적
- 예외 처리 개선

**명령어**:
```bash
/project:aiwf:ai_persona:debugger
# 또는 한국어
/프로젝트:aiwf:ai_페르소나:디버거
```

### 3. Reviewer (리뷰어)
**목적**: 코드 품질 검토 및 개선

**특징**:
- 코딩 표준 준수 검증
- 보안 취약점 식별
- 최적화 기회 발견
- 가독성과 유지보수성 평가

**사용 시나리오**:
- PR 리뷰 준비
- 코드 품질 개선
- 보안 감사
- 리팩토링 제안

**명령어**:
```bash
/project:aiwf:ai_persona:reviewer
# 또는 한국어
/프로젝트:aiwf:ai_페르소나:리뷰어
```

### 4. Documenter (문서화 전문가)
**목적**: 문서 작성 및 관리

**특징**:
- 명확하고 이해하기 쉬운 설명
- API 문서 자동 생성
- 사용 예시와 튜토리얼 작성
- 다국어 문서 지원

**사용 시나리오**:
- README 작성
- API 문서화
- 사용자 가이드 작성
- 기술 사양서 작성

**명령어**:
```bash
/project:aiwf:ai_persona:documenter
# 또는 한국어
/프로젝트:aiwf:ai_페르소나:문서화전문가
```

### 5. Optimizer (최적화 전문가)
**목적**: 성능 최적화 및 효율성 개선

**특징**:
- 알고리즘 복잡도 분석
- 메모리 사용량 최적화
- 실행 시간 단축
- 리소스 효율성 개선

**사용 시나리오**:
- 성능 병목 지점 개선
- 알고리즘 최적화
- 데이터베이스 쿼리 개선
- 메모리 사용량 감소

**명령어**:
```bash
/project:aiwf:ai_persona:optimizer
# 또는 한국어
/프로젝트:aiwf:ai_페르소나:최적화전문가
```

## 페르소나 전환 방법

### 기본 사용법
1. 작업 시작 전 적절한 페르소나 선택
2. 명령어 입력으로 페르소나 활성화
3. 작업 수행
4. 필요시 다른 페르소나로 전환

### 예시 워크플로우
```bash
# 1. 새 기능 설계
/project:aiwf:ai_persona:architect
"새로운 사용자 인증 시스템을 설계해주세요"

# 2. 구현 후 버그 발견
/project:aiwf:ai_persona:debugger
"로그인 시 세션이 유지되지 않는 문제를 해결해주세요"

# 3. 코드 리뷰
/project:aiwf:ai_persona:reviewer
"구현한 인증 시스템 코드를 리뷰해주세요"

# 4. 문서 작성
/project:aiwf:ai_persona:documenter
"인증 API 문서를 작성해주세요"
```

## 페르소나별 컨텍스트 규칙

각 페르소나는 고유한 컨텍스트 처리 규칙을 가지고 있습니다:

### Architect 컨텍스트
- **우선순위**: 시스템 설계 문서, 아키텍처 다이어그램
- **포커스**: 인터페이스, 모듈 구조, 의존성
- **제외**: 구현 세부사항, 임시 코드

### Debugger 컨텍스트
- **우선순위**: 오류 로그, 스택 트레이스, 테스트 결과
- **포커스**: 실행 흐름, 변수 상태, 조건문
- **제외**: 문서, 주석, 스타일 관련 코드

### Reviewer 컨텍스트
- **우선순위**: 변경된 코드, 커밋 히스토리
- **포커스**: 코딩 표준, 보안 패턴, 성능 영향
- **제외**: 테스트 데이터, 빌드 파일

### Documenter 컨텍스트
- **우선순위**: 공개 API, 사용 예시, README
- **포커스**: 사용자 관점, 명확성, 완전성
- **제외**: 내부 구현, 디버그 코드

### Optimizer 컨텍스트
- **우선순위**: 성능 측정 결과, 프로파일링 데이터
- **포커스**: 시간 복잡도, 공간 복잡도, 리소스 사용
- **제외**: 문서, UI 코드, 테스트 코드

## 모범 사례

### 1. 작업에 맞는 페르소나 선택
- 작업의 성격을 고려하여 가장 적합한 페르소나 선택
- 한 작업에 여러 페르소나가 필요한 경우 순차적으로 전환

### 2. 페르소나 전환 타이밍
- 작업 단계가 바뀔 때 적절한 페르소나로 전환
- 같은 유형의 작업은 동일한 페르소나로 일관성 유지

### 3. 컨텍스트 관리
- 페르소나 전환 시 이전 작업 결과를 명확히 전달
- 각 페르소나의 강점을 활용한 작업 분담

### 4. 협업 시나리오
```bash
# 팀 프로젝트에서의 페르소나 활용
1. Architect: 전체 시스템 설계
2. Developer: 기능 구현 (기본 모드)
3. Debugger: 통합 테스트 및 버그 수정
4. Reviewer: 코드 리뷰 및 개선
5. Documenter: 최종 문서화
```

## 문제 해결

### 페르소나가 예상대로 작동하지 않을 때
1. 명령어가 정확히 입력되었는지 확인
2. 현재 프로젝트 컨텍스트가 AIWF인지 확인
3. 페르소나 전환 후 2-3초 대기
4. 문제 지속 시 기본 모드로 리셋 후 재시도

### 성능 저하
- 복잡한 작업 시 페르소나 전환 최소화
- 대용량 코드베이스에서는 관련 파일만 포함
- 필요 없는 컨텍스트는 제외 설정 활용

### 컨텍스트 충돌
- 페르소나별 컨텍스트 규칙 확인
- 충돌하는 정보는 명시적으로 우선순위 지정
- 필요시 수동으로 컨텍스트 정리

## 고급 활용법

### 1. 페르소나 체인
여러 페르소나를 연속적으로 활용하여 복잡한 작업 수행:
```bash
Architect → Developer → Debugger → Optimizer → Documenter
```

### 2. 페르소나 커스터마이징
프로젝트별 특수 요구사항에 맞춰 페르소나 동작 조정 가능
(향후 업데이트 예정)

### 3. 팀 워크플로우 통합
Git 브랜치나 PR 상태에 따라 자동 페르소나 전환
(Feature-Git 연동 기능과 함께 사용)

## 결론

AI 페르소나 시스템은 개발 작업의 효율성과 품질을 크게 향상시킬 수 있는 강력한 도구입니다. 각 페르소나의 특성을 이해하고 적절히 활용하면, Claude Code와의 협업이 더욱 생산적이고 효과적이 됩니다.

지속적인 사용과 피드백을 통해 각 프로젝트에 최적화된 페르소나 활용 전략을 개발하시기 바랍니다.