AI Agent가 관리하는 Obsidian 구조 만들기 - AGENTS.md, 허브 노트, 00_agent_docs 설계

이 시리즈의 1편에서는 일일기록 -> AI 후처리 -> Day Planner 흐름을 보여줬다. 그런데 그 자동화가 한두 번 반짝하고 끝나지 않으려면, 그 뒤에서 에이전트가 길을 잃지 않는 구조가 먼저 있어야 한다.

AI가 똑똑해도 vault가 읽히지 않으면 운영비는 다시 사람에게 돌아온다. 2편에서는 내가 Obsidian vault를 어떻게 나눴고, AGENTS.md, 허브 노트, 00_agent_docs, 로컬 스킬을 어떤 계층으로 배치했는지를 실제 구조 그대로 보여주려 한다.

왜 구조가 먼저 필요한가

먼저 용어를 짧게 맞춰두자

이 글에서 자주 나오는 말만 먼저 짧게 정리하면 이렇다.

• 허브 노트: 한 폴더의 대표 진입점이 되는 안내 노트
• front matter: 노트 맨 위의 YAML 메타데이터 영역
• 위키링크: [[노트 이름]] 형태로 같은 vault 안 다른 노트를 가리키는 링크
• 스킬: 특정 작업 절차를 캡슐화한 에이전트용 로컬 작업 단위

AI도 읽는 vault여야 한다

보통 Obsidian 구조를 이야기할 때는 “내가 보기 편한가”를 먼저 생각한다. AI Agent를 붙이면 기준이 하나 더 생긴다. 사람이 아니라 에이전트도 이 vault를 읽고, 어디에 적어야 하고, 무엇을 건드리면 안 되는지 바로 판단할 수 있어야 한다.

이때 구조는 정리 취향이 아니라 인터페이스가 된다. 폴더 이름, 허브 노트, 전역 지침, 작업별 플레이북이 모두 “에이전트가 이 vault를 어떻게 읽을지”를 결정한다.

구조가 없으면 다시 사람이 정리한다

구조가 없을 때 생기는 문제는 꽤 단순하다.

• 새 노트가 루트나 임의의 폴더에 흩어진다.
• 비슷한 주제 노트가 중복 생성된다.
• TODO와 일반 노트의 경계가 흐려진다.
• 규칙이 바뀌어도 어디를 고쳐야 하는지 모른다.

결국 AI를 붙여도 사람이 다시 뒤에서 정리해야 한다. 내가 1편에서 말했던 “유지비가 너무 커지는 문제”가 구조 레벨에서 다시 돌아오는 셈이다.

내 vault를 이렇게 나눴다

최상위 폴더는 역할 단위로 자른다

내가 실제로 쓰는 구조의 핵심만 뽑으면 이렇다.

/
├── .agents/           # Codex용 로컬 스킬
├── .claude/           # Claude Code용 로컬 스킬
├── 00_agent_docs/     # AI 운영 문서
├── 06_TODO/           # Base Board 실데이터
├── 12_일일기록/       # 일간·월간·연간 기록
├── 13_my/             # 날짜를 벗겨도 남길 장기 메모
├── 14_플레이스/       # 장기적으로 남길 만한 장소 노트
├── _attachments/      # 이미지 첨부
├── CLAUDE.md
└── AGENTS.md

핵심은 “주제”보다 “역할”을 먼저 나누는 것이다.

• 12_일일기록/은 날짜순 원본 기록
• 13_my/는 날짜를 벗겨도 다시 참고할 장기 맥락
• 06_TODO/는 보드가 아니라 실제 마크다운 데이터
• 00_agent_docs/는 에이전트 운영 문서

이렇게 나눠두면 같은 정보라도 어디에 남겨야 하는지 판단이 쉬워진다. 예를 들어 오늘 일기에서 나온 장기 선호는 12_일일기록에 그대로 묻히지 않고 13_my로 승격할 수 있고, TODO는 일반 메모가 아니라 06_TODO/ 실파일로 들어가야 한다는 규칙이 구조 자체에 드러난다.

