VibeLign 지식 저장고 시스템 기획안

작성일: 2026-04-13 목적: 완료된 기획과 의사결정을 삭제 대신 “지식”으로 변환·축적하여, 프로젝트의 집단 기억과 AI 에이전트 컨텍스트로 활용

현재 상태 메모 (2026-05-14): 이 문서는 제품 비전/기획안이며, 현재 코드베이스에는 vib knowledge, docs/knowledge/, /know slash command, knowledge 기반 patch 주입 구현이 확인되지 않았다. 구현 착수 전에는 아래 전체 비전을 한 번에 만들지 말고, MVP 1단계 = 수동 저장 구조(docs/knowledge/) + docs viewer 노출 + 원본 보존 정책 확정 으로 범위를 잘라야 한다. 의미 검색, patch 자동 주입, export/import 생태계는 별도 후속 RFC 로 분리한다.

1. 배경과 문제의식

현재 워크플로우

기획 md 파일은 구현 완료되면 삭제됨. 그 과정에서 사라지는 것:

  • 왜 이 구조를 선택했는지
  • 어떤 대안을 검토하고 왜 기각했는지
  • 어떤 트레이드오프를 받아들였는지
  • 어떤 실패 사례를 피하려고 했는지

핵심 통찰

코드는 “무엇을”을 말해주고, 기획 md는 “왜”를 말해준다. 이 “왜”가 바로 프로젝트의 집단 기억이며, 시간이 지나도 가치가 있는 자산이다.

비유

카파시의 학습 wiki처럼, VibeLign 사용자가 자기 프로젝트의 설계 여정을 지식으로 축적해나갈 수 있는 공간이 필요함.

2. 비전과 차별점

비전

“프로젝트의 무의식”을 기록하는 도구. 개인 메모가 아니라, 프로젝트가 스스로 기억하는 시스템.

Notion/Obsidian과의 차별점

항목 Notion/Obsidian VibeLign 지식 저장고
정보 단위 자유형 노트 코드 연동 지식
연동 독립 git 커밋·파일 변경·patch 결과와 연동
소비자 사람 AI 에이전트도 읽음
범위 개인 프로젝트별 격리
위치 외부 서비스 repo 안 (자연스럽게 버전 관리)

핵심 차별화 포인트: 저장된 지식이 단순 기록이 아니라 patch CodeSpeak 생성에 실제로 영향을 주는 컨텍스트가 됨.

VibeLign의 두 번째 핵심 자산

  • 첫 번째 자산: 앵커 메타 (코드 의미 레이어 — “무엇”)
  • 두 번째 자산: 지식 저장고 (프로젝트 의도 레이어 — “왜”)

두 레이어가 AI 에이전트 컨텍스트로 결합되면 VibeLign만의 차별화된 경험 창출.

3. 핵심 원칙

입력은 쉽고

사용자가 “지식 저장”을 무겁게 느끼지 않게. 한 번의 액션으로 저장 가능.

정리는 자동

AI가 압축, 태깅, 연관 링크를 자동 생성. 사용자는 큐레이션 부담 없음.

활용은 즉시

저장만 하면 쓰레기장. 저장 직후부터 검색·AI 참조로 활용 가능해야 함.

4. 시스템 구성 (7개 레이어)

레이어 1 — 자동 수집

사용자가 의식하지 않아도 지식이 쌓이는 경로:

  • 기획 md 완료 감지 — plans 폴더의 md에 “구현 완료” 체크박스나 태그 붙이면 자동으로 knowledge 폴더로 이동 + 요약 생성
  • 커밋 메시지 수집 — 의미 있는 커밋(feat, fix)은 “이 변경의 배경”을 자동 추출해서 knowledge에 기록
  • Claude Code 대화 저장 — 사용자가 Claude와 나눈 의사결정 대화를 선택적으로 저장. “이거 지식 저장” 버튼 하나면 끝
  • patch 실패 사례 — patch가 실패하거나 수정된 케이스를 자동 아카이브. “왜 이 코드가 까다로운가”의 증거

레이어 2 — AI 보조 변환

기획 md를 그대로 쌓으면 노이즈 누적. AI가 변환 과정 담당:

  • 압축 요약 — 5페이지 기획 → 핵심 결정 3~5개 + 이유 + 대안 검토 (1페이지)
  • 패턴 추출 — “이런 결정이 반복되고 있어요” 자동 감지 → 상위 카테고리로 묶음
  • 연관 링크 — 새 지식 추가 시 기존 지식 중 관련된 것 자동 교차 참조
  • 태그 자동 생성 — 수동 태그 달지 않아도 AI가 주제 분류

변환은 anchor intent 생성과 같은 방식(2차 AI 단계). API 키 없으면 건너뛰고 원본만 저장.

레이어 3 — 구조 (카파시 스타일 wiki)

docs/
├── superpowers/plans/        ← 현재 진행 중인 실행 계획 (ephemeral)
└── knowledge/                ← 완료 후 재구성된 지식 (permanent)
    ├── decisions/            ← 설계 결정 기록 (ADR 스타일)
    │   ├── auth-oauth-vs-api-key.md
    │   └── patch-scoring-approach.md
    ├── patterns/             ← 반복되는 해결 패턴
    │   ├── anchor-based-grounding.md
    │   └── 1차-코드-2차-ai.md
    ├── retros/               ← 구현 후 회고
    │   └── 2026-04-lsp-vs-anchor-meta.md
    └── index.md              ← 자동 생성 인덱스

레이어 4 — 입력 UX

코알못이 “지식 저장”을 무겁게 느끼지 않게:

  • VibeLign GUI의 “지식 저장하기” 버튼 — 현재 대화/화면에서 바로 저장
  • /know 슬래시 커맨드 — Claude Code 대화 중 핵심 순간 즉시 기록
  • 우클릭 → “knowledge에 추가” — 코드 블록, md 문단 어디서든

