[3주차 크루 미션 - 개발 중반 & 중간 공유] ellipsis 미션 제출합니다.

AGENTS.md

@@ -0,0 +1,98 @@
+# AGENTS.md
+
+이 파일은 이 저장소에서 작업하는 모든 AI 코딩 에이전트(Claude Code, Codex, Cursor 등)와 사람 메인테이너의 단일 진실 공급원(SSOT)이다. 특정 도구에 종속되지 않도록 작성한다. `CLAUDE.md`는 이 파일을 가리키는 심볼릭 링크이므로 둘 중 무엇을 편집해도 같은 내용이 갱신된다.
+
+> **주의:** `CLAUDE.md`는 `AGENTS.md`를 가리키는 심볼릭 링크다. 별도 사본이 아니므로 한쪽만 따로 편집하지 말 것. 새 에이전트 지원을 추가할 때도 사본을 만들지 말고 링크만 건다(예: `ln -s AGENTS.md GEMINI.md`).
+>
+> **OS별 동작 차이:**
+> - **macOS/Linux**: Git이 심볼릭 링크를 그대로 체크아웃한다. 추가 설정 없이 동작하므로 별도 조치가 필요 없다. (현재 팀 기본 환경)
+> - **Windows**: Git이 심볼릭 링크를 만들려면 ① 개발자 모드 활성화 또는 관리자 권한과 ② `git config core.symlinks true`가 모두 필요하다. 둘 중 하나라도 없으면 링크가 내용 대신 대상 경로(`AGENTS.md`)만 담긴 한 줄짜리 일반 텍스트 파일로 풀려, 그 파일을 여는 에이전트가 지침 전체를 읽지 못한다. 이 경우 위 설정을 켠 뒤 재클론하거나 `git checkout -- CLAUDE.md`로 다시 받는다.
+
+## 저장소 개요
+
+`android-mini-projects`라는 이름이지만 현재 유일한 활성 프로젝트는 **keybuddy**(키보드 추천 웹 서비스)이며 Android 코드는 없다. 자연어/단계별 질문으로 사용자에게 맞는 키보드를 추천한다.
+
+- `impl/keybuddy/` - 실제 제품 (프론트 + Supabase Edge Function)
+- `impl/crawl.py` - 다나와 목록 크롤러 (데이터 소스 생성)
+- `impl/output/` - 크롤러 산출물 (`keyboards.json` 등, 생성물)
+- `report/`, `README.md` - 기획/주차별 리포트 (제품 가설·문제정의)
+- `impl/keybuddy/*.yaml`, `*.md` - 의도 하네스 Seed 명세 및 before/after 분석
+
+루트 `README.md`는 제품 기획서, `impl/keybuddy/README.md`는 실행·배포 운영 매뉴얼이다.
+
+## 주요 명령어
+
+모든 프론트 명령은 `impl/keybuddy/frontend/`에서 실행한다. 루트에서 실행하면 `Missing script` 오류가 난다.
+
+```bash
+cd impl/keybuddy/frontend
+npm install
+npm run dev          # Vite 개발 서버 (localhost:5173)
+npm test             # vitest run (전체)
+npm test -- src/__tests__/intentSearch.test.ts   # 단일 파일
+npx vitest run -t "완화"                          # 이름 패턴으로 단일 테스트
+npm run typecheck            # tsc --noEmit (프론트)
+npm run typecheck:function   # Edge Function 타입체크
+npm run build        # sync:function-version + typecheck + vite build
+```
+
+Edge Function (Deno, `impl/keybuddy/`에서):
+
+```bash
+supabase functions serve recommend --env-file supabase/functions/.env.local   # 로컬 실행
+cd frontend && SUPABASE_PROJECT_REF=<ref> npm run deploy:function              # 배포
+```
+
+데이터 갱신 (크롤러 재실행 후 양쪽 카탈로그 동기화):
+
+```bash
+cd impl && python3 crawl.py
+cd keybuddy/frontend && npm run sync:data   # output/keyboards.json -> 프론트 + Edge Function 사본
+```
+
+## 아키텍처: 두 개의 추천 경로
+
+keybuddy의 핵심은 **추천 엔진이 두 갈래로 존재**한다는 점이다. 혼동하지 말 것.
+
+1. **현재 UI에 연결된 경로 (production)**: `App.tsx` → `lib/recommend.ts`(HTTP fetch) → Supabase Edge Function `recommend/index.ts`. Edge Function이 키워드 스코어링(`scoreKeyboard`)으로 후보를 40개 이하로 압축한 뒤 **OpenAI**(`gpt-5.4`)에 넘겨 추천 사유를 생성한다. `OPENAI_API_KEY`는 브라우저에 절대 내려가지 않고 Supabase secret에만 존재한다 (`recommend.ts`는 `apikey` 헤더만 보냄).
+
+2. **결정론적 의도 하네스 (lib/, 테스트로만 검증됨 - 아직 UI 미연결)**: `extractRawTags.ts`(유일한 LLM 호출, `claude-sonnet-4-6`로 자연어→의도+명시제약 번역) → `intentProfile.ts`(의도를 차원별 태그로 정적 확장) → `intentSearch.ts`/`searchEngine.ts`(하드필터 + 소프트 스코어링 + 무결과 시 제약 완화). 설계 의도는 `docs/tag-extraction-flow.md` 참고. **"LLM은 번역만, 태그 확장·검색은 전부 결정론"**이 핵심 불변식이며, 같은 입력→같은 출력을 보장한다.
+
+`docs/tag-extraction-flow.md`는 경로 2를 "현재 흐름"으로 서술하지만 실제 `recommend.ts`는 경로 1(Edge Function)을 호출한다. 경로 2는 구축·테스트 완료됐으나 아직 `recommend.ts`에 배선되지 않았다 - 이 갭이 TODO의 "키보드 에이전트 직접 설계" 작업 대상이다.
+
+### lib/ 파이프라인 핵심 모듈 (경로 2)
+
+- `extractRawTags.ts` - 자연어 → `ExtractedTags { hardConstraints, softIntentTags }` (LLM 1회)
+- `tagSchema.ts` - 소프트 의도 태그 어휘(controlled vocabulary)와 검증
+- `softTagRules.ts` - 소프트 태그 → 키보드 매칭 술어(규칙 맵)
+- `intentProfile.ts` - 고수준 의도(사무용/게이밍/휴대용)를 차원별 요구로 확장. 강도는 `필수`(하드 승격)/`선호`(소프트 점수)/`상관없음`. 명시 제약이 의도보다 우선.
+- `hardFilter.ts` - 하드 제약 위반 키보드 제외 (위반 0건 보장)
+- `softScorer.ts` - 소프트 태그 매칭 점수 → 랭킹
+- `searchEngine.ts`/`intentSearch.ts` - 무결과 시 제약을 우선순위 역순으로 1개씩 완화 후 재검색(`HARD_CONSTRAINT_RELAXATION_ORDER`). `searchKeyboards`는 LEGACY, `searchWithProfile`이 신규 진입점.
+
+## 데이터 파이프라인
+
+`crawl.py`는 다나와 **목록 페이지만** 조회한다(상세 페이지 요청 안 함, `DELAY_SEC` 레이트리밋 준수). 한 상품에 스위치 옵션이 여럿이면 제품-스위치 조합별 레코드로 펼치고 최종 **600개**로 제한(`TARGET_RECORDS`). 스위치 이름은 `src/data/switch_aliases.json` 규칙으로만 매칭하고, 매칭 실패는 추론하지 않고 `output/unmatched_switches.json`에 격리한다.
+
+카탈로그 `keyboards.json`은 **두 군데에 사본**으로 존재한다(프론트 표시용 + Edge Function 후보용). 반드시 `npm run sync:data`로 함께 갱신해야 둘이 엇갈리지 않는다.
+
+## 버전 관리
+
+앱 버전의 단일 소스는 `frontend/package.json`의 `version`이다. `npm run build`/`deploy:function`이 `sync:function-version`으로 이 값을 Edge Function의 `version.ts`에 주입하며, Edge Function은 `GET /recommend`, 응답 `meta.version`, `X-Keybuddy-Version` 헤더로 노출한다. 배포 전 `npm version patch|minor|major --no-git-tag-version`으로 SemVer 증가.
+
+## 테스트 규약
+
+`src/__tests__/`에 36개 vitest 스위트가 있다. 특징적인 패턴:
+
+- **`*LlmNoCall.test.ts`** - 결정론 경로가 실제로 LLM을 호출하지 않음을 강제하는 불변식 테스트. lib/ 검색 로직 수정 시 이 보증을 깨지 말 것.
+- **`*.goldset.test.ts`** - 정답셋 기반 정확도 회귀 테스트(하드제약/소프트의도 정확도).
+- **`*Parity.test.ts`** - 두 경로/구현 간 동작 일치 검증.
+
+## Git 작업 규칙
+
+- `ellipsis` 브랜치에 직접 커밋하지 말 것. `ellipsis`는 `origin/ellipsis`와 동일하게 유지한다.
+- 작업은 항상 새 브랜치에서 진행한다 (`feat/...`, `fix/...`).
+
+## 리뷰 기준 (`REVIEW.md`)
+
+`Important`는 동작을 막는 결함(로직 오류·보안·데이터 유출·크래시)에만 사용하고 스타일 제안은 최대 `Nit`. 생성 산출물(`impl/output/**`, `src/data/keyboards.json`)과 `node_modules`는 리뷰 대상에서 제외한다.

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

