영어 감각

터미널에서 진행하던 영어 학습을 웹에서 편리하게 이어 가도록 만드는 서비스다. 기본동사의 감각을 읽고, 원서 장면의 표현을 고르거나 쓰며, AI 해설로 문장이 그리는 그림을 살핀다.

have 감각 설명·공개 예시와 일곱 문제를 처음부터 펼친 문서로 읽으며 원하는 문제부터 푼다. 본문은 페이지를 내려 읽고, 넓은 화면에서는 AI 대화가 옆에 머문다. 첫 답·수정·질문 입력은 대화 칸에 모은다. 전체 공개 문항과 추가한 참고 자료에서 목차가 생기고, 콘텐츠 칸의 자료 스택에서는 최근 추가한 감각 자료를 펼친다. 좁은 화면은 탭 없이 문서 다음에 대화를 이어 놓는다. have·get·be·go·come 설명을 문서에 추가해 읽는다. 기존 have 책 장면 일곱 문항을 고르기·쓰기로 풀고, 카드별 처음 답·수정·질답을 유지한다. 대화의 ‘함께 풀 문제’를 바꾸어 원하는 문제와 대화를 이어 간다. 비로그인 상태에서는 수행·대화를 같은 브라우저에 임시 보관하고, Cloudflare Access로 로그인하면 학습자 전용 SQLite Durable Object(LearnerRecordStore)에 과정 원문과 최신 초안을 보관해 다른 기기에서 이어 쓰거나 study-and-learn 정본 과정 묶음으로 내보낸다. 제출 전에는 준비된 과업 안내를, 제출 후에는 실제 AI 응답을 제공한다.

읽기 이야기 15편(/reading/<이야기>/)과 책·영화 사전 훈련 유닛 13개(/prep/<작품>/unit-<n>/)도 같은 작업 공간의 수업이다. 이야기는 시간을 재어 읽고 본문을 가린 뒤 문제를 풀고, 카드는 표현 카드마다 빈칸을 채운다. 정답·해설은 서버 정본에만 있고 첫 답 뒤에 무료 판정 경로(/api/lesson-check/)가 정본과 비교해 알려 준다. 홈 도구 막대의 "수업 목록"이 이 수업들로 가는 링크를 연다. 수업마다 기록이 따로 같은 브라우저에 남는다.

운영 주소는 https://english.artificialmind.kr/ 이다. Next.js App Router와 React로 화면을 만들고, OpenNext 어댑터로 Cloudflare Workers에서 화면과 해설 API를 함께 실행한다. 기존 API 도메인도 같은 Worker에 연결했다. 프로젝트 기반은 project-base에서 받은 씨앗 모델·스킬·상태판·push 훅이다.

실행

Node.js 24와 npm을 쓴다. 처음 받은 뒤 의존성을 설치하고 프로젝트 훅을 켠다.

npm ci
git config core.hooksPath .githooks
cp .dev.vars.example .dev.vars
npm run dev

개발 화면은 http://localhost:3000/ 에서 연다. 해설을 실행하려면 .dev.vars의 ANTHROPIC_API_KEY를 채운다. 키가 없어도 콘텐츠와 문제는 사용할 수 있다. API와 횟수 제한은 npm run preview의 Workers 런타임에서 확인한다. next dev는 같은 Worker 안의 Durable Object를 실행하지 못하므로 이 환경에서 해설 API의 성공을 보장하지 않는다. .dev.vars는 git으로 추적하지 않는다. 프로젝트 공용 스킬의 정본은 shared-skills/다. Claude Code의 .claude/skills와 Codex의 .agents/skills는 모두 ../shared-skills를 가리키는 링크이며 같은 스킬을 읽는다.

구조

