[Architect] #312 design spec — tool call prefix corpus & 조건부 push

설계서 3 + 절차서 1.
- README.md: 기능 설계서 (15 케이스 corpus, 임계 5/15, 경로 A/B)
- fn-corpus_logger.md: optional debug logger (kDebugMode + dart-define 가드)
- fn-userTurn_partial_push.md: chat_providers.dart 의 break 분기 수정안 (경로 A/B)
- corpus-procedure.md: 빌드/캡처/15 프롬프트/임계 판정 절차

R1-R5 모두 해소 (Architect 채택안).
ADR-0006 슬롯 = 경로 B 채택 시 작성 (Developer 단계).

Refs #312
This commit is contained in:
2026-06-15 14:17:47 +09:00
parent 41457ab96e
commit 94a9cd474b
4 changed files with 546 additions and 0 deletions

View File

@@ -0,0 +1,89 @@
# Corpus 수집 절차 (#312)
> **부모 설계서**: ./README.md · **목적**: Developer 가 corpus 를 재현 가능하게 수집할 수 있도록 절차 명문화.
## 1. 빌드
```bash
cd app
flutter build apk --debug --dart-define=ENABLE_CORPUS_LOG=true
# 또는 단말 연결 후
flutter run --debug --dart-define=ENABLE_CORPUS_LOG=true
```
`ENABLE_CORPUS_LOG=true` 가 빠지면 `DebugCorpusLogger.maybeCreate()` 가 null 반환 → logging 없음.
## 2. 로그 캡처
```bash
# adb 연결된 단말
adb logcat | grep CorpusLogger > /tmp/corpus-raw.log
# 또는 flutter run 의 stdout
flutter run --debug --dart-define=ENABLE_CORPUS_LOG=true 2>&1 \
| grep CorpusLogger > /tmp/corpus-raw.log
```
각 줄은 `[CorpusLogger] {"kind":"text_chunk"|"function_call",...}` 형태의 JSON.
## 3. 프롬프트 시퀀스 (15 케이스)
ChatScreen 진입 후 아래를 순서대로 입력. 각 프롬프트 사이에 ↻ 로 세션 초기화 (turn 격리).
### catalog 카테고리 (5)
1. 수면 관련 습관 추천해줘
2. 아침에 할 수 있는 습관 뭐 있어?
3. 스트레스 관리 프로토콜 알려줘
4. 운동 관련 카탈로그 보여줘
5. 명상 어떤 게 있어?
### add_habit 카테고리 (5)
6. 아침 햇빛 보기 습관 추가해줘
7. 매일 물 2L 마시기 추가해줘
8. 잠들기 전 스트레칭 등록할래
9. 출근 전 명상 5분 추가해줘
10. 점심 후 산책 습관 만들어줘
### log_tracker_entry 카테고리 (3)
11. 오늘 햇빛 봤어 체크해줘
12. 어제 운동한 거 기록해줘
13. 오늘 명상 완료
### streak 카테고리 (2)
14. 내 연속 기록 어때?
15. 스트릭 보여줘
## 4. 결과 표 작성
`/tmp/corpus-raw.log` 의 각 `function_call` 이벤트에서 `accumulated_prefix` 를 추출해 `docs/research/312-tool-prefix-corpus.md` 표에 채운다.
표 schema (README §6.2 참조):
```markdown
| # | category | user_input | tool_name | accumulated_raw | meaningful | note |
|---|----------|-----------|-----------|-----------------|------------|------|
| 1 | catalog | 수면 관련 습관 추천해줘 | search_catalog | "수면 카탈로그를 보여드릴게요" | Y | 정보 전달 의도 + 14자 |
| 2 | catalog | 아침에 할 수 있는 습관 뭐 있어? | search_catalog | "" | N | 빈 prefix |
| ... |
```
판정 기준은 README §6.1 의 운영 정의:
- **Y**: 공백 제외 한국어 자연어 ≥10 자 + 정보 전달 의도.
- **N**: 빈/공백/boilerplate/단순 응대/echo.
## 5. 임계 판정
- Y 카운트 ≥5 → 경로 A (push 구현).
- Y 카운트 =4 → +5 케이스 추가 수집 (총 20, 임계 7).
- Y 카운트 ≤3 → 경로 B (폐기 + ADR-0006).
## 6. 후처리
- corpus 결과를 Redmine #312`## [AI] Developer` 섹션 (또는 별도 댓글) 에 요약: Y/N count + 채택 경로.
- 채택 경로에 따라 `fn-userTurn_partial_push.md` 의 경로 A 또는 B 를 구현.
- 경로 B 채택 시 ADR-0006 작성 (`docs/adr/0006-tool-call-prefix-discard.md` 또는 적합한 제목).
- corpus 수집 종료 후 `--dart-define=ENABLE_CORPUS_LOG=true` 사용 빈도 0 → 향후 CorpusLogger 제거 follow-up 이슈 발행 검토.
## 7. 보너스 — ParallelFunctionCallResponse 측정
같은 raw log 에서 한 turn 안에 `function_call` 이 2 회 이상 emit 되는지 확인. 발생 시 AC4 의 follow-up 이슈에 빈도 데이터 포함.