# AI 코치와 대화하기 (사용자 가이드)

> 적용 버전: **v0.4.0 이상** · Redmine #260 · 관련 레퍼런스: [docs/reference/260-in-app-tool-calling.md](../reference/260-in-app-tool-calling.md)
>
> 본 가이드는 v0.3.0 의 [AI 도움 켜기·끄기](ai-help-onboarding.md) 가 끝났다는 전제에서 시작합니다. 모델이 단말에 준비되어 있어야 합니다.

v0.4.0 부터는 자유 문장으로 AI 코치에게 카탈로그를 묻거나, 습관을 추가하거나, 오늘의 체크인을 기록할 수 있습니다. 모든 처리는 단말에서 일어나며 입력 텍스트는 외부로 나가지 않습니다.

## 진입

1. **습관 목록** 화면 진입.
2. AppBar 의 🤖 (smart toy) 아이콘 탭.
   - AI 도움이 꺼져 있으면 아이콘이 보이지 않습니다 — [AI 도움 켜기](ai-help-onboarding.md) 먼저 진행해주세요.

## 가능한 대화 예시

- "아침 햇빛 프로토콜이 뭐야?" → AI 가 카탈로그에서 찾아 한국어로 요약.
- "수면 관련 습관 추천해줘" → 카테고리 검색 결과를 보여주고 어떤 것부터 시작할지 제안.
- "아침 햇빛 보기 습관 추가해줘" → **확인 다이얼로그가 떠야** 추가됩니다 (아래 §확인 게이트).
- "오늘 햇빛 체크해줘" → 같은 식의 확인 다이얼로그.
- "내 스트릭 어때?" → 현재 연속일수 + 5-tier 보상 등급 안내.

## 확인 게이트 (destructive actions)

다음 작업은 사용자의 명시적 확인 없이는 절대 수행되지 않습니다:

- **습관 추가** (`add_habit`)
- **체크 기록** (`log_tracker_entry`)

확인 다이얼로그가 뜨면:
- **수행** — 작업 진행
- **취소** — 작업 중단 (대화에는 `🛠 습관 추가 → 취소됨` 라벨이 남습니다)
- 바깥 영역 탭 = 취소

## 안전장치

- 한 대화당 최대 4번의 도구 호출 — 무한 루프 방지.
- 8 turn 도달 시 "대화가 길어졌어요" 안내 — 오른쪽 위 ↻ 로 새 대화 시작 권장 (이전 기록은 비워짐).
- AI 가 잘못된 인자로 도구를 호출하면 검증 오류 메시지를 모델에게 돌려주고, AI 가 다시 시도합니다. 앱이 죽지 않습니다.
- "술 끊기" 같은 회피 표현은 R7 규칙으로 자동 거부 + 긍정 프레임 제안 ("맑은 정신을 즐긴다" 등).
- 활성 build 습관 3개 / break 습관 1개 초과 시 R3 규칙으로 거부 — 기존 습관을 정리해야 추가 가능.
- 같은 날짜의 같은 습관에 두 번 체크하면 중복 안내 — 덮어쓰려면 기존 항목 삭제 후 다시 시도.

## 자주 묻는 질문

**Q. 대화 기록은 어디에 저장되나요?**
A. 메모리만 — 화면을 떠나거나 ↻ 를 누르면 사라집니다. 단말에 저장되지 않습니다.

**Q. AI 가 같은 도구를 계속 호출하면?**
A. 4 회를 넘기면 자동으로 멈추고 "도구 호출 루프가 너무 길어 중단했습니다" 안내가 뜹니다.

**Q. 응답이 너무 느린 것 같아요.**
A. 단말 모델이라 1턴 평균 2~5초가 정상입니다. AI 가 도구를 호출하면 round trip 이 한 번 더 들어가 6~10초가 될 수 있어요.

**Q. 도구 결과가 잘렸어요.**
A. 모델 컨텍스트 보호를 위해 도구 결과는 2KB 로 제한됩니다. 잘림이 발생하면 AI 가 자동으로 단건 조회 (`프로토콜 상세`) 도구를 다시 부르도록 안내됩니다.

## 관련 문서

- [AI 도움 켜기·끄기](ai-help-onboarding.md)
- 설계서: [docs/design/260-gemma-tool-calling/](../design/260-gemma-tool-calling/)
- 결정 기록: [docs/adr/0005-in-app-tool-calling-architecture.md](../adr/0005-in-app-tool-calling-architecture.md)
- API 레퍼런스: [docs/reference/260-in-app-tool-calling.md](../reference/260-in-app-tool-calling.md)
- 변경 이력: [CHANGELOG.md](../../CHANGELOG.md)