경로	하는 일
app/	App Router 페이지, API 경로, 메타데이터와 전역 스타일
components/	쓰임 그림 전환, 문제 풀이, AI 해설을 처리하는 React 컴포넌트
components/learning-workspace.tsx, app/workspace.css	장면 수업(have)의 콘텐츠 문서와 대화·목차·자료 스택·임시 복원
components/workspace-shell.tsx, workspace-session.tsx, workspace-chat.tsx	수업 종류에 상관없는 작업 공간 셸·기록 저장·대화 요청 수명주기·대화 표시
components/story-workspace.tsx, components/card-lesson.tsx, components/lesson-common.tsx	이야기 수업(읽기 구역·고르기)과 카드 수업(빈칸·수정·답 보기), 둘이 함께 쓰는 판정 요청·"판정" 항목·옛 판 안내
components/lesson-list-dialog.tsx, lib/lesson-list.ts	홈의 "수업 목록" 창과 그 목록 데이터(제목·주소만)
lib/lesson-registry.ts, lib/lesson-contract.ts, lib/lesson-workspace-state.ts	수업 29개의 ID·주소·문항 목록, 판정 계약, 이야기·카드의 수업 기록 v4
lib/server/lesson-catalog.ts, lib/server/lesson-judge.ts, lib/server/lesson-check.ts, lib/server/study-source.ts	읽기·사전 훈련 서버 정본·공개 투영·판 해시·무료 판정·목록용 요약
lib/workspace-layout-state.ts	목차 접힘과 채팅 읽기 설정의 별도 저장·복원
lib/document-workspace-state.ts	학습 기록과 분리한 자료 추가·펼침·목차 UI 상태
lib/reference-materials.ts, lib/server/reference-materials.ts	기존 공개 감각 자료의 안전한 전달
content/site.json	표제어와 책, 사이트 기본 설정
content/pages.json	공개 페이지의 본문, 메타데이터, 문제와 쓰임 그림 데이터
content/ask.json	해설기 예시 문장과 예시 해설
content/reading.json, content/prep.json	시간 제한 읽기와 책·영화 사전 훈련의 서버 정본(정답·해설 포함). study-and-learn 정본에서 만든 결과이며 손으로 고치지 않고, 서버 모듈(lib/server/study-source.ts)만 import한다
lib/content.ts	콘텐츠 타입과 페이지 조회
lib/learning-catalog.ts, lib/server/learning-catalog.ts

기존 원리 페이지와 연습 주소를 유지한다. /have.html 같은 옛 주소는 해당 페이지로 영구 이동한다. 콘텐츠를 고칠 때는 content/와 해당 컴포넌트를 고친다. HTML을 따로 생성해 커밋하지 않는다. 학습 모델, 원본 문제와 학습 기록의 정본은 study-and-learn 프로젝트가 관리한다. 읽기·사전 훈련 정본(study-and-learn content/reading, content/book-prep, content/movie-prep)이 바뀌면 npm run import:study -- <study-and-learn 경로>를 다시 돌려 두 JSON을 커밋한다.

해설 API

경로	요청과 응답
GET /api/health/	키와 요청 제한 바인딩의 준비 상태, 사용하는 모델
POST /api/learn-chat/	정본 장면·처음 답·수정·이전 질답을 이용한 학습 대화. have 계약은 lib/learning-chat-contract.ts, 이야기·카드 수업은 lib/lesson-chat-contract.ts
POST /api/lesson-check/	이야기 보기·카드 빈칸을 서버 정본과 비교하는 무료 판정과 카드 답 보기. AI와 사용량 한도를 쓰지 않는다. 계약은 lib/lesson-contract.ts
POST /api/explain/	영어 문장을 감각으로 해설한다
POST /api/translate/	한국어를 영어로 옮기고 감각으로 해설한다
POST /api/ask-followup/	문장 해설 결과에 이어 묻는 추가 질문에 답한다
GET/POST /api/learner-records/	Cloudflare Access로 인증한 학습자의 수업·해설기 기록 조회·저장·충돌 해소·명시적 가져오기·보관함 이동/복원
GET /api/learner-records/executions/	브라우저가 닫힌 뒤에도 서버가 보관한 AI 실행 결과를 유료 재호출 없이 조회한다
GET /api/learner-records/export/, POST /api/learner-records/ack/	study-and-learn 정본 과정 묶음(web-process-v1) 내보내기와 정본 수신 확인 반영

단문 해설·변환 POST 본문은 {"text":"I don't get it."} 같은 JSON이고, 빈 문장을 제외한 300자까지 받는다. 학습 대화는 문항·자료 판·아티팩트·최초 답·수정·이전 질답을 보내는 별도 계약이며 같은 300자 제한을 쓰지 않는다. 브라우저는 같은 도메인의 API를 부른다. 키와 감각 사전 지시문은 서버에서만 쓴다. 기존 감각 사전과 해설 형식, 기본 모델 Claude Sonnet 5.5를 옮겼다.

