Harness Case Study

Karpathy의 X 글 한 편이
CLI 도구로

Karpathy의 “LLM Knowledge Bases” 아이디어를 하네스 시스템으로 구현한 전과정. 4번의 커밋, 2,214줄 Python 코드, 커버리지 100%.

4
Commits
2,214
Lines of Code
23
Tests Passing
100%
Feature Coverage
~3h
Total Time
The Spark
시작: Karpathy의 X 글
“It would be nice to have a single markdown-based knowledge base where an LLM is responsible for maintaining and compiling it. You feed it raw data (articles, papers, images, clippings), and the LLM compiles it into a structured wiki with backlinks and indexes. You then query it, generate slides, charts, reports from it.” — Andrej Karpathy, @karpathy on X

트윗 한 편이 구체적인 CLI 도구로 변환되는 데 필요한 것 — 제대로 된 하네스.

raw/
→
LLM compile
→
wiki/
→
LLM query
→
output/
articles, papers, images → structured wiki → slides, charts, reports
Implementation Timeline
4개 커밋으로 본 구현 과정
8093409 · 2026-04-05 00:33
feat: LLM Knowledge Base 전체 구현 (Karpathy 아키텍처 기반)
단일 커밋으로 전체 프로젝트 부트스트랩. CLI 7개 서브커맨드, Anthropic SDK 래퍼, 증분 컴파일, TF-IDF 검색, Marp 슬라이드/matplotlib 차트 생성, Flask 웹 UI, pytest 23개 테스트.
39 files · +3,073 lines · src/lkb/(11) + tests/(5) + .claude/(5) + wiki/(5) + samples
dadd74d · 2026-04-05 00:50
feat: 듀얼 LLM 백엔드 — Claude Code CLI + Anthropic SDK
API 키 없이 Claude Code 구독만으로 동작하도록 백엔드 분리. 자동 감지 + LKB_BACKEND 환경변수로 강제 선택. llm.py 래퍼가 두 백엔드를 투명하게 라우팅.
src/lkb/llm.py · 135줄 추가
e7e359e · 2026-04-05 00:58
fix: output 슬라이드/리포트 LLM 응답에서 markdown 자동 추출
Claude Code CLI가 설명 텍스트를 포함하여 응답하는 케이스 버그 수정. 정규식으로 마크다운 코드블록만 추출하여 깔끔한 Marp/리포트 생성.
src/lkb/output.py · +60 -15 lines
08a1a19 · 2026-04-05 01:33
feat: Karpathy 원글 누락 기능 4개 추가 — 커버리지 100% 달성
원글 재읽기로 누락 기능 탐지 → lint --deep(LLM 의미분석), output --file(양방향 filing), websearch.py(Tavily+Claude 폴백), ask further questions(3개 후속 질문 자동 생성).
8 files · +481 lines · lint.py +143 · websearch.py +111 · ask.py/output.py/cli.py 확장
Harness Contribution
하네스 시스템이 처리한 것

2,214줄 코드 + 23개 테스트가 3시간 만에 나온 이유. 하네스가 자동 처리한 항목:

