AI로 늘어난 노트를 썩지 않게 관리하는 방법 — Obsidian × Claude Code 운영 시스템 공개

AI를 이용해 노트를 쓰는 속도는 빨라졌는데, 이런 상태가 아닌가요?

• Inbox에 정리되지 않은 클립이 계속 쌓여서 영원히 비워지지 않는다.
• 반년 전에 자신이 작성했던 노트의 존재 자체를 완전히 잊어버린다.
• 링크를 걸지 않은 채 고립된 노트가 늘어난다.
• '나중에 읽기'가 '다시는 읽지 않음'과 동의어가 되어 버렸다.

저도 똑같은 상태였습니다. AI는 노트를 만드는 속도를 높여주지만, 다시 읽는 속도는 높여주지 못합니다. 그 결과 발생하는 것이 바로 '생성 과잉(Generation Overload) 및 소비 부족(Consumption Deficit)'입니다.

이 글에서는 이러한 문제를 해결하기 위해 제가 구축한 Claude Code 운영 시스템 전체를 소개합니다. 이번에 전부 공개했기 때문에, 그대로 복사해서 사용해 볼 수 있습니다.

Kaz-Hira/obsidian-claude-kit — 슬래시 명령어 10개 / 후크 9개 / 스킬 9개 / 서브 에이전트 5개 / 스크립트 12개.

데모용으로 작성한 것이 아니라, 제가 매일 실제로 사용하고 있는 설정을 그대로 공개용으로 정제(sanitize)한 것입니다.

💡 애초에 부족한 것은 무엇인가

Obsidian에 AI를 결합하는 글은 많지만, 그 대부분은 '노트를 만드는 것'에 관한 이야기입니다. 요약하게 하거나, 기사를 클립하거나, 회의록을 정리하는 식이죠.

하지만 실제로 막히는 부분은 거기서가 아니었습니다. 막히는 건 작성한 후였습니다.

오른쪽은 지루하고, 게다가 안 해도 오늘은 큰일이 나지 않습니다. 그래서 영원히 미뤄지고, Vault는 조용히 썩어갑니다.

이 시스템 전체의 내용은 거의 전부 오른쪽(관리하는 쪽)에 해당합니다.

🚀 무엇이 자동으로 돌아가는가

가장 큰 변화는 능동적으로 실행해야 하는 명령어가 실질적으로 단 두 개만 남게 되었다는 것입니다.

남는 것은 /triage(Inbox 분류)와 /weekly-review(주간 정리) 단 두 가지입니다. 그 이상은

남는 것은 /triage(인박스 분류)와 /weekly-review(주간 정리) 단 두 가지입니다. 그 이상은

해설: 여기가 사실 가장 중요한 설계 원칙으로, '폴더는 종류로 나누고, 주제(話題)로 나누지 않는다'라는 원칙입니다. 주제로 나누면 반드시 이중 귀속(二重帰属)이 발생합니다('AI 학습 노트'가 AI/에 들어갈까, 아니면 Study/에 들어갈까?). 종류라면 유일하게 결정되므로, 보관 위치를 판단하는 과정 자체가 매번 필요 없어집니다.

⚙️ 실제로 고통을 겪어보고 배운 세 가지 판단 기준

여기부터가 본론입니다. 직접 만들어보면서 알게 된 '이것을 하지 않으면 반드시 망가진다'는 점 3가지를 공유합니다. 이는 제가 이미 망가뜨린 기록이기 때문에, 같은 함정에 빠지지 않을 수 있습니다.

1. 성공했을 때만 스탬프를 진행시키기

RSS 수집 작업(ジョブ)이 3일 동안 조용히 실패하고 있었습니다. 게다가 저는 그 사실을 알아채지 못했습니다.

원인은 두 가지의 조합입니다.

• 훅(Hook)이 /usr/bin/python3 (3.9 버전대)를 절대 경로로 호출하고 있었기 때문입니다. 직전에 PATH 설정을 했음에도 불구하고, 절대 경로 지정이 이를 무효화했습니다. 스크립트 측에서는 -> bytes | None (PEP 604, 3.10 이후)을 사용했기 때문에 TypeError가 발생하며 즉시 종료되었습니다. 또한 '마지막 실행 시간' 스탬프를 실행 전에 업데이트하고 있었습니다. 그래서 실패해도 스탬프는 진행되어 이중 구동 방지 가드창이 닫히고 재시도되지 않았습니다.

두 번째 것이 정말 까다롭습니다. 실패했는데도 '방금 실행한 것'이라는 기록만 남아있기 때문에, 로그를 읽지 않으면 영원히 알아차릴 수 없습니다.

대책으로 상태 파일(state file)을 3가지로 나누었습니다.

