user_brief 추후 상의 · 백로그

결정 전 논의·검토 항목을 추적·보존한다. Evidence(/docs/user_brief/backlog.html)에 노출되어 사용자가 확인하고 작업 진행 시 참조·언급할 수 있다. 항목 처리: 결정 시 data/decisions.json 또는 해당 설계 문서로 이관, 폐기 시 archive.md로 이동.

1. 내용 참조(상호 참조·탐색) 개선 — 미결정

작성 2026-06-07. 발단: 옵시디언 그래프뷰 검토 → 이 리포에 맞는 내용 참조 방안 논의.

배경 — 문서(현재 docs 25 + cmdboard 토픽 노트)가 늘면서 문서 간 상호 참조·탐색을 개선할 방법 검토.

옵시디언 그래프뷰 결론(보류) - 작고 구조화된 에이전트용 리포에선 전역 그래프뷰 ROI 낮음: [[위키링크]] 전제, 사람 전용, 에이전트 가치 0, 규모 커지면 털뭉치. - 로컬 그래프/백링크는 가치 있으나 모델 충돌: 현재는 사이드카 매니페스트·프론트매터 없음 결정인데 옵시디언은 위키링크/프론트매터 기본, [[ ]]는 Evidence 정적 HTML에서 미변환.

후보안(추천순) 1. 토픽 인덱스 페이지(유력) — 기존 docs_manifest.json:topics + topics_vocab.json을 재사용해 빌드 시점에 "토픽 → 해당 문서들" 인덱스를 Evidence에 1장 생성. 토큰0 결정형, 사람(웹)+에이전트(경로) 겸용, 수동 링크 0. 그래프뷰의 "연결 보기"를 정적·실용 형태로 대체. 2. 문서 하단 "관련 문서" 표준 마크다운 링크(큐레이트·수동; 옵시디언 백링크 + Evidence + 에이전트 Read 모두 호환). 3. 프로젝트/토픽 허브(MOC) 강화(기존 SARA·cmdboard 허브 확장). 4. 검색 우선(ripgrep/VS Code/mem_find.py) — 문서 수가 작아 상당 부분 커버.

다음 — 1번 채택 시 작은 코디 지시문화(기존 topics만 읽어 Evidence 인덱스 1장 추가). 결정 전까지 보류.

진행 경과 (2026-06-07) - 1차 토픽 부착 완료: 채티가 sara·user_brief·cmdboard 핵심 문서 본문을 정독해 문맥 기반 교차 연결 4건을 매니페스트에 부착. 교차 토픽 0→4 생성: domain:agent(cmdboard·sara·user_brief), domain:architecture(cmdboard·sara), domain:deploy(cmdboard·sara), domain:ops(cmdboard·user_brief — SARA가 user_brief 세션 시스템을 이식 예정인 연결). validate_manifest exit 0(41항목). - 다음(코디 작업): 토픽 인덱스 페이지 생성 — 매니페스트 topics를 빌드 시점에 읽어 "토픽→문서·프로젝트 교차 토픽" Evidence 페이지 1장. 자동 재빌드(auto_rebuild.sh)에 포함(매니페스트 해시는 이미 감지하나 인덱스 페이지 빌드 단계가 신설 대상). 점진 확장: 단순 동일 키워드 매칭도 새 연결 발견에 활용.

진행 경과 (2026-06-11) — 옵시디언 재평가 (AI vs 사용자 입장) - 자체 관계도(우주 테마·3축·툴팁)·토픽 인덱스 완성으로 보류 사유가 더 강화됨 — 그래프뷰 수요는 자체 구현이 의미 단위(topics)로 대체, 옵시디언 그래프는 위키링크 부재라 고립 노드만 표시. - AI 입장: 효용 0. 에이전트는 원본 .md 직접 Read, 관계·검색은 manifest topics + mem_find가 우위. 위키링크/frontmatter 도입 시 관계 진실 이중화(매니페스트 vs 본문 링크) + Evidence에서 [[ ]] 깨짐 + 페페 직접 편집이 register_doc·validate·BRIEF 캡 관리 우회 리스크. - 사용자 입장: 실제 격차 2개 — ① 전문 검색(Evidence에 없음) ② 즉석 캡처(쓰기 면 부재). 읽기·구조화 뷰·그래프는 Evidence/자체 관계도 우위. - 개선 후보(추천순): ① render_docs.py 문서별 "관련 문서" footer(동일 topics 자동 부착·토큰0) ② Evidence 정적 전문검색(빌드 시 minisearch/lunr 인덱스 JSON + 검색 페이지 1장·읽기전용 불변) ③ (조건부) 옵시디언=inbox 전용 캡처 한정(.obsidian gitignore·추적 문서 위키링크/frontmatter 금지) ④ 전면 도입 비추천. - 상태: 결정 대기(① 또는 ② 채택 시 코디 지시문화). 아이디어 로그 = projects/ideas/ideas.md 2026-06-11 항목.

