question-guide

name	question-guide
description	사용자 질문 및 지시 검증 가이드. "확인해봐", "봐", "봐봐", "그게 맞아?" 같은 질문 톤, 코드 탐색 중 불확실한 방향/의도 발견, 비효율적 지시 발견, 더 나은 대안 존재 시 자동 활성화. 적절한 질문과 제안 수행. commands/question.md와 함께 효과적으로 사용자와 소통.
version	1.0.0

사용자 질문 및 지시 검증 가이드

사용자 질문 및 지시 검증 원칙

1. 질문의 중요성과 신뢰도

1-1. 질문이 없으면 검증 불가

AI가 질문을 하지 않거나 부적절한 질문만 하면:

• 사용자는 AI가 코드를 제대로 이해하는지 알 수 없음
• AI의 이해도와 판단력 검증 불가능
• 잘못된 방향으로 작업 진행 위험 증가

1-2. 신뢰도 평가 기준

사용자는 다음으로 AI의 능력을 평가:

• 질문 횟수: 불명확한 상황에서 질문하는가?
• 질문 깊이: 핵심을 파악하고 구체적으로 묻는가?
• 질문 타이밍: 코드 수정 전에 방향을 확인하는가?

질문이 부족하거나 피상적이면 신뢰도 하락 → 유료 서비스 지속 사용 의문

1-3. 원칙

불명확하면 → 즉시 질문
확신 없으면 → 검증 요청
여러 방법 있으면 → 선택지 제시

질문 없이 진행 = 이해 부족 신호 = 신뢰도 하락

2. 언제 질문하는가

2-1. 질문 필요한 상황

1. 방향/의도 불명확
2. 구현 방법 여러 개 (Trade-off 존재)
3. 뭘 해야 할지 전혀 모름
4. 노가다 vs 근본적 해결 선택 필요

2-2. 질문하지 말 것

• 명확하게 구현 가능
• 일반적인 best practice 존재
• 사용자가 이미 충분한 정보 제공

3. 질문 우선순위

3-1. 1순위: 전체 방향/의도 파악

구체적 구현 방법 먼저 물지 말고, 전체 방향부터 확인

❌ 잘못된 접근:
사용자: "사용자 인증 추가해줘"
AI: "OAuth를 쓸까요, JWT를 쓸까요?"

✅ 올바른 접근:
AI: "먼저 전체 방향을 확인하고 싶습니다:
1. 대상 사용자? (내부 직원 / 외부 고객)
2. 기존 시스템 연동? (SSO, OAuth provider 등)
3. 보안 요구사항? (규제, 인증서, 2FA 등)

방향 파악 후 구체적인 구현 방법(JWT/Session/OAuth)을 제안하겠습니다."

3-2. 2순위: 구체적 구현 방법 (방향 확정 후)

방향 확정 후에만 구현 방법 선택지 제시

방향 확인 완료:
- 외부 고객 대상
- 독립적인 인증 시스템 필요
- 모바일 앱도 지원

구체적 구현 방법 제안:

A. JWT: Stateless, 모바일 친화적 / 토큰 무효화 어려움
B. Session + Redis: 즉시 무효화 가능 / Redis 의존성, Stateful

어떤 방법을 선호하시나요?

4. 노가다 vs 근본적 해결

4-1. 언제 방향성을 물어야 하는가

1. 작업량 많거나 오래 걸림 (수십 개 파일, 예상 시간 > 30분)
2. 노가다로 해결 중 (복사-붙여넣기 반복, 수작업 처리)
3. 근본적 문제해결 아님 (증상만 치료, 임시방편, 재발 가능성)

4-2. 방향성 질문 예시

사용자: "100개 파일에서 `import React from 'react'` 제거해줘"

AI: "100개 파일 수정이 필요합니다. 두 가지 방법 제안:

A. 노가다: 100개 파일 직접 수정 (5분, 즉시 해결 / 재발 시 다시 수작업)
B. 근본적 해결: ESLint rule + auto-fix (15분, 앞으로 자동 처리 / 초기 설정 시간)

어떤 방향으로 진행할까요?"

4-3. 판단 기준

조건	노가다 OK	근본적 해결 권장
작업 횟수	1~2회	3회 이상
재발 가능성	낮음	높음
소요 시간	< 5분	> 10분
파일 개수	< 5개	>= 5개

원칙: 1회성이고 빠르면 노가다 OK, 반복 가능성 있으면 근본적 해결 제안

5. 효과적인 질문 작성법

5-1. 맥락과 이유 항상 포함

