OKF vault에 AKM 운영층을 얹고 히스토리까지 정리한 기록

소개

개인 지식 vault를 OKF(Open Knowledge Format) 규약으로 만들어 쓰고 있습니다. knowledge-hub라는 Obsidian vault이고, 위키링크 대신 절대경로 마크다운 링크를 쓰고, 레인마다 index.md를 두고, 변경은 log.md에 남깁니다. 아래에 프로젝트별 작업 vault를 두고 지속가치가 있는 것만 위로 끌어올리는 2층 구조도 얹었습니다. 거시경제를 추적하는 econ-radar에 181개, 논문을 추적하는 paper-radar에 23개가 쌓여 있습니다.

구조는 갖췄는데 계속 걸리는 게 있었습니다. 노트는 쌓이는데 에이전트가 그걸 잘 못 씁니다. 클로드 코드에 vault를 열고 물어도 매번 같은 맥락을 다시 설명해야 하고, 예전에 폐기한 방식을 다시 꺼내 옵니다. 저는 이걸 "노트가 아직 부족해서"라고 생각했습니다.

1주차 강의가 그 진단을 뒤집었습니다. 문제는 양이 아니라 층위가 섞인 것입니다. 원본, 그것을 합성한 지식, 현재의 결정, 과거의 실패가 한곳에 섞여 있으면 에이전트는 무엇이 현재 기준인지 판단하지 못합니다. 강의에서 제시한 AKM은 이를 책임별로 나눕니다. 지식층(source, knowledge)은 답변을 만들 때, 운영층(context, memory, procedure, action, evolution)은 실행할 때 참고합니다.

그래서 이번 주에 세 가지를 했습니다. 내 vault가 지금 어느 층까지 채워졌는지 세고, 비어 있는 층을 만들고, 그 결과를 git에 제대로 남기는 것입니다. 세 번째가 예상보다 훨씬 큰 일이 됐습니다.

진행 방법

사용 도구: 클로드 코드 + 기존 knowledge-hub vault(OKF v0.1) + git

Step 1. 먼저 셌습니다

"꽤 채워졌다"는 느낌을 믿지 않고 레인별로 세었습니다.

cd ~/knowledge-hub
for d in MOCs literature economy decisions playbooks pointers \
         projects publications presentations _meta; do
  printf "%-14s %s\n" "$d" "$(find $d -name '*.md' | wc -l | tr -d ' ')"
done

MOCs 2 · literature 1 · economy 1 · decisions 1 · playbooks 6
pointers 2 · projects 9 · publications 54 · presentations 1 · _meta 2

88개 중 54개(61%)가 publications였습니다. 발행한 결과물을 보관하는 서랍이었던 겁니다.

Step 2. AKM 7층에 겹쳤습니다

운영층 5개 중 실질적으로 채워진 것은 절차 하나였습니다. 매번 맥락을 다시 설명해야 했던 이유가 여기 있었습니다.

Step 3. 비어 있는 층을 만들었습니다

레인 4개와 노트 10개를 신설했습니다. 강의에서 "기존 vault를 버리라는 게 아니다"라고 명시했으니 기존 노트는 하나도 고치지 않았습니다.

가장 값이 나갔던 건 evolution/quality-gates.md입니다. 저는 데이터 분석을 하는 사람이라 "출처 없는 수치는 쓰지 않는다", "비율을 받으면 분모부터 확인한다", "응답 코드가 아니라 결과 저장소의 신규 건수로 검증한다" 같은 기준을 늘 적용합니다. 그런데 그게 제 머릿속과 ~/.claude/CLAUDE.md에만 있고 vault에는 없었습니다. 에이전트가 읽을 수 있는 5개 게이트로 옮겼습니다.

결과를 내기 전에 /evolution/quality-gates.md 의 G1~G5를 순서대로 돌리고,
불통과 항목은 결론 앞에 목록으로 보여 줘. 통과 여부를 추측하지 말고
실제로 확인한 것만 통과로 표시해.

_meta/router.md도 만들었습니다. 새 자료가 들어왔을 때 어느 레인으로 보낼지 정하는 규칙입니다. 강의에서 "라우터 설정은 파일을 직접 열지 말고 에이전트에게 바꿔 달라고 하라"고 한 부분을 그대로 따랐습니다.

Step 4. 커밋을 작업 단위로 나눴습니다