/init-project
프로젝트 프로파일링. Python 3.11+ 스택 자동 감지. .claude/CLAUDE.md에 빌드 명령어, 아키텍처, 기술 스택 표 생성.
.claude/skills/
backend-patterns, implementation-plan, qa-scenarios, qa-strategy 4개 스킬 파일 자동 생성. 프로젝트별 컨벤션 고정.
/team Phase 0~3
11개 모듈 src/lkb/ 구조 설계 → 구현 위임. CLI·SDK·컴파일·검색·출력·lint·웹UI 각 specialist에 분배.
/qa-scenario-gen
TC 시나리오 자동 생성. CRUD 라운드트립, 증분 컴파일, 백링크 무결성, 오프라인 모드 등 23개 테스트 케이스 도출.
/qa-cycle
pytest 23/23 통과 + ruff check/format 자동 반복. 실패 시 bug-fixer 자동 호출 (e7e359e 커밋이 그 예).
/self-improve
원글 재분석으로 누락 기능 4개 자동 탐지 → 08a1a19 커밋. "이미 100%"를 의심하고 다시 검증하는 폐루프.
/loopy-era-eval
완성 기준을 단일 메트릭으로 정의. 원글 커버리지 % 를 HARD로 측정하고 미달 시 discard.
.completion-check.md
18개 기능 × PASS/FAIL 표 + 증거 파일 매핑. 원글 대비 추적 가능한 completion 문서 자동 유지.
Architecture
구현 결과 — 11개 모듈
모듈줄 수역할
cli.py155Click 기반 엔트리포인트. 7개 서브커맨드 (ingest/compile/ask/search/output/lint/web)
compile.py327raw/ → wiki/ 증분 컴파일. mtime 기반 state, 백링크 자동 생성
output.py323Marp 슬라이드, matplotlib 차트, 마크다운 리포트 + --file 양방향 filing
llm.py281듀얼 백엔드 (Claude Code CLI + Anthropic SDK) + 토큰 추적 + 재시도
lint.py359정적 분석(깨진 링크) + --deep LLM 의미분석 (누락 topic, 불일치 탐지)
ingest.py174파일/URL 문서 수집. 이미지 자동 다운로드, 웹 클리퍼 호환
web.py195Flask 다크 모드 웹 UI — 브라우징 + 검색
search.py124TF-IDF 전문 검색 (CLI + 웹 UI 공용)
websearch.py111Tavily + Claude Code 폴백. lint에서 missing topic URL 제안
ask.py85Q&A + 3개 후속 질문 자동 생성
config.py77환경변수/경로 관리
23/23
pytest pass
PASS
ruff check
18/18
feature coverage
2
LLM backends
Karpathy Coverage
원글 요구사항 100% 매핑
Karpathy 언급구현증거
raw → compile → wikiPASScompile.py 증분 컴파일
인덱스/요약 자동 생성PASS_index.md, _summaries.md
백링크 (Obsidian 호환)PASS[[...]] 문법
Q&APASSask.py
Further questions 제안PASSask 응답에 "추가로 탐구할 만한 질문" 3개
Marp 슬라이드PASSoutput slides
matplotlib 차트PASSoutput chart
마크다운 리포트PASSoutput report
Output → Wiki filingPASS--file → wiki/outputs/
Lint (깨진 링크)PASSlint.py 정적 분석
LLM 기반 deep lintPASSlint --deep: 4개 missing article 탐지
Web 검색 missing data 보완PASSwebsearch.py Tavily+Claude 폴백
전문 검색 CLIPASSsearch.py
웹 UIPASSweb.py Flask
CLI as LLM toolPASSsubprocess 예시 README 명시
Obsidian Web ClipperPASSREADME 통합 가이드
듀얼 LLM 백엔드PASSClaude Code + SDK
증분 컴파일PASSmtime state 기반

굵은 글씨 6개는 v0.2에서 self-improve가 재분석으로 추가한 기능. v0.1에서 누락됐던 항목들.

Key Lesson
하네스의 진짜 가치
하네스 없이

트윗 한 편 읽고 “음, 흥미로운데” 하고 지나침. 구현하더라도 compile.py까지만 만들고 lint, 듀얼 백엔드, filing 기능은 모두 누락. 원글을 다시 읽어볼 동기가 없음.

하네스와 함께

3시간 만에 11모듈 2,214줄. self-improve가 "완성 선언"을 의심하고 원글을 재검증하여 4개 누락 기능 자동 발견. 커버리지 100% 달성까지 자동 추적.

핵심 통찰

v0.1 “완성”을 의심하지 않았다면 lint --deep, output --file, websearch, further questions 4개 기능은 영원히 누락됐을 것. 하네스의 self-improve Phase가 “원글 다시 읽어봐라” 규칙을 강제 실행한 결과가 08a1a19 커밋.

프로젝트: llm-knowledge-base · 2026-04-05

Inspired by @karpathy's LLM Knowledge Bases