FastAPI + SQLite(WAL) + React(단일 HTML). 학급당 ~25명, 조별 로그인(학급당 6개 조).
로그인·제출·대화의 단위는 조다. 같은 조로 접속한 조원은 그 조의 모든 질문 프롬프트·되돌림 까닭·AI 대화를 함께 본다(4초 자동 갱신). 되돌림 게이트도 조 전체에 걸린다 — 한 질문이 교사 검토 중이면 같은 조는 새 질문을 못 낸다.
cd backend
cp env.example .env # API 키와 모델 ID를 채운다 (모델 ID는 필수)
./run.sh # seed → uvicorn :8000프런트는 frontend/index.html을 브라우저로 열면 된다. 빌드 도구가 필요 없다.
.env의 GENERATOR 값으로 갈아끼운다 — anthropic / openai / null.
모델 ID는 코드에 기본값이 없다. 비워 두면 실행이 막힌다 (의도된 것).
제공사 문서에서 현재 사용 가능한 ID를 직접 확인하고 .env에 적는다.
검증되지 않은 모델 ID를 코드에 박아 두면 "어떤 모델로 실험했는가"를 논문에 못 쓴다.
latest 별칭은 코드가 거부한다. 날짜가 박힌 스냅샷 ID를 쓴다.
4~12월 프로젝트인데 그 사이에 별칭이 가리키는 모델이 바뀌면 재현이 불가능하다.
매 호출마다 provider · model · temperature · system_prompt_hash가 DB에 남는다.
NullGenerator는 디버그용이다. 통제 조건이 아니다.
통제 학급도 반드시 실제 AI 응답을 받는다.
cd backend
GENERATOR=anthropic ANTHROPIC_MODEL=<확인한ID> python verify_model.py
GENERATOR=openai OPENAI_MODEL=<확인한ID> python verify_model.py검사지 v7 과제 5의 프롬프트 ㉠~㉣(A형·B형)을 실제 모델에 넣고 네 가지를 본다.
| 프롬프트 | 통과 조건 | 실패하면 |
|---|---|---|
| ㉠ 맥락 0 | 일반론을 낸다 | 학교 사실이 나오면 모델이 지어낸 것 |
| ㉡ 부가 질문만 | 형식은 지키되 내용은 빈다 | 학교 사정을 지어내면 "형식은 내용을 만들지 못한다"는 전제가 깨진다 |
| ㉢ 맥락 완비 | 우리가 준 사실이 반영된다 | 무시하면 맥락 제공의 효과를 못 보여 준다 |
| ㉣ 조건 위반 | 못 할 계획을 성실히 낸다 | 거절하면 조건 위반 문항이 성립 안 한다 |
그리고 되묻기 0회여야 한다. 넷 다 통과하는 모델을 쓴다. 결과 JSON을 논문에 싣는다. 모델 선택의 1순위 기준은 브랜드가 아니라 이것이다.
이 시스템의 산출물은 대개 포스터 문구다. 포스터 문구는 수사의문문 투성이다 — "책, 심심하지 않나요?", "오늘 뭐 읽지?" 이런 것을 되묻기로 잡으면 처치 오염률이 부풀려져 논문이 틀린다.
그래서 guard()는 두 층으로 나눈다.
- HARD — 명시적 정보 요구("알려 주세요", "질문이 있어요"). 하나만 있어도 되묻기.
- SOFT — 학생만 답할 수 있는 사실을 묻는 의문문("몇 명이 오나요?"). 단독으로는 판정하지 않는다. 응답이 질문 위주(의문문 비율 ≥ 0.5)일 때만 되묻기로 본다.
되묻기로 판정되면 강한 지시를 붙여 1회 재시도하고, 해소 여부(retry_fixed)를 기록한다.
차단하지 않는다. 기록한다.
학생이 "도서관에 사람이 안 와. 방법 알려 줘"를 보냈는데 AI가 "몇 명이 오나요? 어느 학년인가요?"라고 되물으면 — AI가 되돌림을 대신해 버린다. 그러면 통제 학급 학생도 AI에게서 교육적 피드백을 받고, 처치와 통제의 차이가 사라진다.
그래서 두 겹으로 막는다.
generators/base.py의SYSTEM_PROMPT— 되묻기·조언·사실 지어내기를 금지한다. 이 프롬프트는 처치의 일부다. 논문 부록에 그대로 싣는다.guard()— 그래도 되물으면 탐지한다. 한 번 재시도하고, 그래도 되물으면FIDELITY_ALERT_MODEL_ASKED_BACK이벤트로 기록한다.
GET /api/admin/fidelity의 model_asked_back_rate가 0이어야 한다.
0이 아니면 모델을 바꾸거나 시스템 프롬프트를 강화해야 한다.
모델 선택의 1순위 기준이 이것이다. 브랜드가 아니다.
- 조작은 통과 / 되돌림 두 가지뿐. (+ 유해 차단)
- 통과 시
sent_prompt = student_prompt. 항상, 예외 없이. edited_prompt를 보내면 403으로 거부하고INVARIANT_VIOLATION으로 기록한다.- 직접 편집 UI와 "AI 제안 넣기" 버튼은 존재하지 않는다.
-
태그 없이 되돌릴 수 없다 (400).
-
까닭 없이 되돌릴 수 없다 (400).
-
까닭은 청자의 관점에서 쓴다.
Damen 외(2021, QJEP 74(6), 1054–1069, doi:10.1177/1747021820987080)에서 자기중심 편향이 줄어든 것은 서사적 피드백을 받은 집단뿐이었고, 정확성 피드백 집단에서는 줄지 않았다. 태그("[대상]이 부족합니다")는 정확성 신호다. 그것만 주면 학생은 "네 가지를 넣어야 통과한다"는 규칙을 외울 뿐, 관점 전환은 일어나지 않는다.
- ✗ "[대상]이 부족합니다."
- ○ "1학년이 이 포스터를 보면 '잔반율'에서 멈출 거예요. 그 말을 들어 본 적이 없거든요."
services/fidelity.py의classify_reason()이 까닭을 서사형/정확성형으로 분류하여 기록한다. 차단하지 않는다. 넛지하고 기록한다. 최종 판정은 사후 인간 코딩으로 한다 — 이 점수는 표본추출 우선순위에 쓴다.
- 통제 학급도 프롬프트를 쓰고 AI 응답을 받는다.
- 차이는 교사가 유해 내용만 차단한다는 점 하나.
- 통제 조건에서
returned를 시도하면 400으로 거부한다.
학생 이름도 출석번호도 저장하지 않는다. 조 번호만 쓴다. 프롬프트에 실명이 들어가지 않도록 수업에서 지도한다. API의 학습 미사용 / 무보존 설정을 확인하고 문서로 남긴다 (IRB·KOFAC 승인용).
| 테이블 | 무엇 |
|---|---|
classrooms |
학급. condition(처치/통제) |
teams |
조. 로그인·제출·대화의 단위. number(조 번호). 학급당 6개 |
submissions |
한 조의 한 차시 루프. 조원이 공유한다. return_count |
prompt_versions |
되돌아올 때마다 새 판. student_prompt / sent_prompt / edit_distance / invariant_violated |
reviews |
교사 판단. 태그 4개 + reason 원문 + reason_type(서사/정확성) |
ai_responses |
model · temperature · system_prompt_hash · asked_back · gave_advice |
events |
append-only. 수정하지 않는다 |
judge_items / judgments |
1차시. 조가 쓴 질문(question) + 그 질문에 대한 AI 답 5개(조 공유) + 조의 판정(①②③ + 까닭) |
retrace_tags |
6차시. 조가 자기 5차시 질문을 스스로 되짚은 태그 + 역추적 한 줄 |
peer_reviews |
7차시. 조가 다른 조 질문에 붙인 태그 + 까닭(reason_type) |
transfer_prompts |
8차시. 전이 과제. 되돌림·AI·피드백 없이 저장만 |
teacher_answers |
1차시 활동3. 교사가 자세한 프롬프트로 받은 AI 답(학급 공유) |
activity_options |
2차시 활동3. 통과 답을 쪼갠 항목 + 조의 O/X 적합 판정·이유 |
team_notes |
조 자유 서술(1차시 비교 compare, 2차시 최종선정 final 등) |
로그인에서 고른 차시가 그 차시의 활동 화면 하나만 켠다 (GET /api/config/sessions).
| 차시 | 모드 | 화면 | 되돌림 주체 | AI |
|---|---|---|---|---|
| 1 | judge |
활동1 조가 쓴 질문→AI답 · 활동2 ①②③ 판정+까닭 · 활동3 교사 상세답과 비교 | 없음 | 조가 직접 + 교사(활동3) |
| 2~5 | loop |
쓰기 → 교사 게이트 → AI (2차시는 답 5가지 + 활동3 O/X 적합·최종선정, 5차시는 자기점검란) | 교사 | O |
| 6 | retrace |
자기 5차시 질문 되짚어 스스로 태그 + 역추적 | 자기+외부준거 | 없음 |
| 7 | peer |
다른 조 질문에 태그+까닭 붙여 되돌림 | 동료 | 없음 |
| 8 | transfer |
전이 과제(전기 절약). 되돌림·AI·피드백 없음 | 없음 | 없음 |
시스템이 맡는 것은 AI 상호작용과 되돌림 기록이다. 페르소나 카드·5 Whys 사다리·
비교표·청자 카드·스티커판 같은 활동지는 종이 인쇄물이다(수업안 02_수업/).
SESSIONS[n]["answers"](기본 1). 2차시는 통과 시 AI가 답 5가지를 준다.
⚠ 5가지 답은 생성 호출에 "다섯 가지로 답하라"는 형식 지시를 얹어 받는다.
sent_prompt(DB 기록)는 여전히 학생 원문 그대로이고 불변식(sent_prompt == student_prompt)은 유지되지만, 모델이 실제로 받는 사용자 메시지에는 형식 지시가 덧붙는다. 시스템 프롬프트처럼 차시 단위로 일괄 적용되는 처치의 일부로 볼 수 있으나, 재현성 기록 관점에서 인지할 것.
태그 집합은 차시마다 다르다(SESSIONS[n]["tags"], 프런트는 /api/config/sessions로 받는다).
- 기본(3·4·5·6·7차시):
[상황] [대상] [조건] [목적]— 4개. - 2차시(역할 부여 차시):
[목적] [상황] [대상] [조건] [역할] [예시]— 6개.
⚠ HANDOFF는 "피드백 태그 4개, 이것만"을 확정 설계로 둔다(강동훈·이미경 2014 요인분석 근거). 2차시에
[역할] [예시]를 더한 것은 그 문장과 어긋난다. 두 태그는 맞춤법·문장 태그는 아니지만(그 금지와는 무관), '4개 고정'을 깨는 변경이므로 지도교수·검사도구(v7)와의 정합성을 확인할 것. 검사가 4개 태그로 채점된다면 2차시만 6개인 것이 수업–검사 불일치를 만든다.
| 지표 | 기대값 | 아니면 |
|---|---|---|
narrative_reason_rate |
높을수록 좋음 | 낮으면 그 학급은 처치가 전달되지 않았다 |
model_asked_back_rate |
0 | 0이 아니면 AI가 되돌림을 대신했다 — 처치 오염 |
invariant_violations |
0 | 0이 아니면 교사가 대신 고쳤다 |
models_used |
원소 1개 | 여러 개면 기간 중 모델이 바뀌었다 — 재현성 붕괴 |
system_prompt_hashes |
원소 1개 | 여러 개면 처치가 도중에 바뀌었다 |
- 과제 5(검사지)의 AI 응답 4개가 실제 모델 출력이 아니다. 연구자가 쓴 예시다. 예비검사 전에 실제 모델에 프롬프트 ㉠~㉣을 넣어 확인해야 한다. 특히 ㉡(부가 질문만)이 정말로 "형식은 지키되 내용은 비는" 답을 내는지.
- 인증·인가 없음. 조 로그인은 드롭다운 선택일 뿐 인증이 아니다(비밀번호 없음). 교실 내부망 전제. 외부 노출 시 반드시 인증을 붙일 것. 학생이 첫 화면에서 '교사 로그인'을 눌러 들어갈 수 있다 — 필요하면 교사 PIN을 붙인다.
- 1차시 판정: null 생성기는 답을 5개로 못 쪼갠다(1개로 나온다). 실모델에서 5개가
나오는지,
_split_five의 파싱이 그 모델 출력 형식과 맞는지 예비검사에서 확인할 것. - 6·7차시 스티커 수치 입력/집계는 종이다. 시스템은 자기 태그·역추적·동료 판별만 받는다.