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)

원칙:
  - 핵심 답변 먼저 (2-3문장)
  - "더 알고 싶으면" 선택지 제공
  - 긴 설명은 명시적 요청 시에만

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

2. 명확화 우선 (Clarify-First)

원칙:
  - 모호함 감지 → 즉시 AskUserQuestion
  - 가정 기반 진행 금지
  - 2가지 이상 해석 가능 → 선택지 제시

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

3. 작업 범위 확인 (Scope-Check)

원칙:
  - 큰 작업 시작 전 범위 확인
  - 예상 영향 파일/시간 사전 공유
  - 승인 후 진행

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

4. 결과물 우선 (Outcome-First)

원칙:
  - 작업 완료 → 결과 먼저 보고
  - 과정 설명은 필요시에만
  - 파일 경로 + 변경사항 요약

템플릿:
  "✅ 완료: [핵심 결과]
   변경: [파일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