허브 노트는 README이자 MOC다

이 구조에서 중요한 건 폴더만이 아니다. 대부분의 폴더에는 허브 노트를 둔다. 허브 노트는 파일 목록이 아니라 “이 폴더가 무엇이고, 어디서부터 읽으면 되는지”를 알려주는 README + MOC(Map of Content)에 가깝다.

실제 00_agent_docs 허브는 이렇게 생겼다.

`00_agent_docs/` 폴더 허브이자 단일 진입점. 루트 지침은 [[AGENTS]]와 [[CLAUDE]]에서 확인한다.

## 바로 보기

- 사용자 요구사항: [[사용자 요구사항 메모]]
- 플레이북: [[Base Board 작업 지침]], [[일일기록 일정 작성 플레이북]]
- 장기 메모리: [[장기 메모리 메모]]
- 운영 원칙: [[에이전트 문서 운영]]

이게 중요한 이유는 에이전트가 폴더를 열었을 때 “전수 목록”보다 “대표 진입점”을 먼저 볼 수 있기 때문이다. 새 문서를 만들 때도 허브가 있으면 어디에 소속되는지 자연스럽게 정해진다.

코드블럭 안의 [[AGENTS]] 같은 표기는 Obsidian의 위키링크다. 일반 파일 경로보다 짧고, 허브끼리 연결 구조를 만들기 쉬워서 에이전트가 따라가기도 편하다.

허브가 잘 잡혀 있으면 그래프 뷰에서도 구조가 읽힌다. 아래처럼 허브가 중심이 되면, 단순히 노트가 많이 있는 vault가 아니라 어떤 묶음으로 운영되는지가 한눈에 드러난다.

에이전트는 어떤 문서를 읽고 움직이는가

AGENTS.md는 얇은 라우터다

내 vault에서 AGENTS.md는 모든 걸 설명하는 매뉴얼이 아니다. 역할을 아주 좁게 둔다.

## 이 문서의 역할

- 역할은 `전역 불변 규칙 + 작업 트리거 + 정답 문서 안내`로 한정한다.
- 길이는 대략 200줄 내외를 유지한다.
- 새 노트가 생겼다는 이유만으로 이 문서를 갱신하지 않는다.

즉, AGENTS.md는 얇아야 한다. 전역 작성 원칙, 폴더 구조, 예외 규칙, 문서 라우팅처럼 오래 안 바뀌는 것만 둔다. 세부 절차까지 다 넣기 시작하면 금방 비대해지고, 결국 아무도 안 읽는 문서가 된다.

세부 절차는 00_agent_docs/로 내린다

반복 작업에 필요한 상세 절차는 00_agent_docs/ 아래로 내린다. 실제 운영 문서도 이 기준을 분명히 적고 있다.

## 문서 분류 기준

- 전역 불변 규칙, 공통 경로 패턴, 예외 규칙이면 `AGENTS.md`, `CLAUDE.md`
- 사용자 선호나 금지사항이면 `사용자 요구사항/`
- 단계별 수행 절차면 `플레이북/`
- 안정적인 환경 정보면 `장기 메모리/`
- 폴더 운영 규칙, 인덱스, 유지보수 정책이면 `운영/`

이 계층을 두면 새 정보가 생겼을 때 어디에 적어야 하는지도 분명해진다. 예를 들어 “모든 일반 노트는 한국어로 쓴다”는 AGENTS.md에 갈 전역 규칙이지만, “Day Planner용 ## 일정은 어떤 문법으로 쓰는가”는 플레이북으로 내려가는 게 맞다.

작업별 운영 로직은 스킬에 둔다

여기서 더 아래로 내려가면 작업별 스킬이 있다. 지금 실제로 쓰고 있는 로컬 스킬은 이런 식이다.

.agents/skills/
├── daily-note-followup/
└── organize-instructions/

