Claude Code로 AI 지식관리 시스템(AKM)을 손으로 뜯어본 80분
2026.07.26
📝 한줄 요약
"AI에게 자료만 던져주면 알아서 정리해줄 것"이라 생각했다가, GPTERS AKM 1주차 워크숍을 Claude Code와 함께 끝까지 밟아보면서 그게 착각이었다는 걸 깨달았다. 대신 실제 파일 3개를 만들고, 자체 검증까지 통과시켰다.
바쁘시면 이것만 읽어도 돼요:
Claude Code로 AI 지식관리 프레임워크(AKM) 실습을 완주하고, 실제 파일 3개를 만들어 검증 스크립트까지 통과시켰다
처음엔 "자료를 넣으면 AI가 알아서 분류해줄 것"이라 오해했는데, 그게 아니라는 걸 이해하는 데 시간이 꽤 걸렸다
핵심 해결책은 "자동화되나요?"라고 뭉뚱그려 묻는 대신 "이 코드나 문서에 자동화 로직이 있나요?"라고 구체적으로 물은 것
강사님께 물어보려던 질문의 답이, 이미 프로젝트 문서 안에 있었다는 걸 AI가 직접 찾아준 순간이 인상 깊었다
"PASS"라고 적기 전에 실제로 한 번 실행해보라고 요구했더니, 진짜 근거 있는 결과가 나왔다
완주 후엔 이걸 실제 진행 중이던 유튜브 아카이브 프로젝트에 적용할 구체적인 계획까지 세웠다
🎯 이런 분들께 도움돼요
개인 지식관리(옵시디언, 노션 등)를 하고 있지만 AI 에이전트와는 아직 연결하지 못한 분
"AI에게 자료만 주면 알아서 정리해줄 것"이라 기대했다가 실망한 적 있는 분
비개발자지만 AI 워크숍이나 실습을 그냥 따라 하지 않고, 근거를 직접 확인하며 진행해보고 싶은 분
😫 문제 상황 (Before)
지식관리 프레임워크 자체가 궁금해서 GPTERS AKM 1주차 실습을 시작했다. 노트가 여기저기 흩어져 관리가 안 되는 문제는 익숙했지만, "그 노트를 AI 에이전트가 제대로 운영한다"는 게 정확히 뭘 의미하는지는 감이 잡히지 않는 상태였다.
🛠️ 사용한 도구
도구명: Claude Code
모델: Claude Sonnet 5
특이사항: dexa.art의 브라우저 실습 페이지와 병행해, 실제 AKM 오픈소스 저장소를 함께 열어보며 진행했다
🔧 작업 과정
실습 페이지와 프로젝트 폴더를 동시에 열다
일단 실습부터 이해하고 싶었다.
현재 프로젝트 파일을 확인하고 아래 링크의 실습문제를 설명해줘
https://dexa.art/akm1w/Claude Code는 브라우저로 실습 페이지를 열어 80분짜리 워크숍 구조를 확인하는 동시에, 이미 로컬에 클론되어 있던 AKM 저장소 폴더도 뒤졌다. 신기했던 건, 실습 페이지가 요구하는 "설치 확인" 단계를 이미 통과한 상태였다는 것 — 저장소 상태와 핵심 파일들이 다 갖춰져 있었다.
이어서 진행 중이던 별도 프로젝트(유튜브 채널 영상들을 자동으로 모으고 정리하는 작업)를 이 실습의 "현재 시스템"으로 매핑해보는 과정도 거쳤다. 다만 아직 구축 중인 부분이 많아 세부 내용을 공개하고 싶지 않았는데, "그냥 구축 중 상태로만 적어달라"고 하자 AI는 억지로 채우지 않고 정직하게 빈 상태를 남겨줬다.
"이 예시 폴더, 실습에 써도 되는 거야?"
실습 페이지가 요구하는 대로 진짜 노트 3개를 골라야 하는 단계에서, 프로젝트 안에 이미 있던 예제 폴더가 눈에 들어왔다.
아니면 프로젝트 폴더안에 예시폴더가 있는데 이 폴더가 실습에 사용될수 있는건가?Claude Code가 그 폴더의 파일 7개를 전부 열어 확인한 결과 — 딱 이 실습의 공식 샘플로 만들어진 픽스처였다. 원본, 해석, 적용 사례까지 이미 완결된 형태로 들어있었다. 덕분에 진짜 개인 자료를 공개하지 않고도 실습을 정확한 구조로 밟아볼 수 있었다.
"그럼 이거 다 자동으로 되는 거 아니야?"
여기서부터가 진짜 고비였다. 노트를 분류하고 정제하는 규칙들을 하나씩 배우다 보니, 자연스럽게 이런 궁금증이 생겼다.
그럼 다시 내가 분류하여 지식체계를 분류하고 싶은 자료를 소스 폴더에 놓고
너에게 지시하면 되는거야?여기까지는 맞는 방향이었다. 그런데 이어서,
아니 나는 최대한의 자동화를 목표에 두고 있고, 내가 이미 한 작업물에대해서도
akm 시스템에서 자동을 다시 검증을 거쳐 이 시스템에 맞게 다시 분류가 되는지가
궁금한거여이 질문에 대한 답은 예상과 달랐다. AKM이라는 프레임워크 자체에는 자료를 자동으로 분류하거나 다시 정제해주는 엔진이 따로 없었다. 파일을 직접 열어 확인해봐도, 그 안에 딸린 검증 도구는 "형식이 규칙에 맞는가"만 확인할 뿐, "이 자료를 어디에 넣을지" 판단하는 기능은 없었다.
실제로 그 판단을 하는 건 매번 Claude Code였다 — 다만 저절로 움직이는 게 아니라, 내가 "이거 분류해줘"라고 요청을 보내야 그제서야 Claude가 규칙을 읽고 판단해서 파일을 정리하는 방식이었다. 즉 자료를 폴더에 넣어두기만 하면 알아서 정리되는 게 아니라, 매번 내가 AI에게 요청을 보내야 비로소 움직이는 구조였던 것이다. "한 번 맡겨두면 알아서 돌아갈 것"이라는 기대와, "매번 내가 요청해야 그제서야 Claude가 판단해서 움직인다"는 실제 구조 사이의 간극을 이해하는 데 여러 번의 되물음이 필요했다.
강사님께 여쭤보려던 질문, 문서 안에 이미 있었다
AI 하네스가 자체적으로 가진 메모리 기능과, 이 AKM 시스템이 서로 겹치는 건 아닌지도 궁금했다.
omc의 하네스 엔지니어링과 akm의 엔지니어링이 겹친다는건가?이 질문은 강사님께 따로 여쭤보려고 정리까지 해뒀는데, Claude Code가 프로젝트의 어댑터 설정 문서를 다시 뒤지다가 이미 공식적으로 정리된 답을 찾아냈다. 물어볼 필요도 없이, 만든 사람이 이미 그 경계를 문서로 못 박아둔 상태였던 것이다. 질문을 정리해뒀던 시간이 아깝지 않았던 건, 그 답을 스스로 검증해봤기 때문이다.
"PASS"라고 적기 전에, 진짜로 한 번 시켜봤다
실습 마지막 단계에서 결과물이 통과했는지 판정을 적어야 했는데, 뭐라고 적어야 할지 감이 안 왔다.
평가 판정 부분은 어떻게 해야해?Claude Code는 "아직 아무것도 실행해보지 않았으니 PASS라고 적으면 안 된다"고 먼저 짚어줬다. 그리고 바로 실행을 제안했다.
진행그러자 만들어둔 절차를 실제로 밟았다 — 먼저 목차 파일부터 열고, 거기서 필요한 노트 하나만 골라서 열어보는 과정을. 결과가 나온 뒤에야 비로소 "PASS"라는 글자를 적었다. 미리 짐작해서 적는 것과, 실제로 시켜보고 나온 결과를 적는 것의 차이를 눈으로 확인한 순간이었다.
어렵지만 끝까지, 13단계 완주
13번까지 완료솔직히 중간중간 이해가 안 가서 되묻는 구간이 많았다. 특히 "자동화되는 줄 알았는데 아니다"를 받아들이기까지가 제일 오래 걸렸다. 그래도 하나씩 끝까지 밟았고, 마지막엔 이 워크숍 13단계 전체가 사실 AKM이 원래 정의해둔 7단계 운영 루프를 손으로 한 번 재현해본 것이었다는 걸 알게 됐다.
✅ 결과 (After)
Before vs After
항목 | Before | After |
|---|---|---|
AKM에 대한 이해 | 자료만 넣으면 AI가 알아서 정리해줄 것이라 생각 | 분류·검증은 매번 에이전트에게 판단을 요청해야 하는 일이라는 걸 이해 |
산출물 | 브라우저 워크시트 칸만 채운 상태 | 실제 프로젝트 폴더에 파일 3개를 만들고 자체 검증까지 통과 |
다음 행동 | 막연함 | 유튜브 프로젝트의 배포 문서를 7일 안에 실제 설정과 대조 검증하기로 구체화 |
결과물
실습에서 만든 노트 3개 (분류 결정 기록, 답변 참고용 정리 노트, 에이전트 운영 카드)
프로젝트 색인 파일 갱신 및 자체 검증 스크립트 통과(오류 0건)
💬 이 과정에서 배운 AI 활용 팁
효과적이었던 것
"자동화되나요?"라고 뭉뚱그려 묻지 않고, "이 코드나 문서에 자동화 로직이 있나요?"라고 구체적으로 묻기
"PASS"라고 적기 전에, 실제로 한 번 실행해보라고 요구하기
이렇게 하면 안 돼요
AI가 "될 것 같다"고 말한 걸 검증 없이 그대로 믿기
아직 해보지 않은 일을 미리 판정해서 적어두기
🌍 다른 업무에 적용한다면?
지식관리뿐 아니라 어떤 자동화 도구를 새로 도입할 때든 똑같이 적용할 수 있다. "이게 진짜 자동으로 도는지, 아니면 내가 매번 시작 버튼을 눌러야 하는지"부터 문서나 코드로 직접 확인하는 습관을 들이면, 나중에 "왜 안 되지?"라며 헤매는 시간을 크게 줄일 수 있다.
🚀 앞으로의 계획
다음 7일 안에, 진행 중이던 유튜브 아카이브 프로젝트의 배포 절차 문서를 실제 서버 설정과 하나씩 대조해서 검증해볼 계획이다.
📋 재사용 가능한 프롬프트
프롬프트 1: 자동화 여부 구체적으로 확인하기
"[기능/도구]가 자동으로 되나요?" 대신 "[관련 코드나 문서]에 자동화 로직이 있나요? 있다면 어떤 조건에서 실행되나요?"라고 구체적으로 물어보세요.
프롬프트 2: 판정 내리기 전 실제 실행 요구하기
"PASS라고 적기 전에, 이 절차를 [대상]에 실제로 한 번 실행해보고 그 결과로 판정해줘." [대상]은 본인 상황에 맞게 변경하세요
로그인하고 댓글을 남겨 주세요
김준희님, “자동화되나요?”에서 멈추지 않고 실제 코드와 문서에 자동화 로직이 있는지 확인하고, PASS를 적기 전에 절차를 직접 실행해 보신 과정이 좋았습니다. 형식 검사가 통과했다는 사실과 실제 업무가 의도대로 수행됐다는 사실은 다르기 때문에, 실행 근거가 생긴 뒤 판정한 것이 정확한 Verify입니다.
AKM의 자동화에 대해서는 한 가지를 보충하고 싶습니다. 공개 AKM 코어는 자동 분류 프로그램이라기보다 어떻게 분류하고 실행하고 검증할지 정의한 정책과 계약입니다. 실제 판단과 파일 작업은 Claude Code·Hermes·Codex 같은 실행 에이전트가 담당합니다. 따라서 기본 저장소만 클론한 상태에서는 사용자가 요청해야 움직이는 것이 맞습니다.
다만 AKM이 매번 수동 요청으로만 동작하도록 제한된 것은 아닙니다. 제 경우에는 Hermes의 cron job을 이용해 정해진 시점에 AKM 운영 절차가 자동으로 실행되도록 구성해 사용하고 있습니다. 공개 저장소에 독립적인 자동화 엔진이 들어 있는 것은 아니지만, Hermes가 실행기 역할을 맡아 AKM의 규칙과 절차를 주기적으로 수행하는 구조입니다.
스케줄러, 파일 감시, Git 훅, cron, 각 에이전트의 Adapter를 연결하면 신규 자료 감지 → inbox 적재 → ROUTER 분류 제안 → 사람 승인 → 이동 → lint·검증 같은 흐름도 자동화할 수 있습니다. 코어가 정책과 실행기를 분리해 두었기 때문에, 자동화 범위와 사람의 승인 지점을 프로젝트 성격에 맞게 선택할 수 있습니다.
AI 하네스의 자체 메모리와 AKM의 경계도 문서에서 직접 찾으신 대로 역할이 다릅니다. 하네스 메모리에는 해당 도구가 매 세션 알아야 할 최소한의 규칙과 AKM 정본으로 들어가는 포인터를 두고, 장기 지식·맥락·절차·검증 기록은 AKM이 맡습니다. 같은 내용을 두 곳에 복사하기보다 하네스 메모리가 AKM으로 들어가는 입구가 되는 구조입니다.
공식 픽스처로 원본·해석·적용 노트의 관계를 연습한 것도 안전한 선택이었습니다. 다만 lint의 오류 0건은 스키마·링크 같은 기계적 규칙을 통과했다는 뜻이지, 해석 내용과 분류 판단까지 사실로 검증됐다는 의미는 아닙니다. 원문 직접 대조와 실제 실행 검증은 계속 별도로 필요합니다.
유튜브 아카이브에 적용할 때는 먼저 자동화의 시작 조건을 한 줄로 고정하면 좋습니다. 예를 들어 새 영상 발견 → 원본 URL·메타데이터·자막을 Source로 보존 → Knowledge 후보 생성 → 출처와 누락 검증 → 승인 후 공개처럼요. 어떤 단계까지 자동 실행하고 어디서 사람에게 확인받을지를 정하면, 이번에 발견한 “정책은 있지만 실행기는 별도”라는 구조를 실제 운영 파이프라인으로 연결할 수 있습니다.
꼼꼼한 피드백 감사합니다 ^^
제가 실습을 진행하면서 있었던 궁금한점이 모두 해소가 되었네요.
이제 막 llm-wiki등을 구축하면서 AKM이라는것도 알게되었는데
청강생이지만 수업 잘 따라가도록 하겠습니다~


