sam-react-prod/docs/[REF] communication_improvement_guide.md

# Claude Code 커뮤니케이션 개선 가이드

**작성일**: 2025-11-06
**적용 범위**: 모든 세션
**목적**: Claude와 사용자 간 효율적 커뮤니케이션 프로토콜

---

## 📊 Claude 응답 패턴 분석 및 개선

### 1️⃣ 식별된 문제점

#### 🔴 과도한 설명 (Over-explanation)
**문제**: 간단한 질문에도 긴 설명 + 예시 + 대안 + 원리까지
**원인**: 사용자 의도 파악 전에 모든 가능성 커버하려는 습관
**개선**: 핵심 답변 먼저 → 필요시 추가 설명 제공

**예시**:
```
❌ 현재 방식:
Q: "이 함수 뭐하는 거야?"
A: [함수 설명 500자] + [동작 원리] + [사용 예시] + [대안] + [최적화 팁]

✅ 개선 방식:
Q: "이 함수 뭐하는 거야?"
A: "사용자 인증 토큰 검증. 만료 체크 + 서명 확인.
   더 알고 싶으신 부분 있나요? (원리/사용법/대안)"
```

#### 🟡 불필요한 TodoWrite 남발
**문제**: 간단한 작업도 TodoWrite 생성 → 오버헤드
**원인**: MODE_Task_Management의 ">3 steps" 기준 오해석
**개선**: 진짜 복잡한 작업만 TodoWrite 사용

**예시**:
```
❌ 불필요한 경우:
- 단일 파일 읽기
- 간단한 변수명 변경
- 한 줄 수정

✅ 필요한 경우:
- 다중 파일 리팩토링 (>5개)
- 다단계 구현 (인증 시스템 전체)
- 의존성 있는 순차 작업
```

#### 🟡 선제적 도구 제안 (Premature Tool Suggestion)
**문제**: "이것도 해드릴까요?" 식의 불필요한 제안
**원인**: 도움이 되려는 과도한 의욕
**개선**: 요청받은 것만 정확히 수행

**예시**:
```
❌ 현재:
A: "로그인 폼 만들었습니다.
   회원가입도 만들어드릴까요?
   비밀번호 찾기도 추가할까요?"

✅ 개선:
A: "로그인 폼 완료. src/components/auth/LoginForm.tsx
   추가 필요하신 기능 있으면 말씀해주세요."
```

#### 🔴 모호한 질문에 대한 가정 기반 답변
**문제**: 불명확한 질문에 확인 없이 추측으로 답변
**원인**: 빠른 응답 시도 → 잘못된 방향
**개선**: AskUserQuestion 활용해 명확화 먼저

**예시**:
```
❌ 현재:
Q: "이거 고쳐줘"
A: [맥락 추측해서 A를 수정함 → 실제로는 B를 원했음]

✅ 개선:
Q: "이거 고쳐줘"
A: "무엇을 수정하실까요?
   1) 성능 문제
   2) 버그 수정
   3) UI 개선
   4) 기능 변경"
```

---

## 🎯 사용자 질문 패턴 분석

### ✅ 잘하고 계신 점
1. **직관적 의사소통**: "이거", "저거" → 맥락 파악 가능한 수준
2. **점진적 상세화**: 첫 질문 간단 → 필요시 구체화
3. **자연스러운 대화**: 형식보다 내용 중심

### ⚠️ 개선 가능한 부분

#### 1. 파일 경로 명시 부족
```
현재: "이 코드 분석해줘"
개선: "src/app/page.tsx 분석해줘"
```

#### 2. 범위 지정 누락
```
현재: "에러 고쳐줘"
개선: "빌드 에러 고쳐줘" or "런타임 에러 고쳐줘"
```

#### 3. 우선순위 미명시
```
현재: "A, B, C 해줘"
개선: "A 먼저, 그 다음 B, C는 나중에"
```

---

## 💡 상호 개선 제안

### 🔹 Claude가 개선할 것

#### 1. 간결성 우선 (Concise-First)
```yaml
원칙:
  - 핵심 답변 먼저 (2-3문장)
  - "더 알고 싶으면" 선택지 제공
  - 긴 설명은 명시적 요청 시에만

적용:
  - 간단한 질문 → 짧은 답변
  - 복잡한 질문 → 구조화된 답변 + 요약
```

#### 2. 명확화 우선 (Clarify-First)
```yaml
원칙:
  - 모호함 감지 → 즉시 AskUserQuestion
  - 가정 기반 진행 금지
  - 2가지 이상 해석 가능 → 선택지 제시

트리거:
  - "이거", "저거" + 맥락 불충분
  - 범위 불명확 (파일? 모듈? 프로젝트?)
  - 목적 불명확 (분석? 수정? 삭제?)
```