README.md

@@ -146,3 +146,32 @@ PC를 구매하면 자연스럽게 따라오는 `필수 입력장치`일 뿐, 
     1. 선택지가 충분한가?
     2. 코어층과 라이트층 모두 놓칠 수 있지 않을까?
     3. 선택지 속 설명의 난도가 적절한가?
+
+---
+
+### 9. 구현 현황 (2026-06 기준)
+
+위 기획의 핵심 기능은 keybuddy 웹앱(`impl/keybuddy/`)에 구현되어 동작합니다. 추천 후보 데이터는 다나와 크롤러로 수집한 키보드 600개를 사용합니다.
+
+**입력 방식 (홈 화면 세그먼트 토글)**
+
+- `자유롭게 입력` : 자연어 문장을 입력하면 의도에 맞는 키보드를 추천합니다. 예시 템플릿 3종을 제공합니다.
+- `단계별 선택` : 아래 질문에 순서대로 답하면 조건에 맞는 키보드를 추천합니다.
+
+**단계별 질문 10개 (기획 그대로 구현)**
+
+용도 / 휴대성 / 타건 소리 / 키감 / 키압 / 연결 방식 / 크기 / 예산(범위 슬라이더) / 각인 / 백라이트. 대부분의 질문에 `상관없음`류 선택지를 두고 진행률 바를 표시합니다(타건 소리·크기·백라이트 제외).
+
+**추천 결과 화면**
+
+- 제품명 / 가격 / 이미지 / 추천 사유(한 줄)
+- 특징 태그(스위치, 연결 방식, 배열, 키압, 백라이트 등) 나열
+- 초보자용 라벨과 주의 노트, 키감/소음 단계 그래프
+- 가격비교 링크, 브랜드·태그 필터, 추천순/낮은가격순/높은가격순 정렬
+- 별점 피드백(0.5점 단위)
+
+**기획 대비 추가된 것** : 결과 필터/정렬, 별점 피드백, 초보자 가이드 라벨.
+
+**아직 하지 않은 것** : 5번(키캡 커스터마이징, 타건음)은 의도대로 미구현입니다. `구매하기` 버튼은 현재 "준비 중" 안내만 표시하며 주문 플로우(7-4)는 연결하지 않았습니다.
+
+추천 엔진 동작 방식, 자연어→태그 추출 설계, 실행·배포 방법 등 기술 상세는 [`impl/keybuddy/README.md`](impl/keybuddy/README.md)와 `impl/keybuddy/docs/`를 참고하세요.

