AI 에이전트와 함께 굴러가는 개인 지식관리 시스템을 만들기 위한 스타터킷입니다. 잘 쓴 노트 앱 설정이 아니라, 에이전트가 지식 기반을 읽고 쓰고 유지보수하는 시스템의 뼈대를 다룹니다.
이 킷은 실제로 운영 중인 시스템에서 일반화한 것입니다. 원본 시스템은 AKM Index v1.0 기준 87.25점(M4)으로 평가받았고, 킷의 구조는 AKM의 5개 필러(Prompt, Context, Harness, Loop, Interop and Governance)와 정렬되어 있습니다. 점수 자체보다 중요한 건 그 점수를 만든 반복 구조입니다. 이 킷이 전달하려는 것이 바로 그 구조입니다.
- 규칙은 문서가 아니라 도구로 강제한다. "~하지 말 것"이라고 적어둔 규칙은 잊힙니다. 같은 규칙을 훅(hook)으로 만들면 잊을 수 없게 됩니다.
hooks/의 예제가 이 전환을 보여줍니다. - 시스템이 시스템을 감사한다. 메모리, 지시 문서, 가드레일 각각에 주기 감사를 붙이고, 감사가 찾은 결함이 당일 수정으로 이어지는 체인을 만듭니다.
audits/의 도구 패턴이 출발점입니다. - 산출물이 다시 시스템을 키운다. 세션에서 배운 것이 메모리로, 발행한 글이 문체 코퍼스로, 실패한 검색이 테스트 픽스처로 환류되는 경로를 설계합니다. 경로가 없으면 대화는 휘발됩니다.
docs/
architecture.md 다섯 계층으로 본 시스템 설계 (AKM 필러 정렬)
operating-loop.md 캡처, 메모리, 감사, 개정의 운영 루프 설계
verification-boundaries.md AI 산출물의 위험 등급과 검증 경계
templates/
CLAUDE.md 전역 지시 파일 스켈레톤
SKILL.md 스킬(온디맨드 지시 자산) 템플릿
spec.md 스펙 주도 개발용 스펙 템플릿
verification-contract.md 반복 작업의 검증 계약 템플릿
memory/MEMORY.md 메모리 프런트 페이지 패턴
memory/memory-file.md 단일 메모리 파일 템플릿
hooks/
README.md 훅 철학: prose 규칙에서 tool-path 가드로
destructive-cmd-guard.sh 파괴적 명령 차단 가드 예제
clone-path-guard.sh 경로 규약 강제 가드 예제
audits/
README.md 감사 설계: 무엇을, 어떤 주기로, 어떤 exit 계약으로
instruction-audit.py 지시 문서와 라이브 설정의 드리프트 감사 패턴
guard-probe-test.sh 가드가 아직 살아있는지 확인하는 프로브 매트릭스
templates/CLAUDE.md를 자신의 전역 지시 파일로 복사하고 자기 환경에 맞게 채웁니다. 처음부터 완벽할 필요 없습니다. 틀린 규칙은 아래 루프가 잡아줍니다.templates/memory/의 패턴으로 메모리 디렉토리를 만듭니다. 세션에서 교정받을 때마다 파일 하나씩 쌓는 것부터 시작합니다.- 자주 어기게 되는 규칙 하나를 골라
hooks/의 패턴으로 가드를 만듭니다. 첫 후보는 보통 "위험한 git 명령"입니다. - 한 달쯤 굴린 뒤
audits/의 패턴으로 첫 감사를 붙입니다. 주 1회면 충분합니다.
AI가 만든 결과를 실제 업무에 넣기 전에는 docs/verification-boundaries.md로 위험 등급을 정하고 templates/verification-contract.md를 채우세요. 생성 능력과 검증 능력은 별개의 시스템입니다.
특정 도구(Claude Code, Obsidian 등)의 설치나 사용법, 특정 벤더의 API. 패턴은 도구 중립적으로 썼고, 예제 코드는 Claude Code의 훅 계약을 기준으로 했지만 다른 에이전트 런타임에도 같은 구조가 적용됩니다.
MIT. 이슈와 PR을 환영합니다. 특히 "이 패턴을 다른 런타임에 이식했다"는 사례를 공유해주시면 킷에 반영합니다.
박현우 (서울대학교), AKM 보드의 hp-2026-07 시스템에서 일반화.
변경 이력은 CHANGELOG.md에 기록합니다.