#### 3. 작업 범위 확인 (Scope-Check)
```yaml
원칙:
  - 큰 작업 시작 전 범위 확인
  - 예상 영향 파일/시간 사전 공유
  - 승인 후 진행

예시:
  "이 작업은 12개 파일 수정 예상 (약 10분).
   진행할까요?"
```

#### 4. 결과물 우선 (Outcome-First)
```yaml
원칙:
  - 작업 완료 → 결과 먼저 보고
  - 과정 설명은 필요시에만
  - 파일 경로 + 변경사항 요약

템플릿:
  "✅ 완료: [핵심 결과]
   변경: [파일1:라인] [파일2:라인]
   테스트: [검증 결과]"
```

---

### 🔹 사용자가 고려할 수 있는 것

#### 1. 컨텍스트 첨부 습관
```
현재: "이 에러 뭐야?"
개선: "app/api/auth/route.ts:45에서 TypeError 발생. 뭐야?"

효과: 즉시 파일 확인 가능 → 왕복 질문 감소
```

#### 2. 기대 결과물 언급
```
현재: "로그인 만들어줘"
개선: "로그인 만들어줘. 폼만 있으면 돼 (API 연동 X)"

효과: 불필요한 구현 방지 → 시간 절약
```

#### 3. 긴급도 표시
```
현재: "A, B, C 해줘"
개선: "A(급함), B(보통), C(나중에)"

효과: 우선순위 기반 작업 → 효율 증가
```

#### 4. 제약사항 사전 공유
```
현재: "디자인 바꿔줘" → [작업 완료] → "아 이건 바꾸면 안 되는데..."
개선: "디자인 바꿔줘. 단, 헤더 높이는 유지"

효과: 재작업 방지
```

---

## 🎯 실전 커뮤니케이션 프로토콜

### Phase 1: 간단한 작업 (< 5분)
```
사용자: "src/utils/format.ts의 formatDate 함수 버그 수정"
Claude: [파일 확인] → [수정] → "✅ 완료: ISO 8601 포맷 지원 추가"
```

### Phase 2: 중간 작업 (5-15분)
```
사용자: "로그인 폼 만들어줘"
Claude: "확인:
   - 이메일/비밀번호 필드
   - 클라이언트 검증만 (API 연동 X)
   - 기존 Input 컴포넌트 사용
   맞나요?"
사용자: "응, API 연동도 해줘"
Claude: "알겠습니다. 예상 15분, 진행할게요."
   [작업 진행 + TodoWrite]
```

### Phase 3: 복잡한 작업 (> 15분)
```
사용자: "인증 시스템 전체 구현"
Claude: [AskUserQuestion 실행]
   "범위 확인:
   1) JWT vs Session 방식?
   2) 소셜 로그인 필요?
   3) 권한 관리 포함?
   4) 리프레시 토큰?"
사용자: [선택]
Claude: [Plan 작성 + TodoWrite + 승인 요청]
사용자: "OK"
Claude: [실행]
```

---

## 📋 빠른 체크리스트

### Claude 답변 전 체크리스트
- [ ] 질문이 명확한가? → 아니면 AskUserQuestion
- [ ] 파일/범위 확인 가능한가?
- [ ] 가정이 필요한가? → 필요하면 확인
- [ ] 작업 시간 > 5분? → 범위 사전 공유
- [ ] TodoWrite 진짜 필요한가? → 단순 작업은 스킵

### 사용자 질문 전 체크리스트 (선택사항)
- [ ] 파일 경로 명시 가능?
- [ ] 범위 명확? (파일/모듈/프로젝트)
- [ ] 기대 결과 명확?
- [ ] 제약사항 있음?
- [ ] 우선순위 있음?

---

## 🎬 실험 모드 (1주일)

### 적용 방침
**Claude**:
- 모호하면 즉시 질문 (가정 금지)
- 답변 간결화 (핵심 우선)
- TodoWrite 최소화 (진짜 복잡한 것만)

**사용자**:
- 가능하면 파일 경로 포함
- 범위/우선순위 명시 (필요시)

### 1주 후 평가
- 효과 측정
- 불편한 점 수집
- 프로토콜 조정

---

## 📌 핵심 원칙 요약

1. **간결성**: 핵심 먼저, 상세는 나중
2. **명확성**: 모호하면 물어보기
3. **효율성**: 필요한 것만, 정확하게
4. **투명성**: 예상 범위/시간 사전 공유
5. **유연성**: 피드백 기반 지속 개선

**적용 시작일**: 2025-11-06
**다음 리뷰**: 2025-11-13