docs/deployment-version-management.md

@@ -0,0 +1,119 @@
+# Supabase Edge Function 버전 관리 메모
+
+## 프로젝트 메모리 작성 위치
+
+현재 이 프로젝트의 배포/버전 관리 메모는 아래 파일에 작성했습니다.
+
+- `impl/keybuddy/README.md`
+  - `## 배포` 섹션에 앱 버전 단일 소스, 버전 증가 방식, Supabase Edge Function 배포 및 버전 확인 방법을 반영했습니다.
+- `docs/deployment-version-management.md`
+  - 이 파일입니다. 어떤 내용을 어디에 기록했는지와 코드 변경 이유를 별도로 정리합니다.
+
+대화에서 언급된 Firebase 프로젝트 `socratic-learn-web` 관련 배포 절차는 이 저장소의 실제 배포 대상이 아니므로 그대로 적용하지 않았습니다. 대신 해당 프로젝트의 원칙 중 “배포할 때마다 SemVer 기준으로 단일 버전을 올린다”는 부분만 Supabase Edge Function 구조에 맞게 적용했습니다.
+
+## 코드 변경이 필요했던 이유
+
+기존 상태에서는 `frontend/package.json`에만 앱 버전(`0.1.0`)이 있었고, Supabase Edge Function 배포물에는 어떤 앱 버전이 올라가 있는지 확인할 방법이 없었습니다.
+
+Supabase Edge Function은 Firebase Functions처럼 별도 릴리즈 커밋이나 배포 메타가 자동으로 앱 응답에 드러나지 않습니다. 그래서 배포 후 운영 환경에서 아래 질문에 답하기 어려웠습니다.
+
+- 현재 배포된 `recommend` Edge Function이 어떤 앱 버전인지
+- 프론트와 Edge Function이 같은 버전 기준으로 배포되었는지
+- 장애나 회귀가 발생했을 때 어떤 버전의 함수 응답인지
+
+이를 해결하기 위해 Edge Function이 앱 버전을 응답에 노출하도록 변경했습니다.
+
+## 적용한 방식
+
+앱 버전의 단일 소스는 계속 `impl/keybuddy/frontend/package.json`입니다.
+
+프론트 빌드 시 아래 스크립트가 실행됩니다.
+
+```bash
+npm run sync:function-version
+```
+
+이 스크립트는 `frontend/package.json`의 `version` 값을 읽어서 아래 파일을 생성/갱신합니다.
+
+```text
+impl/keybuddy/supabase/functions/recommend/version.ts
+```
+
+Edge Function은 이 파일의 `appVersion`을 import해서 사용합니다.
+
+## 버전 확인 방법
+
+배포된 Edge Function은 OpenAI 호출 없이 `GET` 요청만으로 버전을 확인할 수 있습니다.
+
+```bash
+curl https://your-project-ref.supabase.co/functions/v1/recommend
+```
+
+예상 응답 형식:
+
+```json
+{
+  "name": "recommend",
+  "version": "0.1.0"
+}
+```
+
+추천 `POST` 응답에도 아래 메타가 포함됩니다.
+
+```json
+{
+  "summary": "...",
+  "recommendations": [],
+  "meta": {
+    "version": "0.1.0"
+  }
+}
+```
+
+응답 헤더에도 같은 버전이 포함됩니다.
+
+```text
+X-Keybuddy-Version: 0.1.0
+```
+
+## 이 방식의 장점
+
+- 버전의 원본은 `frontend/package.json` 한 곳으로 유지됩니다.
+- Edge Function 배포 번들 내부에 `version.ts`가 포함되므로, 배포 시 상위 디렉터리 파일 import 문제를 피할 수 있습니다.
+- 배포 후 `GET /functions/v1/recommend`만으로 현재 함수 버전을 확인할 수 있습니다.
+- 기존 추천 API 계약은 유지하면서 `meta.version`만 선택 필드로 추가하므로 프론트 호환성이 깨지지 않습니다.
+
+## 배포 시 주의사항
+
+배포 전 변경 성격에 맞춰 SemVer 기준으로 버전을 올립니다.
+
+```bash
+cd impl/keybuddy/frontend
+npm version patch --no-git-tag-version
+```
+
+- 호환되는 버그 수정: `patch`
+- 호환되는 기능 추가: `minor`
+- 호환 깨짐: `major`
+
+그 다음 프론트 빌드를 실행하면 Edge Function 버전 파일이 자동 갱신됩니다.
+
+```bash
+npm run build
+```
+
+Edge Function을 배포할 때는 버전 동기화와 타입 검사를 강제하는 래퍼를 사용합니다.
+
+```bash
+SUPABASE_PROJECT_REF=your-project-ref npm run deploy:function
+```
+
+이 래퍼는 `tsc --noEmit` 타입 검사를 실행하고, 배포 스크립트 안에서
+`sync:function-version`을 실행한 뒤 `supabase functions deploy recommend`를 호출합니다.
+따라서 `package.json`의 버전과 `supabase/functions/recommend/version.ts`의 버전이
+어긋난 상태로 배포될 가능성을 줄이면서 불필요한 프론트 정적 빌드는 피합니다.
+
+프로덕션 오배포를 피하기 위해 `SUPABASE_PROJECT_REF`는 필수입니다. 실제 project ref는
+공개 문서에 적지 말고 로컬 환경 변수나 비공개 설정에서 주입합니다.
+
+Supabase Edge Function 배포는 사용자가 명시적으로 요청할 때만 수행합니다.