레이어 5 — 검색 · 활용

저장만 하면 쓰레기장. 즉시 꺼내 쓸 수 있어야 가치 생김:

  • docs viewer에 knowledge 탭 — 이미 뷰어 있으니 자연스러운 확장
  • 의미 기반 검색 — “auth 관련 결정” 같은 자연어 쿼리 → 임베딩 검색
  • AI 에이전트 자동 참조 — patch CodeSpeak 생성 시 관련 knowledge 자동 주입. “이 부분 수정은 예전에 이런 결정 있었어요” 맥락 제공
  • “오늘의 지식” 알림 — 주기적으로 오래된 지식 중 하나 리마인드 → 복습 효과

레이어 6 — 스테일 방지

시간이 지나도 신뢰를 유지하는 장치:

  • 각 문서에 “작성일 + 관련 커밋 해시” 자동 기록
  • 3개월 이상 된 지식은 “재확인 필요” 배지 표시
  • 관련 코드가 크게 변경되면 자동으로 “이 지식 검토 필요” 알림
  • 사용자가 “여전히 유효” 클릭하면 갱신 타임스탬프

레이어 7 — 공유 · 수출

개인 wiki에서 팀 자산, 나아가 공개 자산으로:

  • knowledge 폴더 전체를 git 커밋 (이미 repo 안이니 자연스러움)
  • vib knowledge export 커맨드로 정적 웹사이트 생성 → GitHub Pages 같은 데 배포
  • 다른 사용자의 knowledge를 import 가능하게 (공개 템플릿 공유 생태계)

5. patch / CodeSpeak 파이프라인과의 통합

현재 컨텍스트 소스

자연어 요청
  → 키워드 추출
  → anchor_meta (intent/aliases/description) 매칭
  → 파일·앵커 grounding
  → CodeSpeak 생성

지식 저장고 통합 후

자연어 요청
  → 키워드 추출
  → anchor_meta 매칭
  → knowledge 의미 검색 (관련 과거 결정 N개 조회)
  → 파일·앵커 grounding + 과거 맥락
  → CodeSpeak 생성 (역사적 결정 근거 포함)

이러면 AI가 “이 부분은 예전에 OAuth 선택한 이유가 있었다” 같은 맥락을 이해하고, 과거 결정을 존중하거나 의식적으로 바꾸는 판단이 가능해짐.

6. 작업 순서 (5단계)

Phase 1 — 기본 저장 구조

  • docs/knowledge/ 폴더 생성
  • docs viewer에 knowledge 탭 추가
  • 수동 저장 버튼 (“지식으로 저장”) 구현
  • 기본 템플릿 (decision / pattern / retro)

Phase 2 — 기획 → 지식 자동 변환

  • plans md에 “구현 완료” 태그 감지
  • AI 보조 변환 (압축, 태깅, 연관 링크)
  • knowledge 폴더로 이동 + 원본 보존 옵션

Phase 3 — AI 에이전트 자동 참조

  • patch CodeSpeak 생성 시 knowledge 의미 검색 통합
  • 관련 지식 상위 N개 프롬프트에 주입
  • 효과 측정 (eval 기반)

Phase 4 — 의미 검색 + 스테일 관리

  • 로컬 임베딩 기반 검색 (코드 전부가 오프라인에서 동작)
  • 스테일 감지 및 배지 표시
  • 주기적 리마인드

Phase 5 — 공유 생태계

  • vib knowledge export → 정적 사이트
  • import/export 포맷 표준화
  • 공개 knowledge 템플릿 마켓플레이스

7. 성공 지표

생산성 지표

  • 사용자가 월평균 몇 개의 knowledge 문서를 축적하는가
  • 기획 → 지식 자동 변환 사용률
  • knowledge 탭 접근 빈도

품질 지표

  • patch CodeSpeak 정확도가 knowledge 참조로 인해 얼마나 향상되는가 (eval 비교)
  • 스테일 지식 비율 (3개월 이상 미검토)
  • 사용자가 “여전히 유효” 표시하는 비율

생태계 지표 (장기)

  • 공개된 knowledge 템플릿 수
  • import된 외부 knowledge 수
  • GitHub Pages로 공개된 knowledge 사이트 수

8. 검토 사항

  1. knowledge 폴더의 git 관리 — 전부 커밋 vs .gitignore 선택형 (사용자 선호)
  2. AI 변환 시 원본 보존 여부 — 옵션으로 둘지, 자동 삭제할지
  3. 의미 검색 엔진 — 로컬 임베딩 (offline) vs 서버 (정확도 높지만 네트워크 의존)
  4. 스테일 기준 — 3개월 / 6개월 / 사용자 설정
  5. patch 통합 범위 — 자동 주입 vs 사용자 명시적 활성화
  6. 공유 마켓플레이스 운영 — anthropic/VibeLign 공식 vs 커뮤니티 자율

9. 핵심 메시지

기존: 기획 → 구현 → 삭제

개선: 기획 → 구현 → 지식으로 변환 → 영구 축적 → AI 에이전트 컨텍스트로 재활용

이 작은 변화로 VibeLign은 “코드 수정 도구”에서 “프로젝트 기억을 함께 만들어가는 파트너”로 진화.

이 문서는 2026-04-13 Claude Dispatch 세션에서 작성. 관련 논의는 VibeLign-LSP-논의.md, VibeLign-규칙수정안-3.md, VibeLign-원클릭설치-기획안_초안.md 를 함께 참고한다. 과거 참조명(VibeLign-줄수-구현가이드.md, VibeLign-원클릭설치-기획안.md)은 현재 파일명과 다를 수 있다.