"CLAUDE.md라는 헌법에 모든 법을 욱여 놓았었다." — 박정기님 의 LLM위키·하네스·루프 엔지니어링을 실행한 것들
2026.07.28
"CLAUDE.md가 헌법이면, 그 헌법에 법률 전부를 적어놓은 셈이었다" — 박정기님의 LLM위키·하네스·루프 엔지니어링을 듣고
하려던 것
바로 앞 시간에 온톨로지·오픈크랩 강의를 듣고 나서, 곧바로 이어진 이 강의를 들었습니다. 사실 저는 이미 CLAUDE.md(Claude에게 항상 먹이는 규칙 문서)를 꽤 오래 써왔고, memory 시스템도 나름 잘 쌓아왔다고 생각하고 있었습니다. "같은 클로드 코드를 써도 결과가 왜 갈리는가"라는 강의 제목을 보고도, 솔직히 "나는 이미 잘 하고 있는 쪽 아닐까" 하는 마음으로 들어갔습니다.
그 마음이 강의 중간에 뒤집혔습니다.
강의에서 인상 깊었던 것
"Gold in, Gold out" — 도구가 아니라 먹이는 지식의 문제
강사는 LLM을 "똑똑한 자동완성"이라고 정의했습니다. 학습된 것만 알 뿐, 제 회사·제 문서·제 사고방식은 전혀 모른다는 것이죠. 그래서 암묵지를 AI가 읽기 좋은 마크다운으로 외재화해 "위키"를 만들고, CLAUDE.md 같은 "헌법" 문서에는 그 위키의 경로만 적어두면, AI가 필요할 때 알아서 찾아 읽는다는 게 핵심이었습니다.
"이제는 개발보다 이 마크다운(위키) 만드는 데 더 시간을 쓴다" — 강사가 인용한 안드레이 카파시(OpenAI 창립 멤버)의 말
하네스 엔지니어링 — 컨텍스트·도구·규칙이라는 세 가지 고삐
"하네스"는 말에 씌우는 고삐입니다. 제약이 없으면 AI도 물에 퍼지는 잉크처럼 결과가 제멋대로 흩어진다고 했습니다. 무엇을 보여줄지(컨텍스트), 무엇을 실행하게 할지(도구), 어떻게 일할지(규칙) — 이 세 가지를 명확히 잡아줘야 한다는 설명이었습니다.
기술 부채와 인지 부채
가장 뜨끔했던 부분입니다. "오토파일럿처럼 이해·검토 없이 코드를 계속 쌓으면 왜 됐는지 아무도 모르는 상태가 된다"는 게 기술 부채, "사람이 계획을 안 읽고 결과만 받으면 스스로 판단하는 능력이 무뎌진다"는 게 인지 부채라고 했습니다. 강사는 이걸 갚는 가장 값싼 방법이 "이미 만든 걸 다시 읽어보는 것"이라고 했습니다.
나에게 적용해 보니
강의를 듣자마자 제 CLAUDE.md를 다시 열어봤습니다. 252줄이었습니다. 블로그 규칙, 브레인노트 규칙, 플라우드 저장 규칙, 폴더 지도가 전부 한 파일에 있었습니다. 블로그 글 하나 쓸 때도 브레인노트 규칙까지 매번 같이 읽히고 있었던 셈입니다. 강사가 경고한 바로 그 "통짜 문서" 상태였습니다.
그래서 실제로 네 가지를 바로 실행했습니다.
1. CLAUDE.md를 헌법-법률로 분리했습니다. 252줄이던 CLAUDE.md에서 블로그·브레인노트·플라우드·폴더맵 규칙을 ~/.claude/rules/ 아래 파일 4개로 뽑아내고, CLAUDE.md에는 "이 작업엔 이 파일을 읽어라"는 인덱스 표만 남겼습니다. 109줄로 줄었습니다. 겸사겸사, 다른 AI 도구에도 복사해서 쓸 수 있는 "핵심 사실 팩"(발표자 명단, 폴더 구조, 블로그 규칙 요약)을 옵시디언의 기존 온톨로지 맵 문서에도 추가했습니다.
3. 콘텐츠 파이프라인의 "재작업 금지" 원칙에 예외 조건을 넣었습니다. 제가 쓰는 콘텐츠 자동화 스킬에는 "재작업(재생성) 금지" 원칙이 있는데, 이건 이 강의의 "루프 엔지니어링"(검증될 때까지 반복)과 정반대처럼 보였습니다. 둘 다 맞는 말이었습니다 — 판단 기준이 빠져 있었을 뿐입니다. "되돌리기 어렵거나, 고위험이거나, 접근법 자체가 갈릴 때"만 예외로 재작업을 허용한다는 한 줄을 추가했습니다.
4. 사례게시글 쓸 때 전사록을 다시 읽지 않기로 했습니다. "Gold in, Gold out"은 제 콘텐츠 파이프라인의 "한 번 조사·검증하고 하나의 원본에서 모든 걸 파생시킨다"는 원칙과 사실 같은 말이었습니다. 그래서 사례게시글 스킬에 "강의 노트(Claude 요약+So What)를 소스오브트루스로 쓰고, 원본 전사록을 처음부터 다시 읽지 않는다"는 원칙을 명시했습니다. 지금 이 글도 그렇게 쓰고 있습니다.
5. 가장 오래 안 열어본 스킬을 다시 읽었습니다. "인지 부채를 갚는 값싼 방법은 다시 읽는 것"이라는 말을 듣고, 제일 오래 안 건드린 keyword-discovery 스킬을 열어봤습니다. 정말로 문제가 있었습니다 — 맨 위에 "이제 이 스킬 대신 다른 스킬을 쓴다"는 경고가 한 줄 있는데, 그 아래로 200줄 넘게 옛날 방식이 여전히 주 경로인 것처럼 상세히 남아 있었습니다. "기본 경로/예외 경로"를 명확히 구분해서 고쳐뒀습니다.
OMC(오마이클로드코드) 설치 전후 비교 — 실제로 뭐가 달라졌나
사실 강의를 들으면서 강사가 소개한 OMC(오마이클로드코드, 이 강의의 LLM위키·하네스·루프 엔지니어링이 이미 구현된 플러그인)를 그 자리에서 바로 설치했습니다. 그리고 이 글에 쓴 1·3·4·5번 작업이 전부 그 이후에 일어난 일입니다. 그래서 "설치 전/후로 뭐가 달라졌나"를 정직하게 비교해보려고 합니다 — 과장하지 않고, 실제로 겪은 것만.
설치 전에는 이랬습니다. 예전에 구글 앱스스크립트로 플라우드 자동저장을 연동해보려던 적이 있었는데, 제가 "너가 말하는 내용을 못 알아듣겠어요. 그러니 너가 전부 해줘요"라고 말할 때까지, 클로드는 "트리거", "동기화" 같은 기술 용어를 그대로 쓰면서 제 눈높이를 스스로 못 맞췄습니다. 뭔가 결정이 필요한 순간에도 저에게 열린 질문을 던져놓고 제가 알아서 판단하게 만드는 경우가 많았습니다.
설치 후 오늘 겪은 변화는 이렇습니다. GWS CLI 설치를 지금 할지 나중에 할지 판단이 필요했을 때, 클로드가 긴 설명 대신 "지금 시작(추천)" / "나중에" 딱 두 개 선택지를 버튼으로 던져줬습니다. 저는 클릭 한 번으로 끝났습니다. 그리고 오늘 CLAUDE.md를 4개 파일로 쪼개는 작업처럼 제 설정 폴더(~/.claude/) 안의 파일을 직접 고치는 일은, 예전 같으면 매번 "이렇게 고쳐도 될까요?" 확인을 거쳤을 법한데 오늘은 그런 지연 없이 바로바로 진행됐습니다. OMC 설정에 "이 폴더는 직접 써도 된다"는 규칙이 미리 정해져 있었기 때문이라고 합니다.
솔직히 아직 못 써본 것도 있습니다. OMC에는 여러 에이전트가 역할을 나눠 협업하는 기능(팀 오케스트레이션)이나, 목표가 검증될 때까지 스스로 반복하는 기능(루프)도 있다고 들었는데, 오늘 한 작업들은 혼자 처리할 수 있을 만큼 규모가 작아서 이런 무거운 기능까지 쓸 일은 없었습니다. 이 부분은 다음에 더 큰 작업을 할 때 실제로 확인해봐야 할 것 같습니다.
오늘 배운 것
"이미 잘하고 있다"는 진단이야말로 가장 냉정하게 다시 봐야 한다 — 저는 CLAUDE.md와 memory 시스템을 이미 갖췄다는 이유로 안심하고 있었는데, 정작 그 문서의 구조 자체가 문제였습니다.
원칙이 충돌하는 것처럼 보일 때는 판단 기준이 빠진 것일 수 있다 — "재작업 금지"와 "루프 엔지니어링"은 반대말이 아니라, 언제 어느 쪽을 쓸지 기준이 없었을 뿐이었습니다.
소스오브트루스는 콘텐츠뿐 아니라 모든 작업에 적용된다 — 강의 요약, 사례게시글, 브레인노트까지 전부 "한 번 만든 원본을 재사용"하는 게 맞습니다.
인지 부채는 새로 만들지 않고 다시 읽는 것만으로도 갚을 수 있다 — 실제로 다시 읽어보니 안 보이던 문제가 바로 보였습니다.
도구를 설치했다고 결과가 바로 좋아지는 게 아니라, 그 도구가 미리 정해둔 규칙(어디는 바로 써도 되는지, 언제 질문으로 확인해야 하는지)이 실제 작업 흐름을 조금씩 부드럽게 만든다 — OMC 설치 전후를 비교해보니, 극적인 변화라기보다 매번 겪던 작은 마찰(확인 절차, 열린 질문)이 하나씩 줄어드는 쪽에 가까웠습니다.
마치며
강사가 마지막에 "1시간 중 55분을 문제 정의에 쓰고 5분 만에 푼다"는 비유를 들며 스스로 "실제 아인슈타인 일화는 아니다"라고 웃으며 정정했던 게 기억에 남습니다. 이 강의를 듣고 제가 한 것도 비슷했습니다 — 새 기능을 만든 게 아니라, 이미 있던 문서를 다시 읽고 구조만 바로잡았을 뿐입니다. 그런데 그 정리 하나로 다음 세션부터는 CLAUDE.md가 더 가벼워지고, 스킬들이 뭘 하는지 더 명확해졌습니다. 앞으로도 새 기능을 추가하기 전에, 이미 있는 걸 다시 읽는 습관부터 들여야겠습니다.
평소에는 조용하다가 강의가 시작되면서 펄펄 날으는 명강사 정기님을 지피터스 2년 만에야 알게 된 것이 부끄럽다.
로그인하고 댓글을 남겨 주세요
oneshot님, “나는 이미 잘하고 있는 쪽 아닐까”라는 마음으로 강의를 들었다가 생각이 뒤집혔다는 시작이 참 솔직해서 좋았습니다. CLAUDE.md를 252줄에서 109줄로 줄이고, 블로그·브레인노트·플라우드·폴더맵 규칙을 네 파일로 분리한 결과까지 보여주셔서 통짜 문서의 문제가 바로 이해됐어요.
재작업 금지와 루프 엔지니어링이 충돌해 보였을 때 둘 중 하나를 버리지 않고 판단 조건을 새로 만든 부분도 인상 깊었습니다. 되돌리기 어렵거나 위험이 크거나 접근법 자체가 갈리는 경우를 따로 구분해두면, 원칙이 많아져도 실제 작업에서 덜 흔들릴 것 같습니다.
가장 오래 안 열어본 keyword-discovery 스킬에서 맨 위 경고와 아래 200줄의 옛 경로가 함께 남아 있었다는 대목은 저도 뜨끔하네요. 새 문서를 계속 만드는 것보다 기존 문서가 지금도 맞는지 다시 읽어보는 일이 왜 필요한지 제대로 보여주는 사례였습니다.
OMC 설치 효과를 거창하게 포장하지 않고, 확인 절차와 열린 질문 같은 작은 마찰이 줄었다고 적어주신 것도 좋았어요. 앞으로 큰 작업에서 팀 기능이나 반복 검증 기능을 써보실 때는 작업 시간뿐 아니라 사람이 중간에 판단해야 했던 횟수까지 전후로 비교해보면 변화가 더 선명하게 보일 것 같습니다.
강의에서 들은 개념을 바로 자기 시스템에 대입하고, 실제 파일과 규칙까지 고친 과정이라 읽는 사람도 자기 설정을 열어보고 싶게 만드는 글이네요. 다음에 더 큰 작업에서 이 구조가 어떻게 버티는지도 궁금합니다.
252줄 CLAUDE.md를 109줄로 줄이면서 ~/.claude/rules/ 아래 파일 4개로 구조를 분리하셨다는 부분, 특히 공감됐어요. "헌법에 법률을 전부 적어뒀다"는 표현이 문제를 정확하게 짚는 것 같아서요.
그리고 가장 오래 안 건드린 keyword-discovery 스킬을 다시 열었더니 맨 위에 "이제 이 스킬 대신 다른 걸 쓴다"는 경고가 있는데 그 아래로 200줄이 구 경로인 것처럼 남아 있었다는 대목 — 실제로 다시 읽어봐야만 알 수 있는 종류의 문제인데, 그걸 인지 부채라는 틀로 이어서 설명하신 게 좋았어요.
"이미 잘하고 있다는 진단이야말로 가장 냉정하게 다시 봐야 한다"는 교훈, 두고두고 생각해볼 것 같아요. 고롱고롱... 이런 정리 글이 올라올 때 좋아져요 🐈⬛




매 구절마다 스터디장님의 격려 덕분에 힘과 용기를 얻습니다. 감사합니다.