본문으로 건너뛰기

CMDS System Files 쉽게 이해하기

이 문서는 무엇인가​

이 문서는 아래 GitHub 저장소가 무슨 용도인지 초보자도 이해할 수 있게 풀어서 설명한 안내문입니다.

  • https://github.com/johnfkoo951/cmds-system-files

한 줄로 말하면 이 저장소는, Obsidian 볼트에서 사람과 AI가 같은 규칙으로 문서를 읽고 정리할 수 있게 만드는 기준 파일 모음입니다.

즉, 단순한 메모 모음이 아니라, "이 볼트에서는 어떤 문서를 우선 읽고, 어떤 형식으로 파일을 만들고, 어떤 규칙으로 링크를 쓰는지" 를 정리한 운영 매뉴얼 세트에 가깝습니다.

왜 이런 게 필요한가​

Obsidian을 혼자 간단히 쓰는 정도라면 없어도 됩니다. 하지만 아래처럼 쓰기 시작하면 규칙이 꼭 필요해집니다.

  • 노트가 수천 개로 늘어날 때
  • AI에게 정리/요약/초안 작성을 자주 맡길 때
  • 여러 사람이 같은 볼트를 같이 다룰 때
  • 파일명, 폴더 구조, 링크 방식이 자꾸 흔들릴 때
  • 어떤 문서를 AI가 먼저 읽어야 하는지 정하고 싶을 때

즉, 이 저장소는 “Obsidian을 그냥 메모앱이 아니라, AI와 함께 쓰는 체계적인 지식 시스템으로 운영하려는 사람” 에게 맞는 구조입니다.

핵심 개념 한 번에 보기​

이 프로젝트는 크게 3가지로 보면 쉽습니다.

1. 시스템 파일​

AI와 사람이 참고할 핵심 기준 문서입니다.

예:

  • CLAUDE.md
  • AGENTS.md
  • CMDS.md
  • CMDS-Guide.md
  • CMDS-Head-Quarter.md

쉽게 말하면:

  • 어떤 파일이 제일 우선인지
  • 어떤 역할의 문서인지
  • 어떤 규칙으로 볼트를 운영하는지 를 적어둔 문서들입니다.

2. 공통 룰 파일​

반복되는 규칙을 따로 뽑아둔 파일입니다.

예:

  • 들여쓰기 규칙
  • frontmatter 규칙
  • 파일 생성 규칙
  • wikilink 규칙
  • 디렉터리 구조 규칙

쉽게 말하면: "매번 같은 설명을 길게 하지 말고, 공통 규칙은 따로 빼서 같이 참조하자"는 구조입니다.

3. 아키텍처 패턴​

AI가 이 볼트를 읽을 때 어떤 방식으로 판단할지에 대한 설계 원칙입니다.

예:

  • 우선순위(precedence)
  • STATIC / DYNAMIC 구분
  • @include
  • Essential
  • memory-type
  • token-estimate

초보자 입장에서는 이걸 “AI가 문서를 읽고 행동할 때의 운영 규칙” 정도로 이해하면 충분합니다.

파일별 역할을 쉽게 풀어보면​

CLAUDE.md​

Claude Code 같은 특정 AI에게 주는 기술 가이드입니다.

쉽게 말하면:

  • "이 AI는 이렇게 행동해라"
  • "이 볼트에서는 이런 규칙을 따라라" 를 적은 문서입니다.

AGENTS.md​

Claude 외의 다른 AI 에이전트용 가이드입니다.

쉽게 말하면:

  • Gemini
  • Codex
  • Cursor 같은 도구들이 참고할 수 있는 공통 규칙입니다.

CMDS.md​

이 시스템의 철학과 맥락 설명입니다.

쉽게 말하면:

  • 왜 이런 구조를 쓰는지
  • 이 지식 시스템이 무엇을 목표로 하는지 를 설명하는 문서입니다.

CMDS-Guide.md​

실제 운영 기준 문서입니다.

쉽게 말하면:

  • 실제로 어떻게 쓰는지
  • 어떤 기준으로 관리하는지 를 적은 사용 설명서에 가깝습니다.

CMDS-Head-Quarter.md​

전체 탐색 허브 문서입니다.

쉽게 말하면:

  • 이 시스템 안에서 어디를 먼저 보면 되는지
  • 어떤 문서가 어디에 있는지 를 안내하는 목차 역할입니다.

초보자가 특히 이해해야 하는 핵심 개념​

1. precedence​

파일 우선순위입니다.

예를 들어:

  • 어떤 문서에서는 A라고 쓰여 있고
  • 다른 문서에서는 B라고 쓰여 있다면

우선순위가 높은 파일 기준으로 해석한다는 뜻입니다.