2. 관계선 사용자 편집 — 미결정 (2차)

작성 2026-06-07. 발단: 토픽 인덱스(1번)가 정적 페이지인데, 사용자가 프로젝트 간 관계선을 보고 직접 수정·추가하고 싶은 경우 필요.

배경 — 1번 토픽 인덱스는 매니페스트 topics 기반 정적 산출물(읽기전용). 사용자가 웹에서 관계선을 보다가 "이 둘도 연결" / "이 선은 제거"를 직접 반영하려면 쓰기 경로가 필요한데, 현재 Evidence는 정적·읽기전용 모델이라 충돌.

쟁점 — 정적 읽기전용 원칙 vs 사용자 편집 쓰기 경로. 편집 결과는 결국 매니페스트 topics를 바꾸는 일이므로, 어디서 어떻게 쓸지가 핵심.

후보안(추천순·미확정) 1. 편집 우회(추천) — 웹은 읽기 유지. 사용자가 관계선 수정을 채티/코디에게 말로 지시 → 매니페스트 topics 편집 → 자동 재빌드로 반영. 정적 모델 불변, 추가 인프라 0. 2. 로컬 편집 보조 UI — 매니페스트 topics를 편집하는 작은 로컬 도구(웹 분리). 정적 빌드와 독립. 3. Evidence에 쓰기 경로 도입 — 정적·읽기전용·토큰0 원칙과 정면 충돌(신중).

다음 — 1번(토픽 인덱스) 가시화 후, 실제 사용 중 편집 수요가 확인되면 1번 후보(편집 우회)부터 검토. 결정 전까지 보류.

3. BRIEF 캡 압박 구조 개선 — 미결정

작성 2026-06-11. 발단: pfs 여유 182자 → 페페 "12,000자 캡 확장 가능?" 질문.

진단(실측) — BRIEF.pfs 11,818자 중 본문(handoff/memory/design)은 ~7,900자로 건전. 압박의 29%(~3,400자)는 ① 활성 결정 1,730자 = 9건 전부 전역 결정(pfs 고유 0건; 동일 내용이 전 프로젝트 BRIEF에 복사, 전역 결정 1건 추가 시 전 프로젝트 ~200자씩 동시 증가) ② 아카이브 포인터 1,697자(세션 8건+ 목록). 구조 모순 1건 인정: 클립 6,000×2 = 캡 12,000이라 본문 만재 시 포인터·결정 여유가 이론상 0.

후보안(추천순) 1. 전역 결정 BRIEF.global 일원화(유력) — 시드 체인이 매 세션 BRIEF.global을 읽으므로 정보 손실 0. 각 프로젝트 BRIEF엔 프로젝트 고유 결정만. pfs 즉시 여유 182→~1,900자, 전 프로젝트 동일 효과 + 전역 결정 증가가 더 이상 프로젝트 캡을 압박하지 않음. build_brief.py 소규모 수정. 2. 포인터 목록 압축 / handoff 완료절 추가 이관 — 보조. 3. 캡 12,000→15,000 확장 — 1·2 후에도 부족하면. "클립 12,000+오버헤드 3,000" 논리로 정합성 있으나 토큰 예산 영구 증가 + 기존 결정(캡 불변) supersede 필요(페페 결정 사안).