impl/keybuddy/intent-harness-before-after.md → docs/intent-harness-before-after.md

@@ -1,5 +1,8 @@
 # 의도 하네싱 전/후 비교 (AC8 정성 리포트)
 
+> **상태: 미연결 클라이언트 설계의 검증 리포트.** 이 비교는 현재 배포 추천 경로(Supabase + OpenAI)가 아니라
+> 앱에 미연결된 클라이언트 의도 하네싱 설계를 대상으로 한다. 배경은 루트 `AGENTS.md`와 [`tag-extraction-flow.md`](tag-extraction-flow.md) 참조.
+
 평면 추출(의도=평면 소프트 태그, 점수만)과 의도 하네싱(의도->차원별 강도, 필수=하드 승격)을 대표 쿼리 10개로 비교한다. 추출값은 결정론적으로 고정(LLM 미사용).
 
 핵심 지표 = **BEFORE 상위 5개 중 의도 필수 차원 위반 수**(예: 사무용->저소음 필수인데 시끄러운 기계식이 상위에 노출된 건수). AFTER는 필수를 하드 필터로 승격하므로, 완화가 일어나지 않은 한 0이 된다. 필수끼리 모순돼 완화된 경우에만 완화된 필수에 대한 위반이 남으며 이는 설계상 의도된 동작이다(무결과 대신 근접 제시).

docs/knowledge/.gitignore

@@ -0,0 +1,4 @@
+# 훅 활성화 시 생성되는 런타임 파일 (커밋 대상 아님)
+.extract-state
+.nudge-stamp
+extract.log