원전: Arthur Benjamin & Michael Shermer, Mathemagics (1993) 작성: 오케스트레이터 (Fable 5) · 구현자: Opus 5 (medium effort) 상태: v1 확정 (2026-07-28, 리서치 4종 반영 완료) · 주요 결정 완료: IndexedDB(§6), i18n ko 기본+en 지원·확장 가능(§6.2, §10-7), 기억술 로케일별 모듈(§10-2), 저작권 방침(§10-1) · 미결정 없음
아이들(초등~중등)에게 벤저민식 암산(mathemagics)을 가르치는 인터랙티브 웹 교재. GitHub Pages 정적 호스팅 + 브라우저 IndexedDB 기본(사용자 승인), 셀프호스트 시 SQLite 옵션. UI/UX 최우선.
- 책의 기법을 단계별 애니메이션으로 시각화하는 레슨 모듈
- 세로셈/가로셈 표기를 정확하고 아름답게 렌더링 + 아이가 직접 입력하는 에디터
- 진도·숙련도 추적 (간격 반복 기반 복습)
- GitHub Pages 단일 배포로 누구나 무료 사용
- 셀프호스터를 위한 SQLite 저장 백엔드 옵션 (동일 코드베이스)
- 서버 필수 기능 (계정/로그인/클라우드 동기화) — v1에서 제외
- 상용 손글씨 인식 (라이선스 비용) — 조사 결과에 따라 재검토
- 네이티브 앱
| 페르소나 | 설명 | 핵심 니즈 |
|---|---|---|
| 학습자 (8–13세) | 암산을 배우는 아이 | 짧은 세션, 즉각 피드백, 재미 |
| 보호자/교사 | 진도를 확인하는 어른 | 대시보드, 셀프호스트 옵션 |
상세 근거: docs/research/book-content-map.md (기법 ~40개, 장별 규칙·단계별 예제·선행 관계 전부 수록. 예제 수치는 재검산 완료)
| 트랙 | 원전 장 | 내용 | 비고 |
|---|---|---|---|
| A. 암산 메인 | 1→2→3→4→5→8장 | 좌→우 "앞자리부터 확정" 암산: 덧셈·뺄셈·보수 → 2×1·제곱 → 2×2(4가지 방법) → 나눗셈 → 어림셈 → 고급(4·5자리 제곱, 3×3, 5×5) | 제품의 중심. 8장은 5장(어림)과 7장(음성 코드)을 선행 요구 |
| B. 지필(세로셈) | 6장 | 열 덧셈, 크리스크로스 곱셈, 지필 제곱근, 9/11 버리기 모드섬 검산 | 유일한 우→좌·쓰기 계열. 5장 세로셈 렌더러의 주 사용처 |
| C. 기억술 | 7장 | 음성 코드(Major System): 숫자↔단어 변환, 계산 중간값 저장 | 한글 자음 매핑으로 신설계 확정 — 설계는 M6 (§10-2) |
| D. 수학 마술 | 9장 | 마술 트릭 9종 | 독립 트랙이 아닌 보상 콘텐츠로 A/B 트랙 사이에 분산 배치 |
자릿값 → [1] 좌→우 덧셈 → [1] 좌→우 뺄셈 → [1] 보수
구구단 → [2] 2×1 → [2] 3×1 → [2] 2자리 제곱
[2] + [1] → [3] 2×2 (덧셈법/뺄셈법/인수분해법/11법) → [3] 3자리 제곱
[2] → [4] 나눗셈 → [4] 단순화/소수화/배수판정
[1~4] → [5] 어림셈 (독립적, 일찍 배치 가능; 8장의 부품)
[6] 지필 계산: 별도 트랙 (모드섬은 [4] 배수판정과 연결)
[7] 음성 코드: 독립 트랙 (3자리 제곱부터 유용, 8장 필수)
[3] + [5] + [7] → [8] 4자리 제곱 → 3×2 → 5자리 제곱 → 3×3 → 5×5
[9] 마술: 각 트릭이 앞 장 원리의 응용 → 해당 스킬 달성 시 해금
각 기법(스킬) 1개 = 레슨 1개. 교수 설계 원칙(§4)을 그대로 구현한 5단계:
- 훅: 이 기법으로 가능해지는 "마술" 데모 (앱이 시연, 3~10초)
- 예제 관찰: 단계 시각화 애니메이션 + 내레이션 (worked example, 2~3문제)
- 페이딩: 마지막 스텝부터 학생이 채움 (
expect셀 점진 확대) - 독립 연습: 전체 풀이 입력, 3단 힌트 사다리, 정확도 게이트(90%)
- SRS 편입 + 마술 해금: 이후 FSRS 스케줄에 따라 혼합 세트(interleaving)로 재등장
- 레슨 메타 + 문제는
content/lessons/*.json(5장의 시맨틱 스키마) — 코드와 분리, 비개발자도 추가 가능. 텍스트 필드(내레이션·힌트)는 로케일 키 객체(§6.2 i18n),ko폴백. - 문제 생성기: 기법별 파라미터(자릿수, 올림 여부, 난이도 레벨)로 무한 생성 —
deriveSteps와 같은 순수 함수 모듈에 배치. - 원문 텍스트는 복제하지 않고 규칙·수치 구조만 사용 (저작권, §10 참조). 예제 수치는 생성기가 새로 만든다.
상세 근거·출처: docs/research/teaching-trends.md (문서 말미에 근거 검증 수준 부록 있음)
- 전략 배우기 → 단계 시각화 → 유창성 훈련의 전체 파이프라인. 벤치마크 앱(Duolingo Math, Khan Kids, Prodigy, Mathigon, TTRS 등) 어디에도 셋을 다 갖춘 곳이 없음 — 이것이 이 앱의 시장 공백이자 정체성.
- 좌→우 분해 + digit-reveal 애니메이션을 핵심 시각 언어로. 벤저민 방법의 본질을 UI로 번역한 것 (5장의 스텝 엔진이 이를 구현).
- 정확도 우선 게이트(accuracy-first). 정확도 90% 통과 후에만 시간 모드 해금 (McNeil et al. 2025 산술 유창성 합의 리뷰).
- 인출 연습 코어 루프 + FSRS 간격 반복. 아동 대상 직접 검증이 없으므로 보수적 파라미터 + 불규칙 사용 견고성 필수.
- 스킬 도입은 예제 → 페이딩 예제 → 독립 풀이 3단계. (worked-example effect; 페이딩 = 마지막 스텝부터 학생이 채우는 방식)
- 힌트는 Point → Teach → Bottom-out 3단 사다리 + 남용 감지. bottom-out 힌트 남용은 학습과 부적 상관 (LAK26).
- 적응형 난이도로 성공률 80–90%(ZPD) 유지.
- 시간 모드는 opt-in + 자기 기록 갱신 + "마술 공연" 프레임. 시간 압박↔수학 불안 논쟁의 절충이자 mathemagics 컨셉 고유의 서사 — 랭킹 비교가 아니라 "관객 앞 공연 준비".
- 유지 단계에서 전략 혼합 세트(interleaving)로 "어떤 트릭을 쓸까?" 판단 훈련 — 전략 선택이 곧 핵심 역량.
- 풀이 후 전략 카드 선택("나는 이렇게 풀었어") — 자기 설명(self-explanation)의 저비용 구현. 음성 언어화는 v2.
- 스트릭은 관대하게(freeze 제공, 일일 최소량 낮게). 보상은 숙달·수집·자율성 중심, 손실 회피 압박 금지.
- 새 전략 도입 시 CRA 페이드: 표상(자릿수 다이어그램) → 순수 암산.
FSRS(아동), Number Talks, TTRS 효과는 근거가 약함 — 이들에 기반한 설계는 조정 가능하게(파라미터화) 구현할 것.
상세 근거: docs/research/vertical-notation-editors.md
| 레이어 | 채택 | 이유 (요약) |
|---|---|---|
| 세로셈 렌더링 | 커스텀 CSS Grid 컴포넌트 (자릿수 1개 = 셀 1개, tabular-nums, carry 행·부분곱 행, 나눗셈 브래킷은 SVG) |
MathML 초등수학 요소(mstack/mlongdiv)는 MathML Core에서 제외되어 2026년에도 전 브라우저 미지원. KaTeX/MathJax도 정식 미지원. 아동 UX 핵심(칸 안내·즉시 피드백·단계 애니메이션)이 전부 셀 단위 DOM 제어를 요구 |
| 입력 | 커스텀 digit-cell 에디터 + 가상 넘패드 (활성 셀 강조, method에 따른 auto-advance 방향, 셀 단위 정오 피드백) | MathLive/MathQuill/Desmos 모두 세로셈 미지원. 손글씨 인식(MyScript/Mathpix)은 API 키 노출·비용 문제로 정적 사이트 부적합 → v2에서 온디바이스 숫자 인식만 재검토 |
| 애니메이션 | CSS transitions + 시퀀싱 필요 시 Motion mini animate()(~5KB). prefers-reduced-motion 준수 |
GSAP은 무료화됐지만 과잉 |
| 인라인 수식 | 일반 HTML 텍스트 | 러닝 토탈(623 + 100 = 723) 수준이면 충분 |
- 저장 포맷 = 시맨틱 스키마(후보 A):
{op, operands, method: "ltr"|"rtl", level, hints}— 스텝은 순수 함수deriveSteps(problem)가 런타임 파생. 벤저민식(좌→우)/학교식(우→좌) 전환이 필드 하나로 끝나고, 파생 엔진이 곧 채점기가 됨. - 런타임/특수 포맷 = 셀 좌표+스텝 스키마(후보 B):
grid.rows[].cells+steps[](highlight/write/carry/strike/reveal,expect: true= 학생 입력 대기 지점,narration= aria-live 낭독 겸 말풍선). 나눗셈 등 비정형 레이아웃과 저자 지정 연출용. - 스키마 전문과 확장 규칙(부분곱 행, 나눗셈 브래킷)은 리서치 문서 §4 참조.
셀별 aria-label, DOM 순서 = 풀이 순서, aria-live로 스텝 낭독, 물리 키보드(숫자키·화살표) 병행 지원.
상세 근거: docs/research/architecture-hosting.md
┌────────────────────────────────────────────┐
│ 앱 (Vite + Svelte 5, PWA, hash routing) │
│ 레슨 · 연습 · SRS 엔진 · 프로필 · 포팅 │
└───────────────────┬────────────────────────┘
│
StorageAdapter (Promise 기반 인터페이스)
┌──────────────┴──────────────┐
[정적 모드: GitHub Pages] [자가 호스트 모드: 가정 PC/NAS/Docker]
DexieAdapter (IndexedDB RestAdapter ──HTTP──▶ Bun 단일 파일 서버
+ navigator.storage.persist()) (Hono + bun:sqlite, 정적 빌드 동시 서빙)
│ │
└────────── JSON ExportBundle ──────────── data.sqlite
(schemaVersion + 순차 마이그레이션)
- 어댑터 선택은 런타임 감지: 부팅 시
/api/healthprobe(800ms 타임아웃) → 성공 시 RestAdapter, 실패 시 DexieAdapter. 같은 정적 빌드를 두 모드에서 재사용.- M6 서버 계약 (M0에서 발견·확정): SPA 폴백이
/api/health에도 200 HTML을 반환하므로r.ok만으로는 오판 — probe는 JSON content-type + 본문{app:"mathemagics"}를 요구한다. Bun 서버는 이 형식으로 응답해야 함 (근거: docs/briefs/M0-RESULT.md).
- M6 서버 계약 (M0에서 발견·확정): SPA 폴백이
- 저장소 (확정 — 2026-07-28 사용자 승인): 브라우저 저장은 IndexedDB(Dexie.js) 를 주 저장소로 사용. SRS 카드 데이터가 계속 자라고 인덱스 쿼리(due 카드 조회)가 필요하기 때문. localStorage는 "마지막 활성 프로필 ID" 같은 소형 플래그만.
- Safari ITP 7일 축출 방어:
navigator.storage.persist()+ PWA 홈 화면 설치 유도. - 참고: SQLite WASM
opfs-sahpoolVFS는 COOP/COEP 없이 GitHub Pages에서 동작 확인됨 — 다만 Dexie 대비 이점 없어 채택 안 함(브라우저 내 SQLite가 꼭 필요해지면 카드 남아 있음).
Vite + Svelte 5(전환·스프링 내장, 런타임 ~2–5KB) + TypeScript, hash routing(Pages 404 회피), vite-plugin-pwa(오프라인), actions/deploy-pages 배포. 멀티 프로필(형제 공용 기기)은 두 모드 공통 지원.
i18n (2026-07-28 결정): 기본 ko, 동시 지원 en, 로케일 추가 확장 가능.
- UI 문자열: 컴파일 타임 i18n 라이브러리 사용 — 후보는 Paraglide JS(inlang) 또는 svelte-i18n, M0에서 비교 후 확정(미검증 상태로 명시).
- 레슨 콘텐츠: 내레이션·힌트·전략 카드명은
{ ko: "...", en: "..." }로케일 키 객체, 누락 시ko폴백. 숫자·스텝 데이터는 로케일 무관. - TTS: Web Speech API에서 활성 로케일의 음성 선택.
- 언어 설정은 프로필 단위(형제가 서로 다른 언어로 학습 가능).
ExportBundle(schemaVersion, profiles, progress, srsCards, settings) JSON을 두 모드의 공용 통화로. import는 merge(last-write-wins) / replace 모드. 셀프호스트 서버는 동일 번들을 /api/export|import로 노출.
| 컴포넌트 | 원전 표기 | 연출 |
|---|---|---|
| 분해 미리보기 | 67 + 28 (20+8) 괄호 주석 |
문제 옆에 분해 계획이 살짝 나타남 |
| 치환 체인 | 759+496 → +500 → 1259 → −4 → 1255 |
문제가 더 쉬운 문제로 바뀌는 화살표 애니메이션 |
| X-다이어그램 | 제곱의 ±d 분기 도식 | 2→3→4자리 제곱에서 같은 도식이 재귀 중첩 — 확대/축소 연출의 핵심 자산 |
| 누계 롤링 | 부분곱 + running total 세로 나열 | 누계 숫자가 카운터처럼 롤링 |
| 보수 매칭 | "47의 보수 53" | 두 자릿수가 뒤집혀 짝을 맞추는 전용 연출 |
| digit-reveal | 답을 앞자리부터 발화 | 말풍선 + TTS로 왼쪽부터 한 자리씩 공개 |
| 메모리 슬롯 | 손가락 자릿수 저장, 음성 코드 단어 | 손 아이콘 + 단어 카드 UI로 치환 |
| 세로셈 그리드 | 6장 지필 표기 전체 | 5장의 CSS Grid 렌더러 (올림 위첨자, 밑줄, 대각선, 모드섬 동그라미) |
- 모든 탭에 즉각 반응 (아동은 무반응 시 연타 후 이탈). 터치 타깃 ≥48dp, 핵심 버튼 ~2cm, 화면 하단 배치 회피.
- 가상 넘패드 + 활성 셀 강조 + auto-advance (기법의 method에 따라 좌→우 or 우→좌), 셀 단위 즉시 정오 피드백. 물리 키보드 병행.
- 텍스트 최소화: 지시는 시각 단서 + 짧은 단문(16px+ 산세리프). 지시문 TTS·자막·고대비 모드 기본 제공.
prefers-reduced-motion준수. - 세션 설계: 1세션 5–10분에 자연스러운 마무리. 무한 스크롤·강제 연장 없음.
- 8–13세 톤: 유치함 배제(한 학년만 어려 보여도 이탈하는 연령대). 마스코트보다 "마술사 공연" 세계관 — 보상은 숙달·수집·자율성.
- 다크패턴 제로 + COPPA 2025 정합: 손실 회피 압박·비교 리더보드·업셀 없음. 데이터는 전부 로컬(우리 아키텍처의 태생적 장점 — 수집 자체가 없음을 명시).
- 접근성: 셀별
aria-label, DOM 순서 = 풀이 순서,aria-live스텝 낭독. - 시각 디자인 작업 시
frontend-design/superdesign스킬 활용 가능 (구현 단계 참고).
각 마일스톤 = Opus 5(medium)에게 넘기는 독립 브리프 1개. 순서 = 의존성 순.
| M | 범위 | 완료 기준 (검증 가능해야 함) |
|---|---|---|
| M0 스캐폴드 | Vite+Svelte 5+TS(strict), hash routing, vite-plugin-pwa, GitHub Actions 배포, StorageAdapter 인터페이스 + DexieAdapter + 어댑터 자동 감지, 멀티 프로필 CRUD, i18n 기반(ko 기본 + en, 라이브러리 비교·확정, 프로필별 언어 스위처) |
svelte-check·vitest·build 통과, Pages 배포 URL에서 프로필 생성·새로고침 후 유지 확인, ko↔en 스위칭 동작 확인 |
| M1 계산 코어 | 시맨틱 문제 스키마 + deriveSteps 엔진(덧셈·뺄셈, ltr/rtl 양방향) + CSS Grid 세로셈 렌더러 + digit-cell 에디터 + 가상 넘패드 + 스텝 재생기 |
엔진 순수함수 단위 테스트(자릿수·올림 전 조합), 데모 페이지에서 한 문제를 애니메이션 재생·직접 입력 모두 가능 |
| M2 레슨 프레임워크 + 1장 | 5단계 레슨 템플릿(§3.3), 3단 힌트 사다리 + 남용 감지, 전략 카드, 1장 콘텐츠(좌→우 덧셈·뺄셈·보수) + 문제 생성기 | 1장 3개 레슨을 처음부터 끝까지 플레이 가능, 진도 저장 |
| M3 연습·SRS | FSRS 스케줄러(파라미터화), 정확도 90% 게이트, 적응 난이도(성공률 80–90%), 혼합 세트, 학습자 진도 화면 + 보호자 리포트("배운 전략 + 대화 소재 1개") | 시뮬레이션 테스트(가상 학습 기록 → 스케줄 검증), 게이트·난이도 로직 단위 테스트 |
| M4 곱셈·나눗셈·어림 | 2·3장(X-다이어그램 컴포넌트 포함, 재귀 중첩 지원), 4장 나눗셈(브래킷 표기), 5장 어림셈 | 각 기법 레슨 플레이 가능, X-다이어그램 2·3자리 제곱 재귀 렌더 확인 |
| M5 지필 트랙·공연 모드 | 6장(열 덧셈, 크리스크로스, 지필 제곱근, 모드섬 검산 — "오답 잡아내기" 게임), opt-in 시간 모드("마술 공연" 프레임 + 자기 기록), 9장 마술 해금 콘텐츠 | 크리스크로스 1-2-3-2-1 스텝 리듬 재생, 공연 모드 기록 저장 |
| M6 고급·셀프호스트 | 7장 기억술(한글 자음 매핑표 + 아동 어휘 단어 사전 설계 포함, §10-2) + 메모리 슬롯 UI, 8장 고급 곱셈, RestAdapter + Bun 서버(Hono+bun:sqlite) + Docker, ExportBundle 내보내기/가져오기 |
두 모드 간 JSON 왕복 이식 테스트, 셀프호스트에서 동일 빌드 구동 |
| M7 UI/UX 폴리시 (안티-AI-슬롯) | "The Stage" 디자인 시스템(토큰·타이포·리듬 재구성) — 기존 라우트·엔진·i18n 구조 보존, 시각·인터랙션 레이어만 교체(hallmark redesign 규약). 인앱 Dialog(M0 이슈 #3 폐쇄), 버튼 8상태, 마이크로인터랙션 3종, 접근성 고도화 |
토큰 inline 색/폰트 0건, 320/375/414/768px 반응형 검증, M0 #3 폐쇄, 기존 74 테스트 회귀 없음, 6축 자기비판 스탬프 |
- 브리프 전달: 마일스톤마다
docs/briefs/M<n>.md작성 후 파일 경로만 전달. 브리프에는 ① 목표와 완료 기준(§8 행) ② 반드시 먼저 읽을 문서(이 PLAN.md + 관련 research 문서 §번호) ③ 건드릴/만들 파일 경로 ④ 검증 명령을 명시. - 결과 회수: 구현자는 결과 요약을
docs/briefs/M<n>-RESULT.md에 쓰고 경로만 보고 (대량 출력을 대화에 덤프 금지). - 품질 규약: TS strict, 계산 엔진·스케줄러는 UI와 분리된 순수 함수 + vitest 커버, 최소 유지보수 가능한 변경, 미검증 성공 주장 금지 (실패한 테스트는 출력 그대로 보고).
- 검증 명령:
npm run check(svelte-check) ·npm test(vitest) ·npm run build— M0에서 셋을 CI로 고정. - 콘텐츠 수치 확인: 기법 규칙이 모호하면 book-content-map.md의 해당 §를 우선, OCR 미확인 표기(동 문서 §6)는 원본 PDF 해당 페이지(책 페이지+21)를 직접 재확인.
| # | 항목 | 상태 / 대응 |
|---|---|---|
| 1 | 저작권: 원서는 저작권 저작물. GitHub Pages 공개는 출판 행위 | 방침 확정(2026-07-28 사용자 승인): 모든 설명문 자체 작성, 예제는 생성기로 신규 생성, 원문 문장·예제 미복제, 서지 출처만 표기 |
| 2 | 7장 한국어 현지화: 음성 코드(기억술)가 영어 자음 발음 기반이라 생성 단어가 영어 단어가 됨 | 결정(2026-07-28): 로케일별 기억술 모듈 — ko는 한글 자음 매핑 신설계(원리 유지, 0~9→한글 자음, 한국어 단어 생성), en은 원서의 Major System 그대로. 기억술은 번역이 아니라 로케일별 별도 콘텐츠 모듈로 구현. 한글 매핑표 + 아동 어휘 단어 사전 설계는 M6에서 |
| 3 | FSRS 아동 대상 근거 부족 | 파라미터 외부화 + 불규칙 사용 견고성 확보 (teaching-trends 부록) |
| 4 | Safari ITP 데이터 축출 | navigator.storage.persist() + PWA 설치 유도 + 주기적 내보내기 리마인더 |
| 5 | OCR 미판독 잔여 표기 | book-content-map §6 목록 — 해당 기법 구현 시 원본 페이지 재확인 |
| 6 | 콘텐츠 규모(기법 ~40개) | 트랙 A 1~3장까지를 공개 가능한 최소 제품으로 보고 단계 릴리스 |
| 7 | UI 언어 | 결정(2026-07-28): 기본 한국어 + 영어 지원. 학습자(한국어 사용자 포함)가 언제든 영어로 스위칭 가능 — 언어 스위처를 프로필 설정에 노출. 로케일 추가가 파일 추가만으로 가능한 i18n 구조를 M0부터 내장 |
| 문서 | 내용 |
|---|---|
| docs/research/book-content-map.md | 원서 9개 장 → 기법 ~40개 규칙·예제·스킬트리·표기 문법 카탈로그 |
| docs/research/teaching-trends.md | 2024–26 근거 기반 교수법·게이미피케이션·벤치마크 앱 분석 + 우선순위 권장 15개 |
| docs/research/vertical-notation-editors.md | 세로셈 렌더링·입력 기술 비교(MathML/KaTeX/커스텀), JSON 스키마, 권장 스택 |
| docs/research/architecture-hosting.md | 저장소 추상화, SQLite 옵션 평가, 이식성, 프론트엔드 스택, 배포 |