Personal Assistant - 문서 참조 구조 정의

TL;DR

목적: Claude가 참조하는 여러 문서 및 다른 리포지토리/폴더와의 연결
핵심
- System Prompt: 프롬프트 최적화
- CLAUDE.md, INDEX.md

개요

아마 프로젝트를 진행하고 실제로 내가 사용하면서, Claude는 여러 문서를 생성하고 업데이트 할 것이다.
그 중에는 /compact를 위한 Handoff 문서와 같은 임시 파일, 해야 할 일들을 잠시 적어놓는 todo 리스트 파일, 추후 개선이나 과거 행적(?) 추적을 위한 로그 파일 등, 다양한 목적의 파일들이 있을 것이다.

어느정도 규모를 잡은 이후, 내가 고민했던 다음 스텝은 이 문서들을 어떻게 관리할 것인가였다.

Claude의 기본 문서 참조 구조

Claude를 포함한 AI Agent들은 기본적으로 모든 프롬프트에 기본적으로 주입되는 시스템 프롬프트를 사용자가 관리할 수 있도록 한다.
예를들어 이전까지 내가 사용하던 Windsurf나 다른 툴들의 경우 global-rule 혹은 Agents.md를, 클로드의 경우에는 CLAUDE.md 라는 파일을 둔다.

CLAUDE.md

더 좋은 CLAUDE.md 작성을 위해, 여러가지 팁들이 알려져있다:

한국어보다는 영어로 작성하는 것이 토큰 절감 측면에서 유리하다.
Anthropic에서는 가급적 CLAUDE.md를 간결하게 유지할 것을 권고. 본인은 200Line 이내로 관리하고 있음.
여기에 모든 내용을 담을 필요 없음. 필요할 때 에이전트가 적절한 파일을 읽을 수 있도록 index만 잘 걸어줘도 좋음

아무래도 매 프롬프트마다 같이 보내지는 시스템 프롬프트이기 때문에, 이 CLAUDE.md가 얼마나 잘 관리되느냐가 곧 토큰, 응답 시간, 품질 모두에 영향을 끼칠 수 밖에 없는 구조이다.

구조

초기에 생각했던 구조는 위 이미지와 같다.
가장 신경썼던 부분은 “Claude가 당장 필요없는 문서는 읽지 않도록” 하는 것이었다.
즉, ‘항상 로드되는 것’과 ‘필요할 때 읽는 것’을 물리적으로 가르되, 필요한 기능으로의 라우팅(routing)이 문제없이 진행되도록 하는 것이 주요 과제였다.

흐름

큰 흐름을 설명하자면, CLAUDE.md에서부터, 에이전트는 필요하다고 판단될 경우 하위 문서를 따라가고 따라가서 필요한 내용을 찾아가는 과정을 겪게된다.

CLAUDE.md에서 가장 기초적인 내용들을 잡아준다. (인격, 응답 방식, 작업 방식, 로깅, …) 가장 중요한 것은, “어떤 상황이 되면 → INDEX의 어떤 부분을 참고해서 작업을 진행해라”라고 명시되어있다는 점.
“필요하다면” INDEX.md에서 필요한 내용을 찾는다. “필요하면 저기 가서 너가 직접 읽어” 라는 방식을 취하므로, 내용이 길어지지 않도록 작성되어있다.

실제 내용 일부인데, 위 사진과 같이 일종의 Table을 만들어서 언제 어떤 파일을, 어떤 스킬과 함께 사용할 수 있는지를 걸어놓은 문서이다.

3-a. 실제 어떤 도메인 기능을 이용하기 위해, 해당 도메인의 작업 규칙을 모아둔 RULES.md를 읽는다. 여러 문서의 CRUD를 다루므로, 주된 내용은 어떤 문서를 언제, 어떻게 수정하고 언제 어떤 문서를 어떻게 읽어야하는지에 대한 내용이다.

3-b. 만약 Obsidian Vault에 접근하는 등 이 리포지토리에서의 작업 범위를 넘어가게 된다면, 이때는 해당 리포지토리의 사용 설명서를 명시해둔 또다른 CLAUDE.md나 INDEX.md를 참조한다.