'자료만 넣으면 AI가 알아서 정리해줄 것'이라는 오해가 착각이었다는 걸 받아들이기까지가 제일 오래 걸렸다고 솔직하게 적으신 부분이 좋습니다. AKM에는 자동 분류 엔진이 따로 없고, 매번 Claude Code에게 분류를 요청해야 판단이 이뤄진다는 걸 파일을 직접 열어 확인하신 과정이 정확합니다.
'자동화되나요?'라고 뭉뚱그려 묻지 않고 '이 코드나 문서에 자동화 로직이 있나요?'라고 구체적으로 물은 것이 핵심 해결책이었다는 정리가 명확합니다. 강사님께 따로 여쭤보려고 정리해둔 질문의 답을, Claude Code가 프로젝트의 어댑터 설정 문서에서 이미 찾아낸 순간도 인상적입니다.
'PASS'라고 적기 전에 실제로 한 번 실행해보라고 요구해서, 목차 파일부터 열고 노트 하나를 실제로 열어본 뒤에야 판정을 적은 태도가 특히 좋았습니다. 아직 해보지 않은 일을 미리 판정해두면 안 된다는 원칙을 스스로 세우신 것도 실무에 바로 쓸 수 있는 교훈입니다.
중간중간 이해가 안 가서 되묻는 구간이 많았지만 13단계를 끝까지 완주하고 실제 파일 3개와 검증 스크립트 통과까지 만들어내신 결과가 훌륭합니다. 유튜브 아카이브 프로젝트의 배포 문서를 7일 안에 실제 설정과 대조 검증하겠다는 다음 계획도 응원합니다!