상태: 결정 완료(2026-06-11) — 3번 채택: 캡 12,000→15,000(dec-brief-cap-15000). 판단 기준 = 페페 제시 "세션 시드 복원의 컨텍스트 점유가 감당되면 글자수·비용 증가 무관" → 실측: 시드 체인(HANDOFF+CLAUDE+global+최대 BRIEF) ≈ 19.6K~28.1K 토큰 = 200K의 10~14%, 캡 +3,000자 = +0.6~0.9%p로 충분히 감당. 1번(전역 결정 일원화)·2번(포인터 압축)은 보류(여유 재고갈 시 재개). 신규 관찰: 컨텍스트 점유 1위는 BRIEF가 아니라 HANDOFF.md(22,309자 ≈ 단독 5~7%) — "얇은 진입점"인데 NOW 완료 라인 누적으로 최대 파일화. NOW 완료 라인의 projects/user_brief/{handoff,archive}.md 주기 이관이 차기 후보.

4. RAG 적용 검토 — 미결정 (2026-06-19)

작성 2026-06-19. 발단: 페페 "user_brief에 RAG 적용 + 추가 제안 검색·제안". 합의 #34에서 RAG '보류' 했던 항목 재검토. 근거 = 이 세션 2개 리서치(로컬 RAG 스택 / RAG 적용 패턴) 교차검증. 1번(내용 참조)·특히 옵시디언 재평가의 개선후보 ②(Evidence 정적 전문검색)와 직접 연결.

결론(요지) — 현 규모에선 풀 벡터 RAG 과투자. 코퍼스 ~100 노트(projects/ 89파일·734KB·~25–35만 토큰 추정)는 Anthropic 공식 가이드의 "~200K 토큰 미만이면 RAG 없이 전부 프롬프트" 임계선. 이미 결정형 시드체인 + 토픽 태그필터 + 토픽 그래프 + mem_find(키워드) 로 "에이전틱 검색" 토대 보유 → #34 '보류' 판단 대체로 유효. 단 "정확한 키워드를 모르는 발견적 질의"가 늘면 가치 발생.

단계안(ROI순·의사결정 게이트 포함) 1. Phase 0 — 미니 eval: 질의→정답노트 골든셋 20~30쌍 + scripts/eval_retrieval.py로 현재 시드+mem_find의 recall@5 실측. recall이 이미 높으면 도입 보류가 데이터로 정당화. = 객관적 출발점. 2. Phase 1 — FTS5(BM25): mem_find를 키워드 substring→BM25 랭킹 격상. SQLite 내장·로컬·무료·의존성 0·즉시 재색인(5분 재빌드 충돌 0). 정확 토큰(파일명·poin03·한글 고유명)에 강함. 한국어는 tokenize='trigram'. 3. Phase 2(필요 확인 시) — 하이브리드: sqlite-vec(기존 SQLite에 얹음) + 로컬 임베딩 KURE-v1(한국어 특화, BGE-M3 기반 1024d CPU) 또는 BGE-M3 + RRF(k=60) + 콘텐츠해시 증분 임베딩. ⚠ Windows sqlite-vec DLL 로딩 게이트 선결(vec_version() 5줄 확인, 실패 시 폴백 LanceDB). API 임베딩 불필요(한국어 벤치 로컬 우위·비용·오프라인). 4. Phase 3(선택) — bge-reranker-v2-m3 로컬(상위 결과 오류 사례 시). - 비도입: GraphRAG·Contextual Retrieval 풀스택 — 핵심 가치(연결 탐색·청크 문맥 보강)를 토픽 그래프(build_graph.py)·handoff 요약으로 무료·결정형 근사 중. 인덱싱 LLM 호출이 로컬·비용민감 원칙과 충돌.

아키텍처 원칙 — 검색은 시드체인 보완(long-tail/발견), 대체 아님. 시드체인 앞단에 넣지 말 것(매 세션 검색 강제 → zero-token 결정성 붕괴). 시드 읽은 이후의 옵션 도구로만 노출.

추가 제안 — ① RAG 진짜 적임지 = talklog(크고 계속 늘고 태그 어려운 코퍼스 → ROI 훨씬 높음, 같은 스택 우선 적용; 영상-다이제스트 체크리스트 #3과 연결) ② 토픽 그래프를 에이전트 탐색도구로 노출 ③ 헤더경로 prepend 청킹(Phase 2 진입 시 최고 ROI 1줄 개선) ④ Lint 단계 신설(인덱스 정합성 검사 합류).

상태: 결정 대기. 채택 시 Phase 0(미니 eval)부터 코디 지시문화. 검증 한계 = Windows sqlite-vec 실동작·현 recall@5 실측 미수행(각각 Phase 2 게이트·Phase 0에서 확인).