UTC 날짜를 기준으로 한 IP에서 하루 30번, 전체에서 600번까지 요청할 수 있다. SQLite 기반 Durable Object가 두 한도를 함께 검사하므로 실행 인스턴스나 배포가 달라져도 같은 날짜의 사용량을 공유한다. 공개 해설 API는 입력 문장이나 원래 IP를 영구 보관하지 않는다. 문장 해설기의 요청·결과·추가 질답은 비로그인 시 이 브라우저의 복원 사본(english-sense-ask-v1)에 남으며 파일로 내려받을 수 있고, Cloudflare Access 로그인 시 작업 공간 29개와 함께 개인 서버 보관(LearnerRecordStore)·기기 간 동기화·study-and-learn 정본 이관(scripts/sync-study-records.ts)에 연결된다. 한도 검사에 쓰는 날짜별 IP 해시와 횟수는 짧게 보관한 뒤 지운다.

검사와 배포

Next.js 타입과 API 검사, 실제 Workers 빌드와 브라우저 검사를 실행한다.

npm run check
python3 -m unittest discover -s scripts -p 'test_*.py'
npm run cf:build
npm run test:e2e

브라우저 검사는 Chromium이 필요하다. 처음에는 npx playwright install chromium으로 설치한다. npm run preview는 빌드한 서비스를 로컬 Workers 런타임에서 실행한다. GitHub Actions도 같은 검사와 Workers 빌드를 실행한다.

Cloudflare 계정 인증과 Worker secret을 준비한 뒤 배포한다. 비밀값은 명령 인수나 문서에 적지 않고 입력한다.

npx wrangler login
npx wrangler secret put ANTHROPIC_API_KEY
npm run deploy

일반 설정은 wrangler.jsonc의 vars에 있다. 설정을 바꾸면 npm run cf:typegen을 실행하고 다시 배포한다. 한도나 모델을 바꾸면 운영 안내와 화면의 설명도 함께 맞춘다. 도메인 전환과 검증 결과는 Cloudflare 전환 문서에 있다. 새 기능의 범위는 개인 학습 요구사항과 상태판에서 확인한다.

제작 모델과 스킬

• 웹앱 제작 모델: 사용자 과업과 약속, 품질과 검증 근거를 연결한다.
• 웹앱 UX 설계 모델: 정보구조·맥락·상태·시각 위계·복구와 재개를 설명한다.
• 웹앱 아키텍처 모델: 책임·상태·데이터·신뢰·실행 경계를 설명한다.
• Next.js 개발 모델: App Router·컴포넌트·렌더링·변경·캐시의 실행 의미를 설명한다.
• 기획 스킬: 승인된 요구를 수용 조건·구조 영향·최소 구현 범위가 있는 작업 계약으로 만든다.
• 구현 스킬: 미검증 가정을 실제 경계에서 확인하고 구현·실패·배포 결과를 연결한다.

Lighthouse 조사에는 원문 커밋과 실제 코드·테스트, 이 서비스에 옮긴 판단을 나눴다. 계약부터 엔지니어링까지의 실제 추적은 상세 조사에 있다. 규칙은 모델이, 수행 순서는 스킬이 소유한다. 현재 선택한 구조는 아키텍처 문서에 있다.

현재 디자인은 실제 Next.js 기본 학습 화면과 AI 대화로 연결했다. 확인한 경로와 남은 한계는 콘텐츠·대화 작업 계약과 모델 평가에 있다. 기존 퀴즈 수행의 근거는 퀴즈 아티팩트 계약에 있다. 이전 시안은 소개 중심 첫 제안으로 남겨 둔다.

작업 공간 29개와 /ask/ 문장 해설기의 개인 서버 기록·기기 간 이어 하기·정본 이관 계약과 검증 근거는 풀이 과정 기록 보존 계약에 있다. 정적 연습과 펜 노트(english-sense-notes-v1:<lessonId>)는 같은 브라우저에 보관한다.