docs: CLAUDE.md README sync rule + README 현행화 #43
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: altair823-org/kebab#43
Reference in New Issue
Block a user
Delete Branch "docs/readme-sync-rule"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
요약
두 가지 문서 작업을 한 PR 으로 묶음:
CLAUDE.md 새 절 핵심
feat/*) 이 README 갱신, spec PR (spec/*) 은 손대지 않음.--json필드 / exit-code → 명령 표 + "빌드 + 실행".config.toml필드 /KEBAB_*env / default / XDG path → SMOKE config 예시 + README 핵심 결정.README 갱신 항목
kebab tui추가,ingest/search가 markdown/image/PDF 모두 처리한다고 갱신,eval✅.Ollama vision LM으로 갱신 (HOTFIXES P6-2), Image caption 라인 추가, PDF parserlopdf+chunker_version per-medium(HOTFIXES P7-3), TUI 진행 상태.kebab-eval/kebab-parse-image/kebab-parse-pdf/kebab-tuicrate 추가, p6/p7 task 카운트 갱신 (4/3).kebab tui+ 두 example 바이너리 (gen_smoke_pdf/gen_smoke_png) 사용법 추가.검증
cargo check --workspace영향 없음 (.md 만 변경)cargo clippy --workspace --all-targets -- -D warnings영향 없음Test plan
회차 1 — actionable 0건. CLAUDE.md 새 절이 미래 PR 작업자에게 한 페이지 lookup 으로 README 갱신 의무 + 위치 + surface 별 매핑 제공. README 자체는 stale 부분 (P5/P6/P7/P9-1) 한꺼번에 정리 + status emoji 변종 (⏸/🟡) 도입 + HOTFIXES 참조 박아둠. 머지 가능. 다음 implementation PR (P9-2 등) 부터 본 sync rule 자동 적용.
@@ -75,2 +75,4 @@`docs/SMOKE.md` walks through running the full pipeline against an isolated TempDir KB via `--config /tmp/kebab-smoke/config.toml`. Use this instead of touching `~/.local/share/kebab/` when verifying a fresh clone or a CLI flag change. Most CLI regressions surface here, not in unit tests (see HOTFIXES.md).## User-facing docs (README)(칭찬) 새 절이 (1) 어떤 PR 가 README 를 손대는지 (
feat/*only,spec/*제외) (2) 어떤 surface 가 갱신 대상인지 (CLI / TUI / Configuration 3 축) (3) 어떤 위치를 손대야 하는지 (명령 표 / TUI 섹션 / config 예시) 를 한 페이지 안에 박아둠. 미래 PR 작업자가 "내 변경이 README 를 건드려야 하나?" 를 한 번의 lookup 으로 답할 수 있는 상태.@@ -77,0 +83,4 @@- **Configuration** — any new `config.toml` field, env var (`KEBAB_*`), default value change, or XDG path. Update the config example block in `docs/SMOKE.md` AND the README's "핵심 결정" / "빌드 + 실행" rows that reference it.The README is also the place where the phase status table lives — flip the relevant row's status (⏳ → ✅) when a phase epic completes. `tasks/INDEX.md` tracks per-component progress; the README tracks per-phase user-visible promises.(칭찬) "Out of scope for the README" 한 줄이 미래에 README 가 부풀어 오르는 것 차단. HOTFIXES detail / version cascade / per-task spec rationale 모두 "이미 다른 곳에 더 잘 적혀 있다" — 정직 + 분리가 깔끔. 미래 contributor 가 README 에 long-form rationale 을 끼워 넣으려고 시도할 때 거부 사유가 코드 옆에 있음.
@@ -44,1 +44,4 @@| PDF parser | `lopdf` per-page 텍스트 추출, `chunker_version = "pdf-page-v1"` 가 PDF 자산에 하드코딩 (HOTFIXES P7-3) — P7-1/7-2/7-3 || TUI | Ratatui + crossterm — P9-1 (Library 패널), P9-2/3/4 진행 예정 || Desktop | Tauri 2 + `pdfjs-dist` (native PDF render backend 금지) — P9-5 || citation 형식 | URI fragment (`path#L12-L34`, W3C Media Fragments) |(칭찬) 핵심 결정 표에 "Image caption" / "PDF parser" 두 행을 신설하면서 HOTFIXES 참조 (P6-2 / P7-3) 를 박아둠. spec literal (Tesseract default, chunker_version 단일값) 과 어긋나는 현실 동작 (Ollama-vision default, chunker_version per-medium) 이 README 만 봐도 정확. "왜 spec 그대로 안 했는지" 의 답은 한 클릭 (HOTFIXES) 떨어져 있어 README 본문은 가볍고 정직.
@@ -91,2 +91,2 @@| **P8** | 음성 transcription + timestamp citation | `kebab-parse-audio` | P5 | ⏳ || **P9** | TUI + desktop app | `kebab-tui`, `kebab-desktop` | P5 | ⏳ || **P5** | Golden query / regression eval | `kebab-eval` | P4 | ✅ 완료 || **P6** | 이미지 ingestion (OCR + caption) | `kebab-parse-image` | P5 | ✅ 완료 (4/4 component, OCR/caption Ollama-vision) |(칭찬) Phase status 표가 ✅ / ⏳ 두 개에서 ⏸ (보류) + 🟡 (진행 중) 두 변종 추가. P8 의 "보류" 와 P9 의 "진행 중 1/5" 가 단순 ⏳ 보다 정확한 사용자 신호 — "P8 은 진행 안 함" / "P9 는 시작했지만 아직 다 안 됨" 두 다른 의미가 한 emoji 로 뭉개지지 않음. 미래 phase status 갱신 시 같은 변종 어휘로 일관.
@@ -94,3 +97,3 @@P0~P5 직렬. P6~P9 P5 이후 병렬 가능.각 phase 는 component-level 단위로 더 분해되어 있다 (총 31 component task — P3-5 app-wiring 추가). 자세한 분해는 [tasks/INDEX.md](tasks/INDEX.md). 머지 후 발견된 버그/fix 의 dated 로그는 [tasks/HOTFIXES.md](tasks/HOTFIXES.md).각 phase 는 component-level 단위로 더 분해되어 있다 (총 33 component task — P3-5 / P6-4 / P7-3 / 등 후속 추가 포함). 자세한 분해는 [tasks/INDEX.md](tasks/INDEX.md). 머지 후 발견된 버그/fix 의 dated 로그는 [tasks/HOTFIXES.md](tasks/HOTFIXES.md).(칭찬) "31 component task 중 17 완료" → "33 component task — P3-5 / P6-4 / P7-3 / 등 후속 추가 포함" 갱신이 정직. spec 시점에 정의된 31 개 + 머지 시점에 발견된 후속 wiring task 3 개를 합산. 미래 reader 가 "왜 31 인데 머지된 게 더 많지?" 를 묻지 않게.
회차 2 — 사용자 결정 'README narrow + 진척도/아키텍처는 별도' 반영. 세 문서로 split (README/HANDOFF/ARCHITECTURE), CLAUDE.md sync rule 도 세 문서 audience 매핑으로 확장. README 의 Mermaid 1개가 facade boundary + vision OCR/caption 점선까지 한 그림에 담음. actionable 0 — 디자인 + 정직성 좋음. 머지 가능.
@@ -5,3 +5,3 @@## ProjectSingle-user local-first knowledge base + RAG. Rust 2024 workspace, 18 crates, single binary (`kebab`). All inference is local (Ollama + fastembed + whisper.cpp).Single-user local-first knowledge base + RAG. Rust 2024 workspace, ~20 crates, single binary (`kebab`). All inference is local (Ollama + fastembed + whisper.cpp).(칭찬)
## Project절이 세 sibling docs 의 audience + 위치를 한 번에 정리. README/HANDOFF/ARCHITECTURE/spec/INDEX/HOTFIXES 가 한 bullet list 로 위치 + 책임 명시 — Claude Code 가 어느 문서를 어느 audience 에 적어야 하는지 첫 절에서 즉시 결정 가능.@@ -74,6 +81,32 @@ The migration from the old `kb` name lives in commits `911fb49 / f1a448d / f9714`docs/SMOKE.md` walks through running the full pipeline against an isolated TempDir KB via `--config /tmp/kebab-smoke/config.toml`. Use this instead of touching `~/.local/share/kebab/` when verifying a fresh clone or a CLI flag change. Most CLI regressions surface here, not in unit tests (see HOTFIXES.md).## User-facing docs (README + HANDOFF + ARCHITECTURE)(칭찬) "User-facing docs (README + HANDOFF + ARCHITECTURE)" 절이 (1) 세 문서의 audience 분리 (2) 갱신 trigger 별 어느 문서를 손대는지 매핑 (3) 셋 다 out-of-scope 인 것 (HOTFIXES detail / version cascade / per-task spec rationale) 명시. PR 작업자가 "내 변경이 어느 문서를 갱신해야 하나?" 를 한 절 lookup 으로 답할 수 있음. spec PR 면제 명시도 그대로 유지.
@@ -0,0 +6,4 @@P0–P5 + P6 + P7 + P9-1 (Library 패널) 머지 완료. `kebab ingest` 가 markdown / image / PDF 모두 처리. `kebab search` / `kebab ask` 가 매체 가로질러 결과 + page citation 반환. `kebab tui` 가 Library 패널 제공. 다음 후보 = P9-2 (TUI search) / P9-3 / P9-4 / P9-5, 또는 보류 중인 P8 (audio) 의 시스템 dep brainstorm.## Phase 로드맵(칭찬) "한 줄 요약" 한 단락이 인수자가 새 conversation 시작할 때 정확히 필요한 정보 (지금 어디까지 + 다음 후보) 를 압축. P5/P6/P7/P9-1 머지 / P8 보류 / P9-2~5 candidate / 사용자 패턴 (책+PDF) 까지 한 페이지 lookup 으로 답.
@@ -0,0 +32,4 @@머지 후 발견된 모든 deviation / hotfix 의 dated 로그는 [tasks/HOTFIXES.md](tasks/HOTFIXES.md). 본 요약은 \"누군가가 인수받을 때 알아두면 시간을 많이 절약하는\" 항목만:- **P3-5 / P4-3 `--config` 누락** — `kebab-cli` 가 `--config <path>` 를 honor 하려면 `kebab_app::*_with_config` companion 을 호출해야 함. 두 번 같은 모양으로 회귀했음.- **P6-2 OCR 기본 엔진** — spec literal 의 Tesseract 가 시스템 dep 부담으로 거부됨, Ollama vision LM 으로 대체. `OcrEngine` trait 그대로라 future swap 가능.(칭찬) "머지 후 발견된 버그 / 결정 (요약)" 절이 6 deviation 을 한 줄씩 dense 표현. 본 detail 은 HOTFIXES 로 미루지만 "인수자가 알아두면 시간 절약" 만 추출 —
--config회귀 / OCR 엔진 변경 / GenerateRequest.images / chunk_id 충돌 가드 / storage UNIQUE bug 등 미래 contributor 가 "왜 이렇게 됐지?" 를 묻기 전에 답을 가져옴.@@ -186,1 +48,3 @@---## 논리 아키텍처```mermaid(칭찬) Mermaid flowchart 가 "사용자 → UI binary → facade → 4 layer (parse/chunker/embed/retrieve/RAG) → 저장소 + 외부" 의 한 페이지 mental model 을 표현.
kebab-app가 facade 라는 §8 의 boundary 가 그림으로 즉시 보임 + vision OCR/caption 의 점선 표기가 "같은 Ollama endpoint 가 두 용도로 쓰임" 을 적시. 이 한 다이어그램으로 README 가 사용자에게 약속한 "Quick start 시각화" 충족.@@ -187,0 +113,4 @@- `KEBAB_*` env — 일부 키 override (`KEBAB_RAG_SCORE_GATE`, `KEBAB_EVAL_GOLDEN`, `KEBAB_COMMIT_HASH` 등).- XDG layout: `~/.config/kebab/`, `~/.local/share/kebab/`, `~/.cache/kebab/`, `~/.local/state/kebab/`.config 예시는 [docs/SMOKE.md](docs/SMOKE.md) 의 `/tmp/kebab-smoke/config.toml` 블록 참조.(칭찬) 비-목표 절 한 단락 압축. 이전의 8-bullet list 대신 한 줄로 "frozen 설계 §11 / §0 참조" 까지 cross-link. README 의 narrow scope (사용 surface 만) 와 일치하면서도 사용자에게 "이건 안 한다" 의 contract 는 보존.
@@ -0,0 +44,4 @@├─> kebab-chunk├─> kebab-store-sqlite├─> kebab-store-vector├─> kebab-embed-local (kebab-embed trait crate)(칭찬) crate 의존성 그래프 + 디렉토리 트리 + 핵심 결정 표 한 곳에 묶여 있어 "내부 구조" 의 single source. 핵심 결정 표가 P6-2 / P7-3 의 spec literal 과 다른 항목 (OCR Ollama-vision / chunker_version per-medium) 에 HOTFIXES 참조 박아둔 게 정직 — 미래 reader 가 "왜 spec 그대로 안 했지?" 를 한 클릭으로 찾음.
회차 3 — 사용자 요청 "바이너리 설치 가이드" 반영. 사전 요구 + 설치 (cargo install --path / --git URL / 갱신 / 제거 + XDG 데이터 정리) + Quick start narrow. 작은 미세 suggestion 1건 (dev 흐름 두 형태 의 차이 한 줄 코멘트) — 본 PR scope 외 follow-up. 머지 가능.
@@ -6,2 +5,3 @@## 사전 요구대상 하드웨어: M4 48GB MacBook 1대, 사용자 1명.- **Rust toolchain** ≥ 1.85 (workspace 가 edition 2024 + resolver 3 사용). [rustup](https://rustup.rs) 권장.(칭찬) 사전 요구 절이 사용자가 첫 페이지에서 바로 마주칠 4 항목 (Rust toolchain / Ollama / 디스크 / fastembed 모델) 을 한 줄씩 dense 표현. 각 항목에 (1) 무엇이 (2) 왜 필요한지 (3) 어떻게 얻는지 명시 —
ollama pull qwen2.5:7b-instruct (텍스트) / gemma4:e4b (vision)처럼 CLI 명령까지 박아두어 검색 추가 lookup 0.@@ -149,3 +14,3 @@## 빌드 + 실행표준 경로는 `cargo install` — `~/.cargo/bin/kebab` 가 PATH 에 있는지만 확인하면 끝.```bash(칭찬) 설치 절이 표준 (
cargo install --path) + 원격 (cargo install --git) + 검증 (which/--version) + 갱신 (--force) + 제거 + 데이터 정리 까지 한 사이클을 한 절에 정리. 특히cargo uninstall kebab-cli가 binary 만 지우고 데이터는 보존 — 사용자가 "왜 데이터가 남아있지?" 라고 묻기 전에 답을 가져옴.~/.local/share/kebab등 4 XDG path 명시도 정확.@@ -174,2 +33,3 @@```## 비-목표 (frozen design §11 / §0)업데이트는 `git pull && cargo install --path crates/kebab-cli --locked --force` 또는 git URL 형식의 경우 `cargo install --git ... --force`.(칭찬) Quick start 가
./target/release/kebab→kebab로 narrow. 사용자가 PATH 통해 호출하는 일반 흐름.kebab doctor한 줄도 추가 — 첫 ingest 가 실패할 때 trouble-shoot 첫 단계가 코드 옆에 있음.@@ -187,0 +47,4 @@# 색인 (Markdown / 이미지 / PDF 모두 한 번에)kebab ingest(suggestion / 미세) 마지막 "설치 없이 dev 흐름" 한 줄이 두 형태 (
cargo run --release -p kebab-cli -- <subcommand>와cargo build --release && ./target/release/kebab <subcommand>) 를 동시 제공. 두 흐름의 차이 (전자는 cargo 가 매번 dependency check, 후자는 binary 직접 실행 → 빠름) 가 한 줄 코멘트로 박혀 있으면 사용자가 어떤 걸 골라야 하는지 즉시 알 수 있음.How to apply (선택): "전자는 cargo cache 갱신 자동, 후자는 binary 빠른 직접 실행 — 짧은 single-shot 은 전자, repeated 호출은 후자" 한 줄 추가. 본 PR scope 외 — follow-up 으로 처리 가능.