볼트 구조 및 디버깅
검색 가능한 두 번째 메모리로 마크다운 볼트를 구성합니다. Claude가 예상치 못한 작업을 수행할 때 네 가지 실패 모드를 분류합니다.
STATE.md 및 MEMORY.md는 모든 세션에 필요한 것을 담고 있습니다. 마크다운 볼트(Obsidian 또는 모든 폴더)는 나머지 모든 것을 담고 있습니다: 전략 노트, 회의록, 프로젝트 저널, 연구, 경쟁 분석.
볼트는 기관 기억으로 성장합니다: 6개월 전에 내린 결정과 그 이유, 현재 작업에 정보를 제공하는 참조 자료, 프로젝트에 걸쳐 있는 패턴. Obsidian 또는 파일 시스템 MCP를 통해 연결하면 Claude가 전체를 온디맨드로 검색할 수 있습니다. 볼트가 없으면 이 지식은 머릿속에만 존재하거나 오래된 문서에 묻혀 있습니다.
마크다운이 데이터베이스보다 나은 이유: 일반 파일은 grep 가능하고, git으로 버전 관리되며, 모든 편집기에서 열리고, 모든 도구 변경에도 살아남습니다. 작동하는 구조:
~/notes/
├── STATE.md # 항상 로드됨
├── MEMORY.md # 인덱스, 항상 로드됨
├── STRATEGY-DIGEST.md # 전략 문서 요약
├── strategy/ # 전체 문서, 온디맨드 읽기
├── projects/ # 날짜가 지정된 프로젝트 노트
├── resources/
└── reference/확장 키는 다이제스트 패턴입니다. 1,000단어 전략 문서를 작성할 때, 그 옆에 3문장 다이제스트를 작성하고 MEMORY.md에 다이제스트를 인덱싱하십시오. Claude는 전체 문서의 약 1,500토큰 대신 세션 시작 시 약 50토큰을 읽습니다. 25개의 전략 문서에서 37,500토큰 대신 1,250토큰이므로 세션이 빠르게 유지됩니다.
Claude가 예상치 못한 작업을 수행할 때 네 가지 실패 모드를 순서대로 확인하십시오. 가장 흔한 것부터 가장 드문 것까지:
오래된 메모리: STATE.md는 한 가지를 말하고, 현실은 다른 것을 말합니다. Claude는 지침을 완벽하게 따랐습니다. 지침이 틀렸습니다. 항상 먼저 "STATE.md를 보여주세요"라고 물으십시오.
누락된 컨텍스트: 관련 파일이 로드되지 않아 Claude가 합리적인 추측을 했습니다. 파일을 명시적으로 로드하고 다시 질문하십시오.
도구 사용 불가: MCP가 다운되었거나 훅이 명령을 차단하여 Claude가 잘못 우회했습니다. 추론을 비난하기 전에 도구 가용성을 확인하십시오.
환각: 가장 드문 원인. 먼저 확인하십시오: 함수를 grep하고, 엔드포인트가 존재하는지 확인하십시오. 대부분의 "환각"은 처음 세 가지 중 하나로 밝혀집니다.
실패 모드당 하나의 진단 질문:
오래된 메모리: "STATE.md는 [주제]에 대해 무엇이라고 말합니까?" 3세션 전의 내용은 오래된 상태를 의미합니다.
누락된 컨텍스트: "[주제]에 대해 로드된 파일은 무엇입니까?" 관련 파일이 없으면 올바른 파일을 로드하십시오.
도구 사용 불가: "지금 사용할 수 있는 도구는 무엇입니까?"
환각: "[함수/엔드포인트]를 grep하고 찾은 것을 보여주세요."
이 순서는 2분이 걸리고 거의 항상 원인을 찾습니다. "Claude가 환각을 일으켰다"로 바로 넘어가는 것은 보통 다시 작성할 필요가 없는 코드를 다시 작성하여 실제 수정을 지연시킵니다.
디버깅보다 예방이 낫습니다. 습관:
세션 종료 시 STATE.md 업데이트. 오래된 메모리 문제의 80%를 제거합니다.
배포된 프로젝트를 보관하여 날짜가 지정된 project_* 파일에 저장합니다.
월별 MEMORY.md 감사: 모든 포인터가 여전히 기존 파일을 가리키는지 확인합니다.
500단어 이상의 모든 문서를 요약합니다.
결정 순간에 결정을 작성합니다. 주말이 아니라. 소급 캡처는 추론을 잃습니다.
프로젝트 노트를 보관하기 전에, 영구적인 교훈을 feedback_* 항목으로 추출합니다. 프로젝트는 역사가 되고, 교훈은 활성 상태로 유지됩니다.
잘 관리된 10개의 문서가 있는 볼트가 200개의 오래된 문서가 있는 볼트보다 낫습니다. 품질과 최신성이 양보다 낫습니다.
Obsidian 또는 파일 시스템 MCP를 사용하면 볼트가 실시간 지식 기반이 됩니다.
결정 고고학: "Postgres 대신 MySQL을 선택한 이유를 볼트에서 검색하세요." 10분 수동 검색이 15초로 단축됩니다.
패턴 감지: "모든 프로젝트에서 속도 제한 문제 또는 429 오류에 대한 모든 언급을 찾으세요." Claude는 5개의 프로젝트 파일에 걸쳐 퍼져 있는 공통 근본 원인을 찾아냅니다.
참조 조회: "공급업체 노트에서 연락처 정보를 찾으세요." 인덱싱되지 않은 파일에서 즉시 검색.
검색 품질은 명명 일관성에 따라 달라집니다: project_[name]_[date].md 및 feedback_[rule].md는 당시 자연스럽게 느껴졌던 것보다 낫습니다. 명명 규칙은 필요하기 전에 구축하는 인덱스입니다.
네 가지 모드 모두 깨끗하게 확인되었는데도 출력이 여전히 잘못되었습니까? 환각처럼 보이지만 환각이 아닌 두 가지 원인.
컨텍스트 순서: 로드된 파일이 충돌하면 나중에 로드된 콘텐츠가 이기는 경향이 있습니다. 오래된 프로젝트 노트가 STATE.md와 모순되면 권한을 명시적으로 할당하십시오: "STATE.md는 현재의 실제 정보입니다. 프로젝트 노트의 모든 것을 대체합니다."
제약 충돌: CLAUDE.md는 "모든 SQL을 매개변수화하라"고 말하므로 Claude는 스타일만 변경하려는 리팩토링 중에 SQL을 다시 작성합니다. 버그가 아닙니다. 명시적으로 범위를 지정하십시오: "스타일만 변경하고 SQL 패턴은 변경하지 마십시오."
둘 다에 대한 진단: "[이 결정]을 지배하는 어떤 지침을 따르고 있습니까? 우선순위 순서대로 규칙을 나열하십시오." 오래된 소스, 충돌하는 규칙 또는 CLAUDE.md의 간극을 찾을 수 있습니다. 모두 수정 가능합니다.
다이제스트 파일이 있는 마크다운 볼트는 두 번째 메모리를 확장합니다. 다이제스트는 세션을 빠르게 유지하고, 전체 문서는 온디맨드로 로드됩니다. Claude가 오작동할 때, 오래된 메모리, 누락된 컨텍스트, 도구 사용 불가, 환각 순서로 분류하고 항상 "STATE.md를 보여주세요"로 시작하십시오. 결정 순간에 볼트에 정보를 제공하면 매주 가치가 복합적으로 증가합니다.