왜 필요하냐면, AI가 서로 다른 문서를 읽고 충돌할 때 기준점이 있어야 하기 때문입니다.

2. @include​

공통 규칙 파일을 불러오는 방식입니다.

쉽게 말하면:

  • 같은 규칙을 여러 파일에 복붙하지 말고
  • 한 군데에 적고 가져다 쓰자 는 개념입니다.

3. STATIC / DYNAMIC​

문서 안에서 자주 안 바뀌는 부분과 자주 바뀌는 부분을 나누는 개념입니다.

AI 입장에서는 이 구분이 있으면 어떤 정보를 더 안정적으로 봐야 하는지 판단하기 쉬워집니다.

4. memory-type​

이 문서가 어떤 종류의 기억인지 표시하는 개념입니다.

예:

  • 참고용인지
  • 사용자 관련인지
  • 피드백인지

이런 분류가 있으면 AI가 문서를 더 잘 다룰 수 있습니다.

5. token-estimate​

이 문서를 읽을 때 대략 얼마나 무거운지 알려주는 정보입니다.

쉽게 말하면:

  • 문서가 짧은지
  • 긴지
  • AI가 읽을 부담이 큰지 를 미리 알 수 있게 하는 장치입니다.

초보자 기준으로 이 저장소를 어떻게 보면 되나​

처음 보면 어려워 보이지만, 사실 아래 순서로 보면 훨씬 쉽습니다.

1단계​

"이건 Obsidian 메모 내용 자체가 아니라, Obsidian 운영 규칙 세트다" 라고 이해합니다.

2단계​

핵심은 파일 5개 + 공통 룰 5개 + 설계 패턴 9개라고 생각합니다.

3단계​

처음부터 전부 따라 하지 말고, 아래 3개만 먼저 가져가도 충분합니다.

  • 파일 우선순위 정하기
  • 공통 규칙 파일 분리하기
  • 파일명/폴더 구조 기준 정하기

즉, 초보자라면 이 저장소를 그대로 복제하기보다, “내 Obsidian에도 운영 규칙 파일 하나쯤은 있어야겠다” 정도로 받아들이는 게 좋습니다.

이런 사람에게 특히 유용함​

  • Obsidian에 노트가 계속 많아지는 사람
  • AI에게 문서 정리와 초안 작성을 자주 맡기는 사람
  • Claude, ChatGPT, Gemini 같은 여러 AI를 같이 쓰는 사람
  • 폴더 구조와 파일명 규칙을 체계화하고 싶은 사람
  • 나중에 볼트를 오래 유지하고 싶은 사람

초보자에게는 어떤 부분만 가져오면 좋은가​

전체 구조를 한 번에 다 가져오면 어렵습니다. 초보자라면 아래만 먼저 적용해도 충분합니다.

추천 1. 운영 규칙 문서 1개 만들기​

예:

  • VAULT-GUIDE.md
  • SYSTEM.md
  • AI-GUIDE.md

여기에 아래 정도만 적어도 좋습니다.

  • 폴더 구조
  • 파일 제목 규칙
  • 링크 규칙
  • AI가 읽을 때 우선 볼 문서

추천 2. 공통 규칙 3개만 먼저 정하기​

  • 파일명 규칙
  • 템플릿 규칙
  • 링크 규칙

추천 3. AI용 기준 문서 따로 두기​

예:

  • "이 볼트에서 AI는 Daily / Projects / Guides를 우선 읽는다"
  • "민감정보는 요약 대상에서 제외한다"
  • "결정사항 / 할 일 구조를 우선 추출한다"

이 정도만 있어도 AI 활용이 훨씬 안정됩니다.

이 저장소를 그대로 쓰기 전에 알아둘 점​

  • 이건 꽤 고도화된 PKM 시스템 기준입니다.
  • 10,000개 이상 노트를 운영하는 환경을 전제로 한 부분이 있습니다.
  • 그래서 초보자라면 전부 그대로 적용하기보다, 필요한 개념만 골라서 단순화하는 것이 더 좋습니다.

즉, 이 저장소는 "초보자용 완제품"보다는 잘 정리된 참고 사례에 더 가깝습니다.

초보자용 한 줄 요약​

cmds-system-files는 Obsidian에서 사람과 AI가 같은 규칙으로 문서를 읽고 정리할 수 있게 만드는 운영 기준 파일 세트입니다.

Team Library와 연결해서 보면 좋은 문서​

같이 기억하면 좋은 포인트​

  • 초보자는 전부 따라 하지 않아도 됩니다.
  • 핵심은 "메모"보다 "운영 규칙"을 따로 둔다는 발상입니다.
  • AI를 자주 쓸수록 이런 기준 문서의 가치가 커집니다.