Claude Code 쪽도 같은 구조를 .claude/skills/에 맞춰 두고 있다. 핵심은 전역 지침 문서가 작업별 절차를 다 품지 않고, 정말 작업 특화된 로직은 스킬 폴더로 내려보낸다는 점이다.

그래서 AGENTS.md는 얇게 유지되고, 스킬은 작업별로 깊어질 수 있다. 이 분리가 없으면 top-level 문서가 금방 플레이북과 스킬의 역할까지 먹어버린다.

이 구조가 실제로 어떻게 동작하는가

예시 1: 새 TODO를 추가할 때

사용자가 할 일을 하나 추가해달라고 하면, 에이전트는 바로 카드 UI부터 건드리지 않는다. 먼저 AGENTS.md에서 TODO / Base Board 라우팅을 보고, 그다음 Base Board 작업 지침과 TODO LIST.base를 확인한다.

실제 .base 파일에는 이런 정보가 들어 있다.

filters:
  and:
    - file.inFolder("06_TODO")
    - status != null
views:
  - type: kanban
    boardColumns:
      - 시작 전
      - 진행 중
      - 완료

이걸 먼저 읽어야 status 값을 추측하지 않고 정확한 문자열로 넣을 수 있다. 즉, 구조가 있으면 에이전트는 “할 일을 어디에 만들지”뿐 아니라 “어떤 스키마로 만들어야 하는지”까지 찾을 수 있다.

실제 TODO 노트 쪽에는 이런 값이 front matter나 속성으로 들어가고, .base는 그 값을 읽어 보드처럼 보여준다.

예시 2: 일일기록을 후처리할 때

1편에서 다룬 daily-note-followup도 같은 구조 위에서 움직인다. AGENTS.md는 12_일일기록의 섹션 소유권과 기본 경계를 설명하고, 실제 일정 문법이나 시간 해석 같은 상세 규칙은 일일기록 일정 작성 플레이북으로 내려간다. 그리고 작업 전체 오케스트레이션은 daily-note-followup 스킬이 맡는다.

이렇게 나눠두면 한 작업 안에서도 역할이 분리된다.

• AGENTS.md: 전역 경계와 라우팅
• 플레이북: 세부 문법과 절차
• 스킬: 실제 작업 순서와 판단 흐름

그래서 한 파일에 모든 판단 로직을 몰아넣지 않아도 된다.

예시 3: 새 규칙이 생겼을 때

이 구조의 장점은 “새 규칙이 생겼을 때 어디를 고칠지”도 분명하다는 점이다.

예를 들어 어떤 규칙이 생겼다고 해보자. 그때 먼저 묻는 질문은 하나다. 이게 전역 불변 규칙인가, 사용자 선호인가, 작업 절차인가?

• 전역 불변 규칙이면 AGENTS.md
• 사용자 선호면 00_agent_docs/사용자 요구사항/
• 작업 절차면 00_agent_docs/플레이북/

이 분류가 있으면 규칙이 늘어나도 문서 체계가 쉽게 무너지지 않는다. 반대로 이 분류가 없으면 모든 게 AGENTS.md 한 파일로 몰리거나, 여기저기 중복된다.

마무리

2편에서 말하고 싶었던 건 단순하다. 좋은 Obsidian 개인 비서는 좋은 모델만으로 유지되지 않는다. AI가 읽을 수 있는 구조, 얇은 전역 지침, 허브 노트, 작업별 플레이북과 스킬이 함께 있어야 오래 간다.

1편에서 보여준 일일기록 -> 후처리 -> Day Planner 흐름도 결국 이 구조 위에서만 안정적으로 돌아간다. 구조는 보기 좋으라고 만드는 게 아니라, AI가 일관되게 일하기 위한 인터페이스다.

다음 편에서는 이 구조를 오래 굴리기 위해 규칙과 기억을 어떻게 유지보수하는지, 즉 지침이 커질 때 어떻게 정리하고 분리하는가 쪽을 이어서 다뤄보려고 한다.