[3주차 크루 미션 - 개발 중반 & 중간 공유] ellipsis 미션 제출합니다.#14
Conversation
다나와 크롤러 데이터 기반 키보드 추천 웹앱(Vite+React+TS) 이관. node_modules/dist/.env.local 등 빌드 산출물과 실제 키 파일은 제외하고 .env.local.example만 포함. README 경로를 impl 기준으로 갱신.
추천 정확도 저하(제약 무시·의도 빗나감)를 고치기 위한 태그 파이프라인 전환 요구사항을 Seed로 명세. LLM은 태그 추출만, 검색/스코어링/결과는 빌드 시 1회 생성한 정적 규칙표로 결정론 처리. 하드 제약 위반 0건 단위테스트 + 의도 골드셋으로 검증. (ooo interview/seed, fallback QA 0.92)
- tagSchema.ts: HARD_NUMERIC_KEYS, HARD_ENUM_KEYS, HARD_CONSTRAINT_KEYS, HARD_CONSTRAINT_ENUMS, SOFT_INTENT_VOCAB 상수 정의 및 export - isSoftIntentTag / isHardConstraintKey / isValidHardEnumValue 런타임 검증 헬퍼 포함 - tagSchema.test.ts: 28개 단위 테스트 (키 목록, 열거형 값, 중복 없음, 헬퍼 동작 검증) - vitest devDependency 추가, npm test 스크립트 설정
스키마 상수 기반으로 임의 객체의 태그 스키마 준수 여부를 검증하는 validateTagSchema 함수 구현. - 최상위 알 수 없는 키, hardConstraints 미지원 키, 열거형 허용 외 값, 숫자 키 타입 오류, softIntentTags 어휘 외 값 감지 - 복수 오류 한 번에 수집하는 방식으로 구현 - 유효/무효 케이스 총 20개 단위 테스트 추가 (전체 47개 통과)
자유형 자연어를 LLM에 전달해 hardConstraints + softIntentTags 구조의 ExtractedTags를 반환하는 extractRawTags() 함수를 구현한다. - extractRawTags.ts: AnthropicClient 주입 구조로 테스트 격리 지원, 스키마 밖 키/값은 parseAndSanitize에서 폐기, 비정상 JSON 안전 처리 - extractRawTags.test.ts: LLM 호출을 _setClientForTest로 모킹, hardConstraints/softIntentTags 키 존재 확인, 스키마 외 값 폐기 등 19개 테스트
extractRawTags의 출력(unknown)을 받아 스키마 밖 키/값을 제거하고 정제된 ExtractedTags를 반환하는 sanitizeTags(raw: unknown) 구현. - 최상위 hardConstraints/softIntentTags 외 키 무시 - HARD_CONSTRAINT_KEYS 밖 hardConstraints 키 제거 - 열거형 키의 HARD_CONSTRAINT_ENUMS 밖 값 제거 - 숫자 키에 number 외 타입 값 제거 - SOFT_INTENT_VOCAB 밖 softIntentTags 항목 제거 - 비정상 입력(null/배열/문자열) 안전 처리 - 알 수 없는 키 제거 / 잘못된 열거형 폐기 / 유효한 값 보존 검증 27개 테스트 추가 (전체 93개 통과)
- extractRawTags -> sanitizeTags -> validateTagSchema 순서 파이프라인을 실행하는 extractAndValidateTags(input: string) 함수를 extractRawTags.ts에 추가 - validateTagSchema 실패 시 오류를 throw하도록 구현 - sanitizeTags가 스키마 밖 값을 폐기하므로 정상 조건에서 항상 유효한 출력 보장 - extractRawTags.ts의 tagSchema 임포트에 validateTagSchema 추가 - extractAndValidateTags.test.ts: LLM 모킹으로 23개 통합 단위 테스트 추가 (정상 응답, 스키마 밖 값 폐기 후 통과, 비정상 JSON 안전 처리, 출력 구조 보장)
- src/lib/hardFilter.ts: 레이아웃 하드 제약 위반 판정 함수 구현 - layoutTag 없음(빈 문자열) -> false(제약 없음) - keyboard.layout과 layoutTag 일치 -> false(통과) - 불일치 -> true(위반) - src/__tests__/hardFilter.test.ts: 17개 단위테스트 - 6개 레이아웃 값 일치 케이스(false) - 8개 불일치 케이스(true) - 3개 제약 없음 케이스(false) - 전체 테스트: 133개 통과 (기존 116개 + 신규 17개)
- softTagRules.ts: SOFT_INTENT_VOCAB 24개 태그 전체를 커버하는 정적 규칙표 생성 - 태그별 AttributePredicate(field/op/value) 술어 매핑 - checkRuleTableCompleteness 함수 구현 - softTagRules.test.ts: 19개 단위 테스트 추가 - 정적 규칙표 구조 무결성 검사 (7개) - 현재 규칙표 완전성 검증 - 누락 0건 확인 (2개) - 누락 태그 감지 시나리오 (6개): 빈 규칙표/특정 태그 누락/predicates 빈 배열 - 경계 케이스 (3개): 빈 vocab/중복 엔트리/순서 보장 전체 152개 테스트 통과 (기존 133개 + 신규 19개)
hardFilter.ts에 checkSwitchViolation(keyboard, switchTag) 함수 추가. 일치->false, 불일치->true, 빈 문자열->false(제약 없음) 케이스 18개 테스트.
guidedInputMapper 모듈을 추가하고 단위 테스트 51개 작성. LLM 호출 없이 결정론적으로 동작하는 순수 함수로 구현: - mapBudgetToConstraints: 예산 범위 -> price_min/price_max - mapConnectionToConstraints: 연결방식 선택지 -> connection/wireless_type - mapLayoutToConstraints: 크기 선택지 -> layout (매핑 불가 선택지는 하드 제약 미생성) - mapEngravingToConstraints: 각인 선택지 -> engraving - mapBacklightToConstraints: 백라이트 선택지 -> backlight - mapKeyFeelToConstraints: 키감 선택지 -> switch_type - guidedAnswersToHardConstraints: 전체 answers+budget 통합 변환 전체 테스트 221개 통과
폼팩터 하드 제약 위반 판정 함수(checkFormFactorViolation)를 hardFilter.ts에 추가하고, 19개 단위테스트를 작성했다. - 일치 시 false(6케이스), 불일치 시 true(9케이스), 태그없음 시 false(4케이스) - 전체 테스트 240개 통과 (기존 221개 + 신규 19개)
Sub-AC 3-2-a: extractDatasetSchema(keyboards) 함수 추가 - Keyboard[] 입력 -> Record<속성명, Set<값>> 반환 - getFieldValues / hasField / hasValue 헬퍼 함수 포함 - 단위 테스트 39개 작성 (빈 배열, 속성명 목록, 값 추출, 중복 제거, 실제 샘플 검증 등) - 전체 279개 테스트 통과
- hardFilter.ts에 checkBudgetViolation(keyboard, budgetTag) 추가 - budgetTag <= 0: 제약 없음으로 간주하여 false 반환 - keyboard.price > budgetTag: 위반(true) - keyboard.price <= budgetTag: 통과(false), 경계값 포함 - hardFilter.test.ts에 13개 테스트 케이스 추가 - 가격 < 상한, 가격 = 상한(경계값), 가격 > 상한, budgetTag <= 0 시나리오 포함 - 전체 292개 테스트 통과
- datasetSchema.ts에 findInvalidFieldNames 함수 추가 - 규칙표 술어의 모든 field 이름 수집 후 스키마 맵과 대조 - 스키마에 없는(무효) 속성명을 중복 없이 반환 - PredicateRuleEntry 제네릭 인터페이스로 순환 의존 없이 SoftTagRuleEntry 호환 - datasetSchema.test.ts에 findInvalidFieldNames 단위 테스트 9건 추가 - 모두 유효: 빈 배열 반환 검증 - 모두 무효: 전체 반환 검증 - 유효/무효 혼재: 무효 속성명만 정확히 탐지 - 중복 field: Set 기반 중복 제거 보장 - 빈 규칙표/빈 스키마 경계 케이스 처리 - 전체 테스트 301개 통과 (기존 292개 + 신규 9개)
- guidedInputMapper에 소프트 태그 전용 상수 추가 (PURPOSE_OPTIONS, PORTABILITY_OPTIONS, SOUND_OPTIONS, KEY_FORCE_OPTIONS) - 소프트 전용 단계 매핑 함수: mapPurposeToSoftTags, mapPortabilityToSoftTags, mapSoundToSoftTags, mapKeyForceToSoftTags - 하드 제약 단계의 소프트 태그 보완 함수: mapKeyFeelToSoftTags, mapLayoutToSoftTags, mapConnectionToSoftTags, mapBacklightToSoftTags, mapEngravingToSoftTags - guidedAnswersToSoftTags 통합 함수 (중복 제거 포함) - guidedSoftTagMapper.test.ts: 소프트 태그 매핑 단위 테스트 75개 추가 - 모든 매핑 함수는 LLM 호출 없는 동기 순수 함수, 전체 376개 테스트 통과
- HardTag 타입 정의: type(판별자) + value(제약값) 구조 - checkHardConstraintViolation 함수 구현: - 'layout' -> checkLayoutViolation (Sub-AC 4-1-1) - 'switch_type' -> checkSwitchViolation (Sub-AC 4-1-2) - 'form_factor' -> checkFormFactorViolation (Sub-AC 4-1-3) - 'price_max' -> checkBudgetViolation (Sub-AC 4-1-4) - 알 수 없는 유형 -> false (안전한 기본값) - 디스패처 단위테스트 추가 (6개 describe, 30개 케이스): 라우팅 정확성, 직접 호출과의 결과 동일성, 알 수 없는 유형, 복합 시나리오
- datasetSchema.ts에 findRulesWithInvalidValues 함수 추가 - 속성명이 스키마에 존재하는 경우에 한해 허용 값 집합 밖 값을 참조하는 규칙 반환 - eq 술어: 스키마 값 집합에 정확히 포함되는지 검사 - contains 술어: 스키마 값 중 하나라도 부분 문자열로 포함하는지 검사 - lte/gte 술어: 수치 비교 임계값이므로 검사 대상에서 제외 - 속성명이 스키마에 없으면 해당 술어는 검사 범위 아님(findInvalidFieldNames 담당) - PredicateWithValue, RuleEntryWithValues 제네릭 인터페이스 추가 - datasetSchema.test.ts에 19개 단위 테스트 추가 (총 421개 통과)
keyboards 배열과 hardTags 배열을 받아 모든 하드 제약을 만족하는 키보드만 반환하는 filterByHardConstraints 함수 구현 (Sub-AC 4-2). - hardFilter.ts: filterByHardConstraints 추가 (checkHardConstraintViolation 기반) - hardFilter.test.ts: filterByHardConstraints 단위테스트 5개 describe 블록 추가 - 빈 태그 배열 / layout 단일 / price_max 단일 / 복합(layout+price+switch) / violations===0 보장 - 전체 테스트 434개 통과 (기존 401개 + 신규 33개)
- TagSet 인터페이스 추가 (hard: HardConstraints, soft: SoftIntentTag[])
- dispatchStepToTagSet(stepIndex, value): 0-9 단계 번호와 선택값을 받아
하드/소프트 매핑 함수에 라우팅하고 TagSet 반환
- STEP_ID_TO_INDEX 테이블 및 dispatchStepIdToTagSet 헬퍼 추가
- 예산 단계(7)는 { min, max } range 입력, 나머지 string 입력 처리
- 타입 불일치/알 수 없는 단계 -> { hard: {}, soft: [] } 안전 반환
- LLM 호출 없이 결정론적 동작
- 10단계 전체 시나리오 단위 테스트 (stepDispatcher.test.ts) 추가
- 전체 511개 테스트 통과
하드 제약 필드 누락/타입 오류/소프트 의도 필드 누락 케이스를 명시적으로 커버 - hardConstraints: null, [], string 타입 오류 검증 - price_min 숫자/문자열 검증 - softIntentTags: null, 숫자 요소, null 요소 검증 - 각 필드 누락 시 상대 필드 오류 미발생 확인 tagSchema.test.ts: 47 -> 57개 테스트 (전체 521개 통과)
… 테스트 작성
- guidedInputMapper에 selectionOptionConverter 함수 추가
- guidedAnswersToHardConstraints + guidedAnswersToSoftTags를 ExtractedTags 인터페이스로 통합
- 자유형 자연어 경로(extractRawTags)와 동일한 { hardConstraints, softIntentTags } 반환
- LLM 호출 없이 결정론적으로 동작
- selectionOptionConverter.test.ts 신규 작성 (Sub-AC 2-2b)
- 출력 구조 보장: hardConstraints(객체) + softIntentTags(배열) 항상 존재
- validateTagSchema 통과 검증: 빈/부분/전체 입력 + 대표 시나리오 8개
- 하드 제약 단계 단일 입력 15케이스 스키마 통과 확인
- 소프트 전용 단계 7케이스 스키마 통과 확인
- 예산 입력 4케이스 스키마 통과 확인
- softIntentTags 항목이 모두 SOFT_INTENT_VOCAB에 속함 검증
- 결정론성: 동일 입력 -> 항상 동일 출력
- LLM 호출 없는 동기 순수 함수 확인
전체 583개 테스트 통과
선택 변환 태그(selectionOptionConverter)와 자유형 태그(sanitizeTags 시뮬레이션)가 동일한 하드 제약을 표현할 때 filterByHardConstraints 결과가 일치함을 검증하는 24개의 단위 테스트를 작성한다. - layout(텐키리스/미니/풀배열) 단일 제약 동일성 검증 - switch_type(기계식/무접점) 단일 제약 동일성 검증 - price_max 단일 제약 동일성 검증 - 복합 제약(layout + switch_type + price_max) 동일성 검증 - 빈 제약, 불가능한 제약(결과 0건) 경우 검증 - 소프트태그 차이가 하드 필터 결과에 영향 없음 검증 - 1800배열 선택 시 layout 하드 제약 없음 동일성 검증 - 8개 시나리오 테이블 기반 통합 검증 - hardConstraintsToHardTags 변환 헬퍼를 테스트 내부에 정의 - 모든 결과에서 violations === 0 단언 포함
- softScorer.ts: SOFT_TAG_RULE_TABLE 기반 결정론 스코어링 함수 구현
- evaluatePredicate: 속성 술어 평가 (eq/contains/lte/gte)
- scoreBySoftTags: 키보드별 점수 벡터 산출 (LLM 없이 순수 함수)
- deriveRankOrder: 점수 벡터 -> 순위 배열 변환
- softScoreParity.test.ts: 40개 단위 테스트 추가
- 선택 경로(guidedAnswersToSoftTags) 소프트태그와
자유형 경로(sanitizeTags 시뮬레이션) 소프트태그를
scoreBySoftTags에 전달했을 때 스코어 벡터가 일치하는지 검증
- 7개 의도 시나리오: 사무용+조용함, 게이밍+RGB, 무선+미니+휴대성,
기계식+타건감+경쾌함, 무접점+조용함, 가성비+풀배열, 복합 전체 단계
- 결정론성, 태그 순서 무관 점수 동일, 순위 배열 일치 검증
- 전체 647개 테스트 통과
There was a problem hiding this comment.
ai agent를 언제든지 다른 것으로 교체했을 때 문제가 없게끔 호환이 되도록 구성해보세요.
팀원들이 claude를 쓰던 codex를 쓰던, 또 다른ai 를 사용하던 문제가 없게끔이요.
또, ai로 기획과 이 프로젝트에 대한 SSOT 로 사용할 docs도 잘 쌓아보세요.
사람에게 컨텍스트를 의존시키지 말도록 만들어보세요.
모든 컨텍스트는 이 레포에 스냅샷 떠져있다고 생각하고 만들어보세요.
그 누가 유지보수하더라도 문제 없게끔이요. 이렇게 프로젝트를 처음 시작하는 경우는 이제 점점 사라지게될거예요. 그러한 ai-native로의 경험, 하니스를 처음 구축해보는 경험은 어디에서도 할 수 없어요.
지금은 바쁘니까 나중에 해야지라는 생각이 드시죠.
일을 하시게 되면 항상 시간은 부족해요. 뭘 더 추가할 시간도 없는데 일단 해야지.
그러다 보면 일을 많이 하더라도 나에게 남는 게 없게 돼요.
결국 플러스 알파를 챙기려면 내가 시간을 더 내어서 하는 수 밖에는 없어요. ai 활용능력은 지금 IT 세계에서 너무나도 필수가 되어가고 있어요. 꼭 ai를 더 잘 활용하려는 시도를 해보셨으면 좋겠어요.
There was a problem hiding this comment.
저희도 클로드(아오), 코덱스(조디악, 투핸더)로 나뉘어져 있어서 이러한 문제가 더 큰 것 같습니다.
GPT 5.5 모델이 나오고 클로드 코드보다 더 나은 성능을 보이기도 했고 최근 클로드 서버가 불안정하여 클로드 코드가 먹통이 되기도 하는 등 하나의 모델이나 에이전트에 종속되지 말아야 한다는 생각이 많이 들었습니다.
다른 프로젝트에서도 이 부분에 대해서 고민해보고 결론낸 적이 있었습니다. claude를 쓰던 codex를 쓰던 에이전트 중립적으로 개발되어야 한다고 생각합니다. 사람이 컨텍스트를 들지 않기 위해서는 에이전트에 컨텍스트를 잘 제공되어야 한다고 생각합니다. 클로드 기준으로 기술 docs나 README.md, CLAUDE.md, 스킬, agent.md 등을 통해서 공통의 컨벤션을 에이전트가 잘 따르도록 작성해야 합니다.
그러나, 모든 기술 docs나 스킬, 에이전트를 공유할 필요는 없다고 생각합니다. 결국 공통으로 사용하고자 해도 다른 개발자가 요구하는 방식과 공통으로 제공한 문서의 방식은 다르기에, 각 개발자가 특화하여 스스로 만들어야 한다고 생각합니다.
그렇기에 공통으로 사용할 만한 문서들은 README.md, AGENTS.md, feature를 개발하기 위해 적용한 방식 문서, PR Description, 컨벤션 문서, 유틸성 스킬정도 라고 생각합니다.
클로드는 CLAUDE.md를 사용하지만, 코덱스는 AGENTS.md를 사용하기에 모델별로 다른 문맥을 이해할 가능성이 있다고 생각합니다. 그렇기에, ln -s AGENTS.md CLAUDE.md를 통해 AGENTS.md에 문맥들을 작성하되 클로드에서도 똑같이 사용할 수 있도록 심볼릭 링크를 걸어 SSOT를 달성하려고 합니다.
아직, 공유할 기술 docs와 공유하지 않아도 괜찮은 docs를 잘 구분하진 못했지만, 기술 docs를 남기는 스킬을 만들었고 생성해낸 docs를 읽어보고 공유를 선택해보겠습니다.
There was a problem hiding this comment.
Agent.md 로 공용화하는 게 낫다는 생각이 들어요.
또는 claude.md나 agent.md에서 그냥 단순하게 내용을 반드시 ""파일을 본다. 모든 에이전트가 같은 지침을 보기 위함이다. 이런 한두줄만 적어두고 관리하는 방법도 있겠어요.
누구든 이 레포에 기여할 때, 레포를 처음 만든 사람이 원하는 큰 그림대로 코드를 작성하고 철학이 담겨있게끔 만들도록 하니스를 구축해두는 것도 중요한 일이라 생각해요. 아주 상세한 부분들은 다를 순 있어도 가장 큰 가지의 방향정도는 자동으로 맞출 수 있게끔이요.
| ### 결과 | ||
|
|
||
| - 효과: 추천이 좀 더 정확해짐(정성적 판단) | ||
|
|
There was a problem hiding this comment.
추천이 좀 더 정확해졌다는 것을 정량적으로 판단하도록 만들어보세요.
판단의 축을 만들고, 몇점정도의 정확도인지를 점수로 매겨볼 수 있도록 구성해보세요.
llm의 결과물을 평가하는 시스템을 만들어보세요. rubric등을 검색하면 여러가지가 나올거예요.
정량적 판단을 할 수 있게 되면 뭐가 좋을까요?
그저 점수만 나오니까?
많은 것들을 시도해볼 수 있어요. 뭘 할 수 있을지 고민해보시면 좋겠어요.
There was a problem hiding this comment.
먼저 우리의 키보드 추천 결과가 정확해졌는지를 정량적으로 판단하기 위한 채점표로써
제안해주신 “Rubric 채점표”에 대해서 살펴보았습니다.
Rubric
평가의 여러 항목에 대해서 명확한 수준을 정의하고, 각 항목이 어떤 성취도를 나타내는지를 설명하는 표의 형태로 제공됩니다. 이를 통해서 평가자는 학생의 수행을 객관적이고 체계적으로 평가할 수 있으며, 학생은 자신이 어떤 기준에 따라 평가받는지 명확히 이해할 수 있습니다.
ex) “보고서 작성 능력”을 평가할 때 포함할 수 있는 기준
내용의 완전성: 주제를 충분히 다루었는가?
- 4점: 주제를 깊이 있게 다루었으며, 관련된 모든 세부 사항이 잘 포함되어 있다.
- 3점: 주제를 적절히 다루었으나, 일부 세부 사항이 부족하다.
- 2점: 주제를 부분적으로 다루었으며, 많은 세부 사항이 빠져 있다.
- 1점: 주제를 거의 다루지 않았으며, 핵심적인 내용이 부족하다
논리적 전개: 글의 전개가 논리적인가?
- 4점: 내용의 흐름이 매우 논리적이며, 모든 문장이 자연스럽게 연결된다.
- 3점: 내용의 흐름이 대체적으로 논리적이나, 일부 연결이 부자연스럽다.
- 2점: 내용의 흐름이 다소 불명확하며, 논리적인 전개가 부족하다.
- 1점: 내용의 흐름이 혼란스럽고 논리성이 거의 없다.
이러한 방식을 바탕으로 저희의 추천 결과의 정확성을 판단하고자 기준을 세우고 점수를 매겨 보았습니다.
-
의도 추출 정확도
사용자의 자연어에서 하드 제약과 소프트 의도를 제대로 뽑았는지 본다.
-
추천 목록 정확도
최종 상위 3개의 제품이 조건과 의도에 맞는지 확인하도록 한다.
-
설명 품질
추천 이유가 제품 정보에 근거하고, 사용자의 조건과 연결되어 있는지 확인한다.
| 축 | 배점 | 판단 기준 |
|---|---|---|
| 하드 제약 충족 | 30점 | 예산, 배열, 연결방식, 스위치 등 명시 조건을 상위 결과가 위반하지 않는가 |
| 의도 적합도 | 25점 | 사무용이면 저소음, 휴대용이면 가벼움, 게이밍이면 기계식/RGB 등 의도에 맞는가 |
| 상위 랭킹 품질 | 15점 | 1~3위 제품이 특히 좋은 추천인가 |
| 설명의 근거성 | 15점 | 추천 이유가 실제 제품 속성과 일치하는가 |
| 폴백 처리 | 10점 | 불가능한 조건일 때 조건 완화를 명확히 하고 근접 결과를 주는가 |
| 다양성 | 5점 | 상위 결과가 같은 브랜드/비슷한 제품으로만 도배되지 않는가 |
이 점수를 실제로 사용한다면
- 대표적인 쿼리를 고정한다.
- “조용한 사무용 15만원 이하”,”게이밍 RGB 텐키리스”,”가벼운 무선 키보드”처럼 대표 질의 10개를 정해둔다.
- 매번 같은 기준으로 상위 3개를 채점한다.
- 프롬프트, 모델, 추천 로직이 바뀔 때마다 같은 쿼리셋으로 점수를 매긴다.
- 평균 점수뿐만 아니라 낮은 축을 본다.
- 예를 들어 평균은 올랐지만 “다양성”이 낮아졌다면 같은 브랜드가 너무 많이 노출되는 문제를 발견할 수 있다.
이러한 방식으로 사용할 수 있을 것으로 보입니다.
정량적 판단을 할 수 있게 된다면 무엇을 할 수 있을까 고민하여 보았는데
- “이번 PR은 기존의 평균 82점에서 87점으로 개선”처럼 설명할 수 있게된다.
- 프롬프트 변경 전후의 추천 품질 향상을 비교할 수 있다.
- LLM 모델 변경 전후의 품질을 비교하여 살펴볼 수 있다.
라고 생각하였습니다.
There was a problem hiding this comment.
결과를 채점하는 하니스도 한 번 만들어서 실제로 llm이 생성하는 결과물만 딱 떼어놓고 테스트할 수 있도록 시스템도 한 번 만들어보세요.
이렇게 점수화가 어느정도 된다면, 비용이나 속도 문제로 모델을 바꿨을 때, 어디까지 모델 버전을 떨어뜨려도 괜찮은지에 대한 지표로도 활용할 수 있겠어요.
| 5. 기능추가 | ||
| 1. 타건음 영상 → 플레이스 홀더로 대체 | ||
| 2. 스토어 링크 → 플레이스 홀더로 대체 | ||
| 6. 피드백 받기 | ||
| 1. 구매하기 버튼 | ||
| 1. MOCK으로 구현, 토스트만 출력되게 | ||
| 2. 매칭 결과 피드백(1~5점) | ||
| 1. MOCK으로 구현, 슈퍼베이스 연결 안됨 |
There was a problem hiding this comment.
기능 추가를 결국 다 못했다는 것 같은데요.
플레이스홀더로 대체가 어떤 의미인가요?
슬랙 채팅으로 제가 정말 다 할 수 있겠냐고 했는데도 그렇다 라고 하셨는데...
이젠 정말 다시 진지하게 고민해보세요. 집중해서 기능을 개발해야하니까요.
기능 다 개발 못하면 우테코 짤린다고 생각하고 계획하고 개발해보세요.
There was a problem hiding this comment.
말씀해 주신 것처럼 실제 리뷰 영상 링크 수집은 아직 진행하지 않았습니다. 다만 리뷰 영상 제공 기능의 실현 가능성을 확인하기 위해, 유튜브에 해당 제품의 타건 및 리뷰 영상이 존재하는 비율의 분석을 진행하고 있었습니다.
현재까지의 분석 결과는 다음과 같습니다.
| 기준 | 고유 제품명 356개 | 전체 레코드 600개 |
|---|---|---|
| 제목에서 타건·리뷰 영상임이 명확한 경우 | 285개, 80.1% | 498개, 83.0% |
| 제품 관련 영상 링크가 발견된 경우 | 317개, 89.0% | 545개, 90.8% |
| 영상 링크를 찾지 못한 경우 | 39개, 11.0% | 55개, 9.2% |
분석 결과, 약 90%의 제품에서 관련 영상 링크를 찾을 수 있어 충분히 실현 가능한 기능이라고 판단했습니다. 현재는 유튜브 영상 링크를 수집하기 위한 크롤러를 설계하고 있습니다.
수집한 영상은 iframe 등의 영상 플레이어를 활용해 사용자가 서비스 화면을 벗어나지 않고 리뷰와 타건 영상을 시청할 수 있도록 제공할 계획입니다.
| - 이전 : 자연어 + 키보드 데이터베이스 → LLM 콜 | ||
| - 추천이 부정확했음, 사무용인데 시끄러운 키보드를 추천 | ||
| - RGB 백라이트가 필요없다고 했더니 RGB 백라이트가 있는 키보드를 추천함 | ||
| - 현행 : 자연어 → LLM 통하여 태그 추출 → 태그 기반 검색 | ||
| - 추천이 정확해졌음, 사무용은 조용한 축을 가진 키보드를 추천함 | ||
| - RGB 백라이트가 필요 없다고 하는 자연어를 통해 “백라이트 없음”이라는 하드 제약을 만들어서 태그 기반 검색에 활용함 | ||
| - 정량화 기준이 없었음, 사용자 반응에 의존하는 정성적 검증 방법으로 정확한가를 거르기 어려웠음 |
There was a problem hiding this comment.
방법을 바꾼 이유가 무엇인가요?
"이전이 구려서" 라는 말을 원하는 게 아니에요.
어떤 판단을 바탕으로 이전 에서 현행으로 방법이 변경된건가요?
There was a problem hiding this comment.
이전에, “사무용" 키보드를 추천 받았는데 “백라이트”가 존재하고 “소음”이 상관없는 키보드로 해석되어 청축 키보드를 추천하는 경우가 많았습니다. 제 기준에서 사무용이라면, 백라이트가 없고 소음이 적은 키보드여야 한다고 생각했습니다.
여기에서 더 확장해서, “사무용”, “게이밍용”만이 아니라 특정 태그에 대해서 규칙이 필요하다고 판단했습니다. 그래서, 메인에 있는 세가지 입력건에 대해 규칙을 적용했습니다.
지금은 위 3가지에 한해서는 제대로 돌아감을 확인했습니다. 다만, 아직 이 규칙이 많은 경우를 커버하지는 못한다고 생각하여 규칙을 더 확장하려고 합니다. 그래도 현행 추천 알고리즘은 MVP 단계에서는 충분하다고 판단했습니다.
There was a problem hiding this comment.
골든 케이스를 많이 만들어보는 것도 ai 생성물에 대한 평가 질을 높일 수 있는 방법이 되겠네요.
There was a problem hiding this comment.
ai가 모든것을 스스로 생각하고 학습하고 결과를 내놓게 해볼 수도 있지만,
프롬프트에 ai에게 어느정도의 지침을 넣어둔다면 좀 더 원하는 방향대로 끌고 나갈 수도 있겠어요.
청축과 사무용이 어울린다는 생각을 키보드를 조금 아는 사람들이라면 못할테니까요. 사무용이라면 어떠어떠한 것들을 봐라. 라는 지침을 넣어볼 수도 있고, 다른 여러가지 방법들도 나올 수 있겠어요.
| | 키보드 카테고리 대상 약 100개 제품 데이터 크롤링 및 수집 | 다나와에서 데이터 600개 수집하여 데이터베이스로 활용 | | ||
| | 수집 데이터 및 프로토타입 기반 작동 가능한 웹 페이지 구현 | Gemini Canvas로 제작한 프로토 타입을 클로드 코드로 작동하도록 구현 | |
There was a problem hiding this comment.
왜 600개인가요?
600개이면 충분한가요? 이전엔 왜 100개로 잡았나요?
더 많이 혹은 더 적게 수집하지 않은 이유는 무엇인가요?
There was a problem hiding this comment.
이전엔 “LLM이 주어진 데이터에서 추천이 가능한지”를 검증하하즌 목적이 커서 100개의 데이터만 넘겼습니다. 100개 보다 더 많이 넣을 수 있었겠지만 그렇게 하면 LLM 콜 비용이 폭증할거라 판단해 100개만 삽입하였습니다.
100개의 데이터와 사용자 입력문을 LLM 콜에 넣고 LLM이 실제로 주어진 데이터에서 추천이 가능하다고 판단했습니다. 그런데, 키보드 추천 결과가 사용자의 입력문과 달리 나오고 동일한 입력문에도 다른 결과가 나와서 추천 결과가 부정확하다고 판단했습니다.
처음에는 데이터가 부족하여 LLM이 추천할 데이터가 부족하다고 생각해서 500개를 추가했습니다. 다나와에서 데이터를 크롤링하기에 너무 많은 숫자를 수집하면 차단 당할 위험이 있다고 생각해서, 500개만 시도했습니다. 그런데, 500개를 추가해도 처음과 결과는 다르지 않고 LLM 콜 비용은 폭증해서 이 방법 역시 적절치 않다고 생각했습니다.
그래서, 추천 알고리즘을 바꾸고 추천 정확도가 올라감을 확인하고 데이터 수는 600개로 남겨뒀습니다.
현행 구조에서는 데이터를 더 추가해도 LLM 콜 비용이 폭증하지도 않기에 데이터를 더 추가해도 괜찮다고 생각합니다. 한편으로, 정량적 분석 방법이 없어 이 정도의 데이터 규모만으로 추천의 정확도가 올바른가?는 미확정 상태입니다.
다만 추천 결과에서 저희가 의도한 정보를 사용자에게 제공하기 위해 키보드 데이터 수집 시 기계식, 광축, 자석축이 장착된 키보드의 경우 스위치 정보를 필수로 수집하는 방향으로의 수정을 고려중입니다.
맴브레인, 팬타그래프, 무접점의 경우 어느정도 일관된 타건감을 제공한다고 판단했습니다. 따라서 기계식 스위치, 광축, 자석축의 경우 스위치를 제조한 제조사 정보를 확인해 해당 제조사의 공식 PDF 자료를 활용해 스위치의 타입에 따른 타건감 정보를 제공 할 생각입니다.
현제 수집되어 있는 키보드 데이터에서 기계식, 광축, 자석축이 장착된 키보드 중 스위치 제조사 정보를 확인할 수 있는 비율은 다음과 같습니다.
| 접점 방식 | 전체 | 제조사 값 있음 | 비율 |
|---|---|---|---|
| 기계식 | 458 | 228 | 49.8% |
| 광축 | 30 | 25 | 83.3% |
| 자석축 | 18 | 4 | 22.2% |
| 합계 | 506 | 257 | 50.8% |
수집된 데이터 중 94개가 맴브레인, 팬타그래프, 무접점에 속하며
기계식, 광축, 자석축 중에도 스위치 제조사 정보를 확인할 수 있는 데이터가 257개가 됩니다.
따라서 제조사 정보를 확인 가능한 키보드에 대해서만 우선적으로 추천 데이터로 활용할 경우 키보드 추천에 활용할 수 있는 데이터의 개수가 351개 정도가 됩니다.
따라서 스위치 제조사를 확인할 수 있는 키보드만 추천 데이터로 활용해도 현재로써는 데이터가 충분할 것이라 판단해 스위치 제조사를 확인할 수 있는 키보드에 대해서만 추천을 진행하는 방향을 고려중에 있습니다.
맴브레인, 팬타그래프, 무접점방식의 경우 대부분의 제품에서 어느정도 일관된 타건감을 제공한다고 판단해 맴브레인, 펜타그래프 → “구분감”, 무접점 → “부드러움” 의 키감으로 매핑해 키감 정보를 제공할 생각입니다.
추가로 데이터를 수집해 600개를 다시 맞추는 방향도 고려를 해보았으나, 이 이후로 상품을 추가 조사할 경우 해당 키보드에 대한 수요가 별로 높지 않아 사용자의 만족도를 낮출 수 있다는 생각이 듭니다.
다만 이 또한 명확한 기준을 세우고 “인기순으로 정렬한 데이터에서 상위 600개의 키보드는 수요가 있을 것”이라는 것에 대한 검증이 이뤄진 것이 아닌, 단순히 “순위가 낮다는 것은 수요가 없다는 것을 반증한다.”라고 판단한 것 이기에 적절한 판단이라고 확신은 할 수 없는 상황입니다.
| 2. LLM 추천 결과가 부족하게 오거나 잘못된 인덱스를 반환할 경우, 어디까지 fallback으로 채워야 하는지 명확히 정해야 했습니다. 이 처리가 불안정하면 사용자가 빈 결과나 잘못된 추천을 받을 수 있다고 판단했습니다 | ||
|
|
There was a problem hiding this comment.
프롬프트가 빈약했던 건 아닐지요.
정말 원하는 결과를 정확하게 뽑아낼 수 있는 형태의 프롬프트였나요?
There was a problem hiding this comment.
기존에는 LLM이 잘못된 인덱스를 반환하거나 추천 개수가 부족할 때 fallback으로 어떻게 보완을 할 수 있을지를 고민하였었는데 피드백을 받은 후에 다시 고민해봤을 때에는 이는 실패 이후의 처리를 하는 것에 더 가깝고, 더 먼저 점검해야할 사항은 LLM이 애초에 원하는 결과를 반환할 수 있도록 프롬프트를 충분히 구체적으로 작성하였는지였습니다.
이에 따라 후보 목록 안에서만 추천할 것, 존재하지 않는 인데스를 반환하지 않을 것, 사용자 조건과 제품 속성을 연결해 추천 이유를 작성해줄 것, 추천 개수가 부족하다면 임의로 지어내지 말 것 등을 프롬프트에 명확히 포함시켜주어야 한다는 생각이 들게 되었습니다. fallback은 프롬프트를 강화한 이후에도 발생할 수 있는 예외 상황을 보완하는 안전장치로 두는 것이 적절하다고 판단하였습니다.
There was a problem hiding this comment.
출력 스키마 폼을 미리 확정해서 정해두고, 그 필드에 대한 설명을 적고, 그 필드들을 ai에게 채우라고 하는 것도 하나의 방법이겠어요.
json 형태로 뽑는다면, llm 결과물인 json에 값이 비어있거나 invalid한 경우 코드로 필드를 확인하고 디폴트 값을 채워넣는 것도 가능하니까요.
이 방법이 정답이란 말은 아니라는 것 아시죠?
| 1. 출처마다 스위치 표기가 달라 별칭 테이블만으로는 모든 데이터를 매핑하기 어렵고, 일부 키보드의 걸림 정도와 소음 수준을 제공하지 못하고 있다. 기존 매핑 구조의 유지 여부와 미매핑 데이터 처리 및 별칭 수집·검증 방법에 대한 결정이 필요하다. | ||
| 1. 별칭 테이블: 데이터 출처마다 다르게 표기된 스위치 이름을 단일화 하기 위해 제작한 스위치 별 별칭 모음 | ||
| 2. 별칭 테이블이 정말로 필요한 구조인지 의문 |
There was a problem hiding this comment.
스위치 표기가 다르다는 건 어떤 문제인가요?
체리 청축인데 하늘축 뭐 이런식으로 판다는 뜻인가요?
체리축의 특허가 만료돼서 이제는 아무나 맘대로 만들 수 있게 된 것으로 알고 있어요. 그래서 이젠 대 춘추전국 시대일 것이라 생각하는데.. 요오즘 정보는 제가 잘 몰라서 조심스럽군요
There was a problem hiding this comment.
스위치 별칭 테이블이 도입된 이유부터 설명을 해드리겠습니다.
각 스위치의 타건감을 스위치 내부 구조에 따라 리니어 → 부드러움, 택타일 → 걸림감, 클릭 → 클릭감으로 일반화해 제공하고자 했습니다.
이 방식을 적용하기 위해선 기계식 키보드에 장착된 스위치의 이름을 통해 해당 스위치의 내부 구조가 어떤 구조로 제작되었는지 매핑할 필요성이 있었습니다.
다만 각 스위치에 대한 정보를 어디에서 수집해야하는지 파악이 되지 않아 난항을 겪고 있었습니다.
그러던 중 인터넷 서치를 통해 한 온라인 커뮤니티 유저들이 스프레드 시트를 통해 제작해놓은 스위치 정보 테이블을 발견하게 되었고, 해당 자료를 통해 switch_catalog.json 파일을 제작했습니다.
당초 계획은 크롤러를 통해 수집한 스위치 이름과 switch_catalog.json의 스위치 이름 필드를 순회해 스위치 타입을 결정하고 해당 스위치 타입에 따라 타건감을 결정할 계획이었습니다.
하지만 같은 스위치에 대해 다나와에서 적어놓은 스위치 이름과, 커뮤니티 스프레드 시트에서 적어놓은 이름에 차이가 있어 매핑이 되지 않는 문제가 발생했습니다.
예시로 다나와에는 “경해축”으로 표기된 스위치가 커뮤니티 스프레드에는 “Blue Whale 경해축”으로 표기되어 있어 이름이 정확히 일치하지 않아 매핑이되지 않은 문제가 발생했습니다.
여기에 제조사가 달라도 스위치의 이름이 동일한 경우도 있고, 제조사가 제공되지 않는 스위치도 존재해 생각보다 에로사항이 더 많았습니다.
현재의 과제는 “기계식 키보드의 경우 스위치 제조사까지 제공되는 키보드에 대해서만 추천을 진행한다”라는 방안의 의사 결정을 진행하는 것입니다.
| ### 지금 가장 의심스러운 가정 | ||
|
|
||
| - 사용자가 원하는 키보드 후보군을 찾는 데 자연어 입력 방식이 실제로 편리한가? |
There was a problem hiding this comment.
호호 자연어가 정말 편한지는 제가 한 번 물어봤던 거 같긴한데.. 꿈이었나 기억이 가물가물하네요.
자연어 입력을 받는 다는 것은 여러분들이 그 입력을 받아냈을 때 사용자가 가려운 곳을 긁어줄 수 있도록 대답하게 만드는 프롬프트를 깎아야하는 영역이지요.
쉽게 말하면, 키보드 에이전트를 여러분이 직접 만들어야하는 영역이 되는거죠.
LLM은 방향을 잡아주지 않고는 진짜 굉장히 멍청해요. 여러분이 사용하고 있는 에이전트도 굉장한 하니스가 구축되어있는 친구들이랍니다. 그냥 단순 LLM 콜은 굉장히 멍청하게 될 수 있다는 사실, 여러분들이 여태껏 몇십년간 쌓아온 지식들이 뇌에 들어있다는 것을 간과해선 안돼요. 일반 LLM 콜은 그냥 아무 학습도 하지 않은 뇌에게 뭔갈 물어보는 것과 비슷해요. 비결정론적인 AI 결과물을 최대한 내가 원하는 결과를 내개끔 만드는, 프롬프트를 깎는 것은 굉장히 힘든 일이랍니다
There was a problem hiding this comment.
말리빈이 언급한, LLM은 방향을 잡아주지 않고는 진짜 굉장히 멍청해요. 라는 말에, 실제로 우리 LLM이 방향이 잡히지 않고 멍청한가? 에 대한 검증으로 전혀 키보드와 연관 없는 검색어를 입력했을 때 아무 추천이 나오지 않는 결과를 보면 어느정도 하네싱은 구축해냈다고 생각합니다.
저희가 이번 보고서에서 가장 의심스러운 가설로 “자연어 입력이 정말 편한가?”를 선택한 이유는 발표 과정에서 크루들에게 받은 피드백에 있습니다.
발표 당시 “초보자에겐 자연어를 입력하는 것 조차 어려울 수 있을 것 같다.”라는 피드백을 받았고, 이에 대한 우려는 저희도 계속 해왔기 때문에 처음 서비스를 기획할 때부터 “단계별 선택”기능을 구성해 놓았고 이를 설명해주었습니다.
다만 중간 발표 당시에는 단계별 선택 기능이 화면 하단에 배치되어 보조적인 검색 도구로 인식 되었다고 생각합니다. 그 결과 다른 크루들로부터 “자연어 입력 방식도 사용자에게 어려울 수 있다”라는 피드백을 받았고, 이를 가장 의심스러운 가정으로 선정했습니다.
이 가정을 검증하고 보완하기 위해 현재는 ‘자연어 입력’과 ‘단계별 선택’이라는 두 가지 검색 방식을 제공하고, 사용자가 원하는 방식을 직접 선택하도록 하는 방향으로 진행하고 있습니다.
또한 사용자가 두 기능을 모두 주요 검색 방식으로 인식할 수 있도록 UI상에서 동일한 위계로 배치하는 작업을 진행했습니다.
There was a problem hiding this comment.
단계별로 하되, 중간중간에 llm에게 말을 걸수도 있게 하이브리드로 한다면...? 이건 편하려나요 ㅋㅋㅋ
| ### 이번 주에 만든 핵심 기능 | ||
|
|
||
| 1. 자연어 기반 키보드 추천 기능 | ||
| 2. 스위치 특징 레벨 미터 | ||
|
|
There was a problem hiding this comment.
만든 기능들은 가설 검증에 좀 가까워진 것 같나요?
그렇다면, 혹은 그렇지 않다면, 어떤 이유인가요?
There was a problem hiding this comment.
만든 기능들은 가설 검증에 어느 정도 가까워졌다는 생각이 듭니다. 저희가 세운 핵심적인 가설은 “키보드 구매 과정에서 고려해야할 정보가 너무 많아서 사용자가 부담을 느끼며, 이를 자연어 입력이나 단계별 선택을 통해 줄여줄 수 있다”는 것이였습니다.
현재 구현한 자연어 입력, 단계별 선택, 추천 결과 카드, 태그 표시, 초보자용 설명, 구매 링크 등은 사용자가 복잡한 키보드 정보를 직접 비교하지 않아도 자신의 조건에 맞는 후보를 빠르게 확인할 수 있도록 도와줍니다. 이러한 점에서 “키보드 선택 과정을 간소화할 수 있는가”라는 가설을 검증하기 위한 최소한의 사용 흐름에는 가까웠다고 볼 수 있습니다.
하지만 아직 완전히 가설 검증에 도달하였다고는 말하기 어려울 것으로 보입니다. 기능이 존재한다고 해서 사용자가 실제로 더 편하게 느꼈는지는 알 수가 없기 때문입니다. 자연어 입력이 정말 사용자에게 가장 편리하게 느껴지는지, 단계별 선택지 제공을 통한 선택이 부담을 줄여주는지, 추천 결과가 신뢰할 만하다고 사용자가 느끼는지, 초보자를 위한 설명이 이해를 돕는지는 실제 사용자에게 사용을 해보도록 하고 피드백을 통해서 확인하여야할 것으로 보입니다.
따라서 현재 기능은 가설을 검증할 수 있는 형태의 프로토타입에 가깝지만, 검증 자체는 아직 사용자의 피드백을 통해서 추가적으로 진행해야할 것으로 보입니다.
…on-volume fix: 검색 결과 필터 카운트 표시 개선
…on-volume feat: 추천 결과 초보자 설명 추가
Pencil 새 메인 화면(시안 A) 반영. - 상단 '자유롭게 입력 / 단계별 선택' 세그먼트 토글로 입력 방식 전환 - 자유 입력 탭: 텍스트 입력창 + '분석하기' 버튼 - 단계별 탭: 용도/타건감/예산 칩 미리보기 + '단계별로 시작' 버튼으로 단계 진입 - 부제를 '원하는 방식으로 키보드를 찾아보세요.'로 수정, 예시 질문 섹션 유지 homeTab 상태로 토글 모드를 관리하며 기존 freeform/step 동작은 그대로 결선
추천 엔진의 두 경로(Edge Function/OpenAI vs 결정론 의도 하네스), 데이터 파이프라인, 버전 단일소스, 테스트 규약을 정리. 기존 Git 작업 규칙은 보존.
CLAUDE.md/AGENTS.md 내용 중복(drift)을 막기 위해 AGENTS.md를 정본으로 두고 CLAUDE.md는 심볼릭 링크로 전환. Claude Code/Codex 등 어떤 에이전트가 읽어도 동일 내용을 본다.
개인 머신(~/.claude)에 묶여 있던 knowledge-loop(추출->검토->승격)를 도구·머신 비종속으로 레포에 적용할 수 있도록 docs/knowledge/ 에 정리. - README.md: 패턴 개념, 레포에 두는 이유, 승격 워크플로, 도구별(Claude/Codex/수동) 적용법 - scripts/: KNOWLEDGE_DIR·KNOWLEDGE_LLM_CMD 로 경로·LLM 교체 가능한 추출/넛지 스크립트 - pending.md/archive.md/promoted/: 저장소 골격 템플릿 - 기존 전역 훅과의 중복 추출을 막기 위해 이 레포는 의도적으로 훅 미등록(가이드만 제공)
- 템플릿 클릭 시 freeform 탭으로 전환해 입력값이 보이도록 수정 - 추천 진행 중(loading) 분석 버튼 비활성화로 중복 요청 방지 - 홈 복귀 경로 3곳에서 homeTab을 freeform으로 초기화 - 미사용 import(SlidersHorizontal, MessageSquare) 제거
- 홈 복귀 로직 3곳 중복을 goHome 공용 콜백으로 추출 (DRY) - goHome에서 rating·error도 함께 초기화해 이전 별점/오류 잔존 제거 - 단계별 진입 시 setError(null) 추가로 이전 오류 배너 잔존 제거 - 탭 전환·템플릿 선택 시 setError(null) 추가
- goHome의 불필요한 useCallback 제거(메모이즈 이점 없음, 일반 const로) - 세그먼트 토글 배열을 모듈 상수 HOME_TABS로 추출해 렌더마다 재생성 제거 - 템플릿 선택 인라인 람다를 selectTemplate 헬퍼로 추출
feat(keybuddy): 홈 화면을 세그먼트 토글 레이아웃으로 재디자인
신규 진입자가 CLAUDE.md를 별도 사본으로 오해하지 않도록, 한쪽만 편집 금지·새 도구는 사본 대신 링크로 추가·클론 시 core.symlinks 주의를 첫 문단 아래에 명시한다.
macOS/Linux는 추가 설정 없이 동작하고, Windows는 개발자 모드/관리자 권한과 core.symlinks 설정이 모두 필요하며 없으면 한 줄짜리 텍스트 파일로 풀린다는 점을 안내에 추가한다.
docs: 에이전트 지침을 AGENTS.md 단일 정본으로 통합
- impl/keybuddy/docs/* 와 intent-harness-before-after.md 를 레포 루트 docs/ 로 이동. AGENTS.md가 이미 'docs/tag-extraction-flow.md' 를 참조하는데 실제 파일이 impl/keybuddy 하위에 있어 발생한 경로 불일치를 해소 - tag-extraction-flow.md / intent-harness-before-after.md 상단에 '미연결 클라이언트 설계' 상태 헤더 추가. 실제 배포 추천은 Supabase Edge Function + OpenAI(gpt-5.4)이며 의도 하네싱 lib는 앱 진입점에 미연결임을 문서 자체에 명시(AGENTS.md '두 개의 추천 경로'와 정합) - 이동에 따른 상호 링크/자기 경로 참조 갱신
- Edge Function 실제 maxCandidates(40)와 어긋난 '25개' 표기 3곳 정정 - 루트 docs/ 기술 문서로 안내하는 '더 읽을거리' 섹션 추가
- 기획서(가설/문제정의)는 보존하고 '9. 구현 현황' 섹션을 추가 - 입력 방식(자연어/단계별 10문항), 결과 화면, 기획 대비 추가/미구현 항목 정리 - 기술 상세는 impl/keybuddy/README.md 및 impl/keybuddy/docs/로 안내
리뷰에서 발견한 결함을 수정한다. - knowledge-extract.sh: cwd 누락 시 기본값 "?" 대신 $PWD 로 폴백해, git 루트를 못 찾을 때 실행 위치에 "?" 디렉토리를 만들거나 헤더에 "?"가 찍히는 부작용을 막는다. - knowledge-extract.sh: grep -c 결과(interrupts/commits)에 기본값 0 을 보장해, 드물게 빈 문자열일 때 정수 비교(-eq)가 깨지는 것을 방지한다. - knowledge-nudge.sh: claude-json 출력을 printf 대신 jq 로 인코딩해, 저장소 경로/KNOWLEDGE_DIR 에 따옴표·역슬래시가 있어도 JSON 이 깨지지 않게 한다. 평문 분기는 그대로 두어 jq 미설치 환경에 영향 없음. - README: 기타 도구 수동 실행 예시가 transcript 파일을 직접 파이프하도록 적혀 있어 실제 stdin 계약(transcript_path 를 담은 JSON)과 어긋났다. 그대로 따라하면 조용히 종료되므로 JSON 입력 예시로 교정한다.
docs(knowledge): 레포 내장 지식 루프 가이드와 이식용 스크립트 추가
There was a problem hiding this comment.
여기에 추가된 테스트가 의미 있는 테스트인지 조금 의문이 드네요.
There was a problem hiding this comment.
Agent.md 로 공용화하는 게 낫다는 생각이 들어요.
또는 claude.md나 agent.md에서 그냥 단순하게 내용을 반드시 ""파일을 본다. 모든 에이전트가 같은 지침을 보기 위함이다. 이런 한두줄만 적어두고 관리하는 방법도 있겠어요.
누구든 이 레포에 기여할 때, 레포를 처음 만든 사람이 원하는 큰 그림대로 코드를 작성하고 철학이 담겨있게끔 만들도록 하니스를 구축해두는 것도 중요한 일이라 생각해요. 아주 상세한 부분들은 다를 순 있어도 가장 큰 가지의 방향정도는 자동으로 맞출 수 있게끔이요.
docs: keybuddy 기술 문서를 레포 루트 docs/로 일원화
코드 리뷰(PR #20) 반영. - "후보를 좁힙니다"는 단계별로 후보를 실시간 축소하는 듯한 오해를 줘 "순서대로 답하면 조건에 맞는 키보드를 추천합니다"로 정정. 실제로는 마지막 단계에서 runRecommend(guided)를 한 번만 호출한다. - "각 질문에 상관없음류 선택지를 두고"는 과장. 타건 소리/크기/백라이트 3개 질문은 상관없음류 선택지가 없으므로 "대부분의 질문에"로 정정하고 예외 3개를 명시.
docs: 루트 README에 keybuddy 구현 현황 반영
…location-input [Refactor] UI/UX 개선
4 participants
Week 3 보고서 - ellipsis
이번 주 한 일 (계획 vs 실제)
(개발 진도가 계획대로 갔는지)
계획
실제
A. 지난주 액션 결과
2주차에 정한 1가지
실행 상태
결과
B. 개발 진행 상황
이번 주에 만든 핵심 기능
진도
발표에서 보여줄 수 있는 핵심 흐름
범위 변경 (있다면)
C. 의사결정 / 막힘
새로 발견한 문제
이로 인해 의도와 다른 피드백이 이어졌고, 이를 해석하고 조율하는 데 예상보다 많은 시간이 소요되었다. 2. LLM 추천 결과가 부족하게 오거나 잘못된 인덱스를 반환할 경우, 어디까지 fallback으로 채워야 하는지 명확히 정해야 했습니다. 이 처리가 불안정하면 사용자가 빈 결과나 잘못된 추천을 받을 수 있다고 판단했습니다
결정 + 근거
서비스의 방향을 정확히 전달해야 불필요한 오해를 줄이고, 의도에 부합하는 피드백을 받을 수 있기 때문이다. 2. 추천 fallback 로직은 AI와 Claude 리뷰를 통해 놓칠 수 있는 엣지케이스를 검토한 뒤, 잘못된 인덱스나 부족한 추천 결과가 들어와도 안전하게 처리되도록 정리했습니다.
특히 dead code를 제거하고, 추천 결과가 부족할 경우 fallback으로 채우는 기준을 명확히 하여 사용자가 빈 결과나 잘못된 결과를 받지 않도록 개선했습니다.
풀리지 않은 막힘 (있다면)
D. 회고
이번 주 가장 큰 학습 1가지
그런 상태에서 악어 크루의 AI Agent에 대한 발표를 통해 commend, skills에 대한 인사이트를 얻을 수 있었고 앞으로 AI를 사용하는 역량을 어떻게 높여야 할지 방향을 잡은 것 같다.
AI skills 중 사용자의 의도를 구체화하고 모호성을 줄이기 위해 AI와 토론을 할 수 있는 interview라는 skill이 있다. 이를 활용해 AI에게 내 의도를 명확하게 전달하는 연습을 할 수 있을 것 같다.
지금 가장 의심스러운 가정
최종 발표 흐름 초안 (1줄)