.vault-<job>-lock # 이중 구동 방지용. 시작【전】에 접근
.vault-<job>-stamp # 최종【성공】시간. 자식 프로세스가 exit 0일 때만
.vault-failures.jsonl # 실패 기록. 대시보드가 이것을 읽음

• 해설: 하나의 파일에 '배타적 잠금(排他ロック)'과 '성공 시간'을 겸하게 한 것이 패착이었습니다. 분리한 후, 연속 3회 실패한 작업은 서킷 브레이커로 중단시키고, 시작 시에만 한 줄 표시합니다. 무한히 실패하는 것보다 사람에게 보여주는 편이 낫습니다.

2. 구문 검사(Syntax Check)는 통과해버린다

위의 -> bytes | None은 py_compile로도, ast.parse로도 감지할 수 없습니다. PEP 604 타입 주석은 def 실행 시점에 평가되기 때문에, 구문 검사는 그냥 지나갑니다.

# 이것은 통과한다. 하지만 실행하면 떨어진다
python3 -m py_compile vault-rss.py

검증은 반드시 '실제로 돌려보는 것'이어야 합니다. 이는 글을 쓰고 있는 와중에도 실증되었습니다. 이번에 리포지토리를 공개용으로 패키징했을 때, install.sh에서 두 가지 버그를 발견했습니다.

• local src="$1" rel="$2" dst="$CLAUDE_DIR/$rel"" —local은 모든 인수를 전개한 후 대입하기 때문에, 같은 줄의 $rel은 외부 변수를 가져옵니다. 호출하는 쪽에 우연히 동명이인 변수가 있었기 때문에 **작동하는 것처럼 보였습니다**(shellcheck가 발견).- pycache/*.pyc를 읽는 sed가 illegal byte sequence로 비정상 종료되어, 도입 전체에까지 영향을 미쳤습니다. 첫 번째 테스트가 통과한 것은 직전에 pycache`를 지웠기 때문이었습니다.

둘 다 '한 번 작동했다'는 근거로 삼았더라면, 그대로 공개했을 것입니다.

3. 알림은 너무 많이 보내는 순간 무의미해진다

시작 시 알림은 최대 3줄로 제한하고, 같은 내용은 일정 기간 재알림하지 않도록 제한을 걸었습니다.

처음에는 '쌓여 있는 것은 전부 알려주자'라고 생각해서 만들었는데, 이것은 실패였습니다. 매번 7줄도 8줄도 나오면, 인간은 3일 만에 읽지 않게 됩니다. 그리고 정말 봐야 할 한 줄이 묻힙니다.

• 해설: 경보 피로(alert fatigue)는 운영 감시 분야에서는 상식적이지만, 개인의 Vault에서도 평범하게 발생합니다. 알림의 가치는 '보낸 개수'가 아니라 '읽힌 개수'로 결정됩니다.

🎁 전체를 다 넣지 않아도 가져갈 수 있는 생각

리포지토리 전체를 도입하기에는 무거울 때라도, 이 두 가지는 단독으로 효과적입니다.

Vault의 CLAUDE.md는 500단어 이내로 유지한다. 이것은 매 세션 로드되기 때문에, 길수록 매 턴마다 과금되고 게다가 지켜지기 어렵습니다. 자세한 내용은 별도의 노트 링크로 지정합니다.

백그라운드 작업(Background Job)은 성공했을 때만 성공을 기록한다. 당연하게 들리지만, touch stamp && run_job과 같이 작성하는 실수는 정말 많습니다. 순서를 바꾸는 것만으로도 실패 시 자동으로 재시도되도록 만들 수 있습니다.

✍️ 요약: 만드는 쪽은 충분하니, 망가지지 않게 하는 쪽을 만들자

• Obsidian × AI에서 막히는 것은 '노트를 만드는' 쪽이 아니라 '만든 후'입니다.
• 자동화의 목표는 '자동으로 수행하는 것'보다 '스스로 기억하지 않아도 되는 상태'를 만드는 것입니다. - 상태 파일은 성공했을 때만 진행합니다. 실패를 붙잡고 있으면 조용히 죽습니다.
• 구문 검사(Syntax Check)가 통과해도 동작이 보장되는 것은 0입니다. 반드시 실행해서 확인해야 합니다.

전체 코드는 GitHub에 있습니다. macOS 전용이며, MIT 라이선스입니다.

모두 넣을 필요는 없습니다. 우선 /lint만 실행하여 자신의 Vault에 몇 개의 고립된 노트와 링크 끊김이 있는지 확인해 보세요. 아마 상상했던 것보다 많을 겁니다. 제가 처음 실행했을 때, 그 숫자에 깜짝 놀랐습니다.

Discussion