knowledge-base: Instructions file for Claude Code

knowledge-base 개발 가이드

팀 지식을 Postgres+pgvector에 수집하고 하이브리드 검색을 MCP로 노출하는 서버. 설계 배경과 결정 이력은 docs/가 원본이다 — 특히 검색/파이프라인을 바꾸기 전에 docs/04(Decision Log)와 docs/07(스펙 대조·로드맵)을 먼저 확인할 것.

명령어

pip install -e ".[dev,aws,slack,dashboard,oauth,anthropic]"   # 전체 개발 환경
KB_TEST_DSN="host=127.0.0.1 port=5432 user=kb dbname=kb_test" pytest   # 실 Postgres 필요
pytest tests/test_search_quality.py -k d12              # 단일 파일/테스트
ruff check src tests                                    # 린트

테스트는 mock DB가 아니라 실제 Postgres에 붙는다(스키마 자동 생성·롤백은 tests/conftest.py의 clean 픽스처). pgvector 0.6에서도 전부 통과해야 한다 — 0.7+/0.8+ 전용 기능(halfvec, iterative_scan)은 반드시 버전 게이트(pgvector_version()) 뒤에 넣는다.

아키텍처 (데이터 흐름)

connectors/*  ──SourceRow──▶  pipeline/engine.ingest_row
  (markdown·gitlog·code·slack·   ├─ 해시 dedup → 청킹(chunk.py) → [증류 distill.py]
   github_prs·notion·linear)     ├─ [문맥 생성 context.py] → 임베딩(embed.py)
                                └─ ORM 업서트: documents(원문+FTS) + chunks(임베딩)
DB 계층: models.py(ORM 스키마 원본) · db.py(SQLAlchemy 엔진/세션 — AUTOCOMMIT 격리)
         · migrations/(Alembic 리비전) · migrate.py(kb migrate 러너 — 배포 시 자동 실행)
search/: signals.py(신호별 rank: fts/vector/idf/trgm/context + 필터 푸시다운)
         → fuse.py(가중 RRF·나이감쇠) → hybrid.py(오케스트레이션·boost/superseded
         보정·다양성 캡·Hit 조립). 공개 API는 __init__ 재수출 — kb.search에서 import.
인터페이스: cli.py · mcp_server.py(도구 표면, HTTP는 stateless — 다중 레플리카 안전)
           · dashboard/ · slack_listener.py
인증: auth.py(Identity·베어러 해석: 관리자 토큰 → api_tokens → oauth_tokens)
     · oauth/(kb가 OAuth 2.1 AS: google.py 상위 IdP+허용 정책 · store.py DB
       · provider.py mcp SDK provider+라우트) · dashboard/googleauth.py(세션 쿠키)
       · dashboard/cfaccess.py(구 CF Access 모드 — 유지)
공통 계측: usage.py(UsageEvent→api_usage) + pricing.py(비용 추정)
LLM 실행기: pipeline/llm_backend.get_llm → llm_cli(claude CLI) | llm_api(anthropic/
           bedrock의 Claude) | llm_converse(Bedrock Nova 등 — bedrock 백엔드가 모델 ID로 라우팅)

깨뜨리기 쉬운 불변 원칙

• MCP 도구는 LLM-free — 합성 답변은 클라이언트 에이전트(또는 대시보드 /ask)의 몫. mcp_server에 LLM 호출을 넣지 말 것.
• D12 비대칭 인덱싱: 증류물이 있는 대화는 원문 body 청크를 임베딩하지 않는다 (FTS로는 검색됨). embed_raw_conversations가 롤백 플래그.
• superseded 노트는 삭제하지 않는다 — 감점(×0.3)+뱃지로 하향, 이력 보존. 타 프로젝트 명시 노트도 같은 패턴(D19): 스코프 검색에서 배제 아닌 ×0.5 감점 +other-project 뱃지. project 미기록 노트는 팀 공용 = 무감점 (하위호환). 기록 시 project 이름은 projects/project_sources로 해석한다 — 저장소 이름은 소유 프로젝트로 교정, 미등록 이름은 저장하지 않는다 (잘못된 라벨 > 무라벨의 해악).
• 커넥터 실패 격리: 커넥터 하나의 예외가 다른 커넥터 sync를 막으면 안 된다.
• 계측은 본 작업을 깨지 않는다: on_usage 훅 실패는 삼킨다 (usage.py 패턴 유지).
• 스키마 변경 = models.py + Alembic 리비전 한 쌍: models.py 수정과 migrations/versions/ 새 리비전 파일이 함께 움직인다. baseline(0001)은 레거시 DB stamp 기준이라 수정 금지. 파괴적 마이그레이션 금지 — 되돌림도 전진 리비전으로. 배포는 kb migrate가 자동 적용한다 (compose migrate 서비스 / k8s initContainer, advisory lock으로 동시 실행 직렬화).
• 세션은 AUTOCOMMIT (db.py): 문장 즉시 커밋이 stateless MCP·동시 sync의 dedup 가시성 전제다. 트랜잭션 묶음이 필요하면 해당 경로에서 명시적으로 열 것.
• 검색 파라미터(가중치·청크 크기·임계값) 변경은 골든셋(kb eval) 스코어로만 판단.
• MCP HTTP는 stateless (stateless_http=True): 요청마다 독립 처리라 k8s ×N 레플리카가 안전하다. 세션 상태를 요구하는 기능(구독·서버발 알림)을 붙이려면 이 전제부터 재검토할 것 — 회귀 테스트: test_mcp_http의 stateless 테스트. OAuth도 이 전제를 지킨다: 대기 중인 인가 요청은 서명된 state에 담고(D17) DB에는 발급 결과(클라이언트·코드·토큰)만 남긴다 — pending 테이블을 새로 만들지 말 것.
• 인증 경로는 auth.verify 하나 — 관리자 토큰 → api_tokens → oauth_tokens 순. 새 인증 수단을 여기 밖에서 해석하지 말 것(스코프·감사 로그가 갈라진다). OAuth가 켜지면 allow_open=False — "등록 토큰 0개 = 무인증 admin" 완화가 꺼진다(공개 노출 전제). 이 게이트를 되돌리면 인터넷에 열린 KB가 된다.
• OAuth 설정은 전부 아니면 전무: 부분 설정·빈 허용 목록·짧은 서명 키는 기동 시 예외다 (GoogleOAuth.from_env). 조용히 인증 없이 뜨는 것보다 안 뜨는 게 낫다.
• 허용 도메인 판정은 hd 클레임 필수 (D18): 개인 Google 계정도 회사 도메인 주소를 verified email로 가질 수 있어 email 접미사만으로는 조직 소속이 아니다.