여기서 문제가 드러났습니다. vault에 커밋되지 않은 이전 작업이 68개 파일이나 쌓여 있었습니다. BRIC 동향리포트 원고, 그림 재생성, 검증 스크립트, LinkedIn 아카이브 같은 것들입니다. 이걸 제 AKM 작업과 한 커밋에 섞으면 나중에 "AKM 도입할 때 뭘 바꿨더라"를 찾을 수 없습니다.

파일 단위로 나누려 했는데 log.md 하나가 걸렸습니다. 이전 작업의 항목(2026-07-13, 07-19)과 제가 쓴 항목(07-29)이 한 파일에 섞여 있었습니다. git add -p는 비대화형으로 못 돌립니다.

블록 단위로 수동 분리했습니다.

lines = pathlib.Path('log.md').read_text(encoding='utf-8').split('\n')
start = next(i for i,l in enumerate(lines) if l.startswith('## 2026-07-29'))
end   = next(i for i,l in enumerate(lines) if i>start and l.startswith('## '))
mine, rest = lines[start:end], lines[:start] + lines[end:]
print(f'검산: {len(rest)} + {len(mine)} = {len(rest)+len(mine)} == {len(lines)}')
# 검산: 27 + 7 = 34 == 34

제 항목을 뺀 버전으로 먼저 커밋하고, 원본을 복원해 두 번째 커밋에 넣었습니다. 결과는 68개 + 14개로 깔끔하게 갈렸습니다.

Step 5. 히스토리에서 민감 파일을 제거했습니다

커밋한 68개를 훑어보니 공개 저장소에 올리기 곤란한 것들이 있었습니다.

• 정부 공모 배포문서 4건 (hwp, hwpx, zip)

• 단톡방 대화 로그 1건 (제3자 발언 포함)

• BRIC 공식 원고 양식 2건

• 게재본·원고 docx/xlsx 9건

vault의 .gitignore에는 이미 "저작권 가드: 게재본은 커밋하지 않는다"는 주석이 있었는데 PDF만 막고 docx는 놓치고 있었습니다.

git-filter-repo가 없고 git이 2.24라 --pathspec-from-file도 못 써서, 셸 인용된 경로 목록을 만들어 filter-branch --index-filter로 돌렸습니다.

FILTER_BRANCH_SQUELCH_WARNING=1 git filter-branch --force \
  --index-filter "$(cat index-filter.sh)" --prune-empty -- --all

작업 전에 대상 파일을 물리적으로 복사해 백업했습니다. 이 판단이 뒤에서 저를 살렸습니다.

Step 6. gitignore 사각지대를 찾았습니다

정리하고 나서 "앞으로 뭘 놓칠 수 있나"를 훑었습니다. 그리고 이번 작업에서 가장 아찔한 걸 발견했습니다.

기존 규칙이 전부 publications/ 아래로만 걸려 있었습니다. 그런데 제가 방금 만든 레인이 하필 위험한 곳이었습니다.

• source/는 논문 PDF 원본이 들어가는 자리인데, PDF 차단이 publications/ 한정이었습니다.

• context/는 강의에서 스터디장이 의료 정보와 상담 기록, 카톡 대화 맥락을 여기 둔다고 했던 바로 그 레인입니다.

제가 만든 두 레인이 규칙 밖에 있었습니다. 전역으로 올리고 12가지 경우로 시뮬레이션했습니다.

🚫 source/논문.pdf        ✅ source/노트.md
🚫 context/부부상담.md     ✅ context/current-sprint.md
🚫 context/KakaoTalk*     ✅ literature/논문요약.md
🚫 _meta/api_keys.md      ✅ playbooks/새절차.md
🚫 .env, *secret*