물론 위의 모든 문서들을 내가 실제로 읽거나 편집할 단계는 지났으므로, 대부분은 영문으로 바꿔둔 상태이다.

두 축(Axis)

처음에는 문서들을 그냥 .claude 폴더에서 관리하고자 하였으나, 점점 쌓이면서 구조를 손봐야 할 필요성을 느꼈다.
내 방법이 정답인지는 모르겠으나, 나는 처음부터 두 개의 축으로 문서 관리를 강제하기로 하였다.

X-axis: 무엇에 관한 문서인가? (주제)
- 관심사 별로 분류한 것. 각 관심사는 유사한 성격의 docs로 볼 수 있다.
- 여러 종류의 Todo, Logging, Handoff 문서들이 생겨나게 되는데, Todo들은 Todo끼리, Logging은 Logging끼리 모아두어, 동일한 규칙으로 각 문서들을 관리할 수 있다.
Y-axis: 관심사를 어떻게 관리하는가? (정리 방법)
- 모든 관심사는 대체로 유사한 구조를 갖게 된다 (이 구조에 종속되지 않는다면, 별도의 repository를 만드는 편이 편하다)
- 처음 보는 도메인이더라도 일단 “RULES.md부터 열면 된다”가 항상 성립하고, 공통되는 뼈대는 INDEX.md에 한 번만 적어두면 되므로 확장에 용이하다.

Problem & Solve

1. MEMORY.md

claude는 기본적으로 MEMORY.md라는 문서를 관리한다.
문제는, 여기엔 언제 어떤 내용이 들어오고 어떤 내용이 삭제될지 모른다는 점이다.
즉 오늘 기억하던 메모리가 내일은 휘발될 수 있기 때문에, MEMORY.md에 어떤 내용이 들어있든 신경쓰지 않는 구조로 설계하였다.

2. HANDOFF, TODO, LOG 문서들

기존에는 특히 HANDOFF, TODO, LOG 문서들이 뒤섞여 사용되고는 했었다.

HANDOFF: /compact 시 다음 채팅 시작 시점에 반드시 참고할 문서. 그러나 TODO의 내용과 중복되거나 이미 끝나서 LOG에 포함된 내용도 중복해서 포함하였음
TODO: 남은 작업. 그러나 완료된 작업도 지워지지 않고 남아있었음
LOG: 개발 일지. 사실상 TODO와 HANDOFF의 혼합체.

그러나 구조 개편 이후, (X-axis로 나눴으므로) 이를 완전히 분리할 수 있었다:

HANDOFF: 당장 다음 채팅 시작 시점에 알아야 할 내용 (마지막 완료 - 진행중 - 관련 todo)
TODO: 남은 작업 및 변경 후 검증 대기중인 작업들. 완전 완료된건 LOG로 이전.
LOG (Dev-log): 언제 어떤 부분이 왜 바뀌었는지를 기술하는 일지. “xyz 작업 남음” 등은 TODO나 HANDOFF로 모두 이전

특히 제일 상단에 RULES.md를 따로 둠으로써, 위 문서들의 책임 범위와 관리 방식이 명확하게 정의되었기에 서로 ‘reference’는 할지언정 (ex: todo의 “xyz” 항목 참고), 중복되는 내용은 크게 줄어들어, 문서 간 정합성이 어긋나는 빈도가 크게 줄어들었다.

그리고 LOG 부분은 추후 로깅 시스템을 고도화하여 hill-climbing을 구현하기위해 필수적으로 거쳤어야 했던 항목이었던 만큼, 충분한 시간을 투자할만한 작업이었다는 생각이 든다.

결과

CLAUDE.md의 길이가 85 → 40줄로 대폭 감소. 세션 시작 토큰 절감
HANDOFF, TODO, LOG의 완전한 책임 분리
- 부가적인 효과로, 중복이 감소하고 레퍼런스 구조로 가면서 문서 정합성과 간결성도 확보