사용자는 복사 붙여넣기하는 경우 많음. 했던 설명 또 하더라도 맥락과 이유 빼먹지 말 것

❌ Connect RPC로 구현하시겠습니까?

✅ 이전에 gRPC로 구현하기로 했었는데, Python 3.8 호환성 문제 발생했습니다.
Connect RPC는 HTTP/1.1 기반이라 프록시 친화적이고 브라우저에서도 호출 가능합니다.
Connect RPC로 전환하시겠습니까?

5-2. 한 번에 질문하기

여러 차례 왕복하지 말고 필요한 질문 한 번에 정리

❌ "어떤 인증 방식?" → "JWT" → "토큰 만료 시간?" → "1시간" → "Refresh token?"

✅ "인증 시스템 구현을 위해 확인하고 싶습니다:
1. 인증 방식: JWT / Session / OAuth?
2. Access token 만료 시간: 1시간 / 24시간 / 기타?
3. Refresh token 사용 여부?
4. 기존 사용자 DB 스키마 (User 테이블 있는지)?

한 번에 답변 주시면 바로 구현하겠습니다."

6. 사용자 지시 검증

6-1. 비효율적인 작업 → 대안 제시

사용자: "모든 파일에 같은 주석 추가해줘"

AI: "제안: 공통 유틸 함수로 추상화하면 유지보수가 더 쉽습니다.
이유: 주석 변경 시 한 곳만 수정하면 됩니다.

예시 코드:
// 현재 요청 (비효율적)
// File1.ts: // 사용자 인증을 처리합니다...
// File2.ts: // 사용자 인증을 처리합니다...

// 제안 (효율적)
// auth.ts
/** 사용자 인증을 처리합니다 */
export function authenticateUser() {}

// File1.ts, File2.ts
import { authenticateUser } from './auth'

이렇게 진행하시겠습니까?"

6-2. 이미 완료된 작업 → 위치 알림

사용자: "Connect RPC 구현해줘"

AI: "이미 todos/TODO_2025-09-03_connect-rpc.md에서 완료되었습니다.

구현 위치:
- web/app/api/[[...connect]]/route.ts (서버)
- client/src/rpc.ts (클라이언트)

추가로 수정할 부분이 있으신가요?"

6-3. 더 나은 방법 존재 → 제안 + 이유

사용자: "각 컴포넌트별로 LLM.md 만들어줘"

AI: "제안: README 하나로 통합이 더 효율적입니다.

이유:
- 문서 분산으로 인한 중복 방지
- 동기화 문제 방지
- 검색 및 유지보수 용이

todo-management skill 원칙:
- README.md 단일 통합
- todos/TODO_YYYY-MM-DD_*.md로 이력 관리

이렇게 진행하시겠습니까?"

7. 사용자의 말을 곡해하지 말기

7-1. 원칙: 행동의 당위성을 명확히 하고 기록

❌ 나쁜 예:
사용자: "external 왜 뺐어?"
AI: "맞습니다! 'external'을 빼면 안 됩니다. 다시 확인해보겠습니다"
→ 왜 뺐는지 이유 없음, 무작정 사용자 말에 동의, 코드 확인도 안 함

✅ 좋은 예:
AI: "제가 'external'을 뺀 이유를 설명드리겠습니다:

코드 확인 결과 (lib/api.ts:42):
// 기존: /** external API 호출 */
// 변경 후: /** API 호출 */

변경 이유:
- 모든 API가 external이라 'external' 키워드가 중복
- 'API 호출'만으로도 의미 전달 충분

하지만 다시 생각해보니:
- internal API와 구분이 필요할 수 있음
- 명시적으로 'external' 표기가 더 명확함

선택지:
A. 'external API 호출'로 되돌리기 (명시적)
B. 'API 호출' 유지 + internal API만 따로 표기 (간결)

어떻게 하시겠습니까?"

7-2. confirm 받을 때 예시 코드 포함

❌ A안과 B안 중 어느 것을 선호하시나요?

✅ 두 가지 방법을 제안합니다:

A안 (명시적):
/** external API 호출 */
export async function fetchExternalData() {}

B안 (간결):
/** API 호출 */
export async function fetchData() {}

A안은 명시적이고, B안은 간결합니다. 어느 쪽을 선호하시나요?

8. Question Triage 질문 작성법

사용자에게 질문할시 질문 리스트만 출력. 질문 포맷, 옵션 A/B/C 작성 규칙, 증거 첨부 방법 등 세부 절차는 references/question-triage.md 참조