첫 시도에서 source/** 제외 후 .md만 재포함하는 규칙을 썼는데 source/노트.md까지 막혔습니다. git은 부모 디렉터리가 제외되면 안쪽 파일을 되살리지 못합니다. 확장자 규칙으로 바꿔 다시 검증했습니다.

마지막으로 이 경계를 vault 안에 적었습니다. _meta/router.md에 "git 경계" 절을 넣어, 레인에 두는 것과 git이 추적하는 것의 차이, 새 레인을 만들 때의 점검 방법을 남겼습니다. 제 머릿속이나 대화창에만 있으면 다음 세션에서 사라집니다.

결과와 배운 점

측정 결과

배운 점

1. 총량으로 판단하면 안 됩니다. "노트 88개"는 꽤 쌓인 것처럼 들리지만 분류해 보니 61%가 발행물이었습니다. 저는 늘 "비율을 받으면 분모부터 확인하라"고 하면서 제 vault에는 그 습관을 적용하지 않았습니다.

2. 머릿속 기준은 자산이 아닙니다. 품질 기준을 파일로 내리고 나서야 에이전트가 스스로 판정할 수 있게 됐습니다. 그전까지는 결과물이 제 기준을 통과했는지 매번 사람이 다시 봐야 했고, 그게 "AI를 써도 일이 안 줄어드는" 이유였습니다.

3. 규칙은 대화가 아니라 vault에 적어야 이어집니다. router와 git 경계를 문서로 남긴 게 이번 작업에서 가장 오래 남을 부분이라고 봅니다. 세션은 끝나고 대화창은 닫히지만 파일은 남습니다.

4. 새 구조를 만들면 기존 안전장치가 그 구조를 모릅니다. 레인 4개를 늘렸더니 .gitignore가 통째로 사각지대가 됐습니다. 구조를 늘릴 때는 그 구조를 감싸는 규칙도 같이 늘려야 합니다. 이건 AKM만의 이야기가 아닙니다.

5. 커밋 분리는 나중을 위한 투자입니다. 68개와 14개를 섞으면 5분 아끼고, 나눠 두면 반년 뒤에 "그때 뭐 바꿨지"를 1분에 찾습니다. log.md 하나 때문에 수동 분리까지 했지만 할 만했습니다.

시행착오

세 번 어긋났고 두 번은 아슬아슬했습니다.

• 대소문자 하나로 파일을 놓쳤습니다. 제거 대상을 고르는 필터에서 'kakaotalk' in 이름으로 소문자 비교를 해서, 실제 파일명 KakaoTalk이 걸리지 않았습니다. 그런데 이걸 알아챌 기회가 있었습니다. 분류 합계는 16건인데 스크립트 결과가 15건으로 나왔고, 저는 그 차이를 보고도 그냥 넘어갔습니다. 1건 어긋났을 때 멈춰서 확인했어야 했습니다. 2차 패스로 제거했습니다.

• filter-branch가 워킹트리 파일까지 지웠습니다. 인덱스만 건드릴 줄 알았는데 마지막 체크아웃에서 대상 파일이 디스크에서도 사라졌습니다. 미리 떠 둔 백업으로 15건은 복원했는데, 하필 백업 목록이 위의 대소문자 버그로 1건 비어 있었습니다. refs/original을 아직 지우지 않은 상태여서 거기서 꺼냈습니다. gc를 먼저 돌렸으면 그 파일은 복구하지 못했습니다. 복원 후 백업과 SHA-256을 대조해 16/16 일치를 확인했습니다.

• gitignore 재포함 규칙이 동작하지 않았습니다. source/**로 제외하고 !source/**/*.md로 되살리려 했는데 .md까지 막혔습니다. 부모 디렉터리가 제외되면 안쪽을 되살릴 수 없다는 git 동작을 몰랐습니다. 확장자 기반으로 바꿨습니다.

공통점이 있습니다. 셋 다 "확인했다고 생각한 것"에서 났습니다. 그래서 마지막에 12가지 경우 시뮬레이션과 체크섬 대조를 붙였습니다. 눈으로 규칙을 읽는 것과 실제로 걸리는지 돌려 보는 것은 다릅니다.

앞으로의 계획

• 남은 한 층인 action과, evolution의 실패 기록을 채웁니다. 지금 evolution에는 통과 기준만 있고 실패 사례가 없습니다. 위의 시행착오 세 건이 첫 입력이 되겠습니다.

• source/ 레인을 실제로 씁니다. 다음 문헌 수집분부터 원본을 남깁니다.

• 2주차에 econ-radar(181개)에 router 규칙을 태워 분류가 실제로 도는지 봅니다. 가장 큰 스트림이라 시험대로 적당합니다.

• 바이오 도메인 지식을 지식층에 심습니다. 강의에서 한국 건축 법규를 예로 들었는데 제 분야에도 같은 공백이 있습니다. 국내 임상시험 규제나 바이오 데이터 표준처럼 모델이 유독 약한 것들입니다.

도움 받은 글 (옵션)

• 23기 AI지식관리 1주차 강의 (DECK): AKM 7층 구조, index와 router, schema, loop의 역할, 실패를 다음 실행의 규칙으로 삼는 루프

• Cerebras 기술 블로그: 지식을 한곳에 모으지 않고 흩어진 채로 두되 에이전트에게 접근 권한과 인용 규칙을 주는 방식 (스터디장 번역본 공유)

• Karpathy의 LLM Wiki, 고요한 님의 커맨드 스페이스: AKM이 밝힌 두 계보