AI 에이전트와 함께 굴러가는 개인 지식관리 시스템을 만들기 위한 최소 스타터킷입니다. 잘 쓴 노트 앱 설정이 아니라, 에이전트가 지식 기반을 읽고 쓰고 유지보수하는 시스템의 뼈대를 다룹니다.
이 저장소는 운영 중인 개인 시스템의 복제본이 아닙니다. 공개 가능한 패턴, 합성 예시, 빈 템플릿만 추려낸 시드입니다. 개인 dotfiles, 메모리, 세션 로그, 시크릿, 호스트 정보, 비공개 프로젝트는 포함하지 않습니다. 필요한 부분만 골라 자기 환경에 맞게 구현하세요. 개인 시스템 전체를 이 저장소 구조에 복사하지 마세요.
킷의 구조는 AKM Index의 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회면 충분합니다.
예제를 복사하기 전에 경로, 런타임의 훅 계약, exit code를 확인하세요. 이 저장소의 스크립트는 최소 패턴이며 모든 환경에서 바로 실행되는 설치 프로그램이 아닙니다.
AI가 만든 결과를 실제 업무에 넣기 전에는 docs/verification-boundaries.md로 위험 등급을 정하고 templates/verification-contract.md를 채우세요. 생성 능력과 검증 능력은 별개의 시스템입니다.
이 킷을 실제로 시도했다면 사용 피드백 이슈에 다음 내용을 남겨주세요.
- 사용한 구성 요소와 런타임
- 실제로 도움이 됐거나 막힌 지점
- 재현 가능한 최소 예시
- 문서나 템플릿에 반영할 개선안
AI 에이전트가 이슈 초안을 만들거나 등록해도 됩니다. 다만 먼저 공개용 초안을 보여주게 하고 사람이 확인한 뒤 제출하세요. 원시 로그, 설정 파일, 메모리 내용, 환경변수, 절대 경로, 호스트명, 개인 및 조직 정보, 비공개 프로젝트명은 이슈에 넣지 마세요. 합성 예시나 필요한 부분만 지운 최소 발췌를 사용하세요. 자세한 절차는 CONTRIBUTING.md와 SECURITY.md에 있습니다.
특정 도구(Claude Code, Obsidian 등)의 설치나 사용법, 특정 벤더의 API, 개인 시스템의 완성된 설정 묶음은 다루지 않습니다. 패턴은 도구 중립적으로 썼고, 예제 코드는 Claude Code의 훅 계약을 기준으로 했지만 다른 에이전트 런타임에도 같은 구조가 적용됩니다.
MIT. 이슈와 PR을 환영합니다. 특히 이 패턴을 다른 런타임에 이식한 사례와 실제 사용 중 발견한 결함을 공유해주시면 검토해 반영합니다.
박현우 (서울대학교), AKM 보드의 hp-2026-07 시스템에서 일반화.
변경 이력은 CHANGELOG.md에 기록합니다.