콘텐츠로 이동

⚠ 이 페이지는 v0.1 (단계형 힌트 1~5단계) 기록 보존본. 2026-05-21부터 teams/engineering/concepts/사고력-답변구조-v0.2 (대화형 사고 유도)로 superseded (ADR-0009).

본문은 그대로 둠 (Karpathy 원칙 "decisions are forever"). 현재 정책은 v0.2 페이지 참조.

사고력을 기르는 AI 답변 구조 (v0.1 — superseded)

1. 무엇 / 왜

학생이 모르는 문제에 부딪혔을 때 AI가 즉답을 회피하고, 5단계 힌트로 사고를 유도한 뒤, 끝까지 막힐 때만 풀이 흐름·정답을 노출하는 답변 정책이다. 단순 LLM API 호출과 다른 점은 다음 세 가지가 도메인 수준에서 강제된다는 것:

  1. 정답 회피·힌트 우선·메타인지 유도 — 1~5단계 힌트 트리거가 명시적
  2. 학생 맞춤 컨텍스트 — 선생님이 등록한 강점/취약점/학습 성향이 프롬프트에 주입
  3. 선생님 연결 — 학생-AI 상호작용을 선생님이 AI Inbox에서 열람·피드백

출처: raw/notion/ai-mvp-v0.1 §4 핵심 원칙 1~4

2. 사용자 시나리오

학생

  1. 질문 등록 또는 과제 풀이 중 막힘 → "디에듀 AI 힌트" 버튼
  2. AI가 1단계 방향 힌트 응답
  3. 학생이 다시 시도 → 막히면 "다음 힌트" 요청
  4. 2~3단계 힌트 누적 → 여전히 막히면 4단계 풀이 흐름
  5. 마지막에 5단계 최종 정답 + 해설

선생님

  1. AI Inbox에서 자기 스터디룸 학생 질문 목록 확인 (정렬: 미해결 → 미완료 → 해결 완료)
  2. 상세 진입 → 학생/AI 대화 전체 로그 열람
  3. 특정 힌트 단계에 댓글로 피드백 (예: "여기서 한 단계 더 끌어줘도 됐다")

3. 데이터 모델

기존 [teams/engineering/domains/qna](../domains/qna.md)를 확장하는 방향으로 결정 (별도 도메인 신설보다 비용 낮음).

엔티티 처리
QnaMessage 컬럼 추가: actor (STUDENT/TEACHER/AI), hint_level (1~5, AI일 때만), token_usage_id (FK, nullable)
QnaContext 컬럼 추가: ai_status (NONE/IN_PROGRESS/RESOLVED) — AI Inbox 정렬용
(신규) StudentContext 학생당 1행. 과목/학습단계/학습목적우선순위/강점/취약점/자유메모
(신규) AiPromptTemplate key (e.g. hint.level1), body, model, version. 단계별 시스템 프롬프트
(신규) AiTokenUsage qna_message_id, model, prompt_tokens, completion_tokens, cost_usd, created_at
(신규) TeacherFeedback qna_message_id (FK), teacher_id, body, created_at. 단계별 댓글

4. Backend FRD

구현 명세 본문은 코드 옆 mvp-back:docs/frd/사고력-답변구조/spec (Backend) + mvp-front:docs/frd/사고력-답변구조/spec (Frontend) 에서 관리한다 (ADR-0004, ADR-0005). 본 페이지는 "왜·추상" 만 유지.

핵심 요약: - 기존 QnA 도메인 확장 + 4 신규 엔티티 (StudentContext, AiPromptTemplate, AiTokenUsage, TeacherFeedback) - API 6개 (학생 ai-hint·context 3 + 선생님 ai-inbox·ai-log·feedback 3) - Flyway V29~V34 (모두 추가 전용) - LLM provider Anthropic Claude 잠정 (ADR-0005 예정)

세부 (엔티티 필드·SQL·서비스 클래스명·권한 분기): mvp-back:docs/frd/사고력-답변구조

5. Frontend 화면/플로우

본 FRD는 backend 중심. Frontend 상세는 Track F에서 별도 작업.

후보 화면 (Tailwind v4 + 27개 UI 컴포넌트 + Tiptap 그대로 활용): - QnA 상세에 "디에듀 AI 힌트 받기" 버튼 + 단계별 답변 카드 UI - "다음 힌트" / "정답 보기" 노출 정책 (단계별 잠금 해제) - 학생 컨텍스트 입력 페이지 (/student/me/context) - 선생님 AI Inbox (/teacher/studyrooms/{id}/ai-inbox) — 정렬·필터 - 선생님 피드백 댓글 (메시지 단위 인라인)

6. 비기능

  • 성능: AI 응답 첫 토큰 < 3초. 스트리밍은 2차 MVP. 1차는 REST 동기 응답 (totalTime 목표 < 8초)
  • 비용: AiTokenUsage에 호출당 token/cost 기록. 일별/학생별 집계 쿼리로 운영 모니터링
  • 프롬프트 정책: 직접 정답 제공 금지(단계 1~3). 단계 4·5에서만 풀이 흐름/정답 노출. 시스템 프롬프트에 명시적으로 강제
  • 레이트 리밋: 학생당 분당 10건. 동일 messageId에 대한 hint 요청은 5단계까지만
  • 로깅: 모든 LLM 호출은 AiTokenUsage + 애플리케이션 로그(요청/응답 본문 마스킹)

7. 관련 도메인

8. 관련 결정

  • (예정) ADR-0004 — LLM provider 선정 (Anthropic Claude vs OpenAI vs 국내 LLM)
  • (예정) ADR-0005 — 프롬프트 본체 저장 위치 (DB vs yaml vs Git 별도 레포)
  • (참조) ADR-0002 — LLM wiki 도입 (raw vs wiki vs decisions 분리)

9. 출처

  • raw/notion/ai-mvp-v0.1 — "사고력 코치 AI" 정의
  • raw/notion/ai-mvp-v0.1 — 4대 원칙
  • raw/notion/ai-mvp-v0.1 — 단계형 힌트 + 학생 컨텍스트 + AI Inbox + 피드백 범위 확정
  • raw/notion/ai-mvp-v0.1 — RAG·자동 요약·말투 학습 명시적 제외