이 글에서 할 수 있는 것
Claude Code를 **세션이나 PC가 바뀌어도 그동안의 경과를 기억한 채 상담해 주는 '전담 집사'**로 만들 수 있습니다.
사용하는 것은 Claude Code의 표준 기능(CLAUDE.md・서브 에이전트)와 Git뿐입니다. 추가적인 도구나 유료 서비스는 필요하지 않습니다.
어려운 것을 생각할 필요가 없습니다. 템플릿을 복사하여 로컬에 clone하고, 해당 폴더에서 Claude Code를 실행하여 대화를 시작하기만 하면 됩니다.
템플릿은 공개되어 있습니다.
만들고 싶었던 것
시작은 '곤란해서'라기보다는 '전담 집사가 있으면 뭔가 멋있지 않을까'라는 생각이었습니다. 떠올린 것은 『HELLSING』의 월터나 『배트맨』의 알프레드 같은 이미지였습니다. 주인 사정을 이해하고 의도를 파악하여 움직여 주는 집사입니다.
집사는 모든 것을 스스로 처리하는 것은 아닙니다. 주인의 요청에 응하기 위해 적절한 하인들을 고용하고 지시를 내립니다. 그리고 회가 거듭될수록, 더욱 높은 수준으로 주인의 기대에 부응하게 됩니다.
이 집사에 가깝게 만들기 위해서는 Claude Code의 두 가지 한계가 벽이 되었습니다.
첫째는 세션을 닫으면 대화 내용을 잊어버린다는 것입니다. 주인 사정을 이해해 주는 집사라면, 우선 기억하게 만들어야 합니다.
둘째는 기억이 단일 PC에 묶인다는 것입니다. 자동 메모리(auto memory) 기능도 있지만, 저장 위치는 그 PC의 홈 디렉토리 안에 있습니다. 다른 PC나 웹 버전의 Claude Code로 옮기면 인계받을 수 없습니다. 정해진 책상 앞에서만 이야기할 수 있는 집사는 제가 상상했던 모습과는 거리가 멀었습니다.
구조 전체 개요
butler/ ← 이 폴더에서 Claude Code를 엽니다
CLAUDE.md ← 집사의 역할과 기록 규칙 (매번 자동으로 로드됨)
profile.md ← 저에 대해 파악한 것 (취향・환경・관심)
...
포인트는 네 가지입니다.
- 기록을 단순 파일로 만들고, 읽기/쓰기 규칙을 CLAUDE.md에 작성합니다.
- Git으로 동기화하여 어디서든 동일한 기록을 사용합니다.
- Git에 올리지 않을 정보의 저장 공간을 분리합니다.
- 무거운 작업은 전문 에이전트에게 맡기고, 집사는 중계에 전념하게 합니다.
1. 기록을 파일로 만들고 읽기/쓰기 규칙 정하기
CLAUDE.md는 Claude Code가 시작할 때마다 로드하는 파일입니다. 여기에 '시작할 때 읽을 내용', '끝날 때 쓸 내용'이라는 규칙을 작성합니다.
## 세션 시작 시 (매번)
1. `profile.md`와 `open-items.md`를 읽습니다.
2. `journal/`의 최신 1~2 파일을 읽어 직전 경과를 파악합니다.
...
기록을 역할별로 나누는 것이 요령입니다.
| 파일 | 내용 |
|---|
| profile.md | 저의 취향이나 생각 |
| ... | |
| 모든 것을 하나의 파일에 넣으면, 금방 길어져서 로딩 부담이 증가합니다. 분리해 두면, 매번 읽는 것은 profile.md・open-items.md・최근 journal만으로 충분합니다. | |
그 외에도 다음과 같은 세부 규칙을 포함했습니다.
- 날짜는 '어제'가 아니라
2026-10-19처럼 작성합니다 (나중에 읽어도 알 수 있도록).
- 비용이나 기능 등 변하기 쉬운 정보는 기억으로 답하지 않고 공식 문서를 통해 확인하도록 합니다.
- 조사한 내용에는 확인 날짜를 기재합니다.
2. Git으로 동기화하기
기록은 단순 파일이므로, 폴더 전체를 비공개 GitHub 리포지토리에 두면 다른 PC나 웹 버전의 Claude Code에서도 동일한 기록을 사용할 수 있습니다.
CLAUDE.md에는 동기화 규칙도 작성해 둡니다.
## 동기화 (Git)
- 세션 시작 시: `git pull`로 최신화합니다.
- 기록을 업데이트했을 때: 요점이 파악되는 메시지로 커밋하고, `git push` 합니다.
...
이렇게 하면 제가 아무 말도 하지 않아도 Claude가 기록을 업데이트할 때마다 커밋과 푸시를 해줍니다.
3. Git에 올리지 않을 정보 분리하기
비공개 리포지토리라 하더라도, 두고 싶지 않은 정보는 있습니다. 예를 들어 실명이나 근무처, 이력서 원본 파일 같은 것들입니다.
그래서 private/ 폴더를 .gitignore에 넣어 정보의 저장 공간을 분리하는 규칙을 만들었습니다.
- Git에 기록해도 좋은 것: 선호도/생각 방식, 상호작용 경위, 일반화된 이력 (예: "40대 회사원").
private/에만 보관할 것: 개인을 식별할 수 있는 정보, 파일 원본, 근무지/고객의 구체적인 정보.- 애매하면
private/에 두고 사용자에게 Git에 올려도 되는지 확인한다.
파일을 전달하고 싶을 때는 경로만 알려주면 됩니다. Claude가 해당 위치 그대로 읽고 필요한 것만 private/에 복사합니다.
4. 무거운 작업은 전문 에이전트에게 맡기기
사용하다 보면 조사나 작업까지 부탁하게 됩니다. 그러자 두 가지 걱정이 생겼습니다.
- 작업 정보가 너무 많아져서, 집사(butler)의 장점(나의 생각에 공감하는 상호작용)이 희미해진다.
- 전문 작업 때문에 정한 규칙이 다른 주제에도 영향을 미친다.
작업은 서브 에이전트에게 맡기기
서브 에이전트는 자신 전용의 새로운 컨텍스트(context)에서 작동합니다. 부모(집사, butler)에게 돌아오는 것은 최종 보고서뿐입니다. 중간 과정의 작업이 집사의 대화를 가득 채우지는 않습니다.
요청할 때 "결론을 먼저, 10줄 이내로"와 같이 답변 형식을 지정하면, 집사에게는 결론만 남게 됩니다.
규칙은 적용하고 싶은 범위에만 두기
| 규칙의 종류 | 보관 위치 |
|---|
| 나와의 접하는 방식 (전체) | 집사의 CLAUDE.md |
| 특정 전문 에이전트용 | .claude/agents/<이름>.md 본문 |
| 특정 작업 절차 | .claude/skills/<이름>/SKILL.md (호출될 때만 로드됨) |
| 길게 이어지는 전문 프로젝트 | butler 외부의 다른 폴더에 있는 CLAUDE.md |
전문 프로젝트를 butler의 안에 만들지 않는 것이 핵심입니다. 작업 폴더의 상위 디렉터리에 있는 CLAUDE.md도 읽히기 때문에, butler 안에 만들면 그 프로젝트에서도 집사 전용 규칙이 적용되어 버립니다.
함정: 전문 에이전트에게도 집사 규칙이 읽히는 경우
여기가 가장 큰 발견이었습니다.
직접 만든 서브 에이전트에는 초기 설정으로 CLAUDE.md가 읽힙니다. 이대로 두면, 조사를 부탁한 것뿐인 전문 에이전트까지 저널(journal)을 쓰려고 하거나 집사처럼 행동할 수 있습니다.
대책은 에이전트 정의에 omitClaudeMd: true를 추가하는 것입니다.
---
name: example-specialist
description: 언제 이 에이전트에게 맡길지 구체적으로 작성
...
사용인도 경험을 쌓는다
서두에서 언급했듯이, 집사에게는 회를 거듭할수록 기대를 충족시켜 주기를 바랍니다. 서브 에이전트도 마찬가지입니다.
전문 에이전트 정의에 memory: project를 추가하면, 해당 에이전트 전용의 기억 폴더(.claude/agent-memory/<이름>/)가 생성됩니다. 내부의 MEMORY.md는 호출될 때마다 맨 앞부분(200줄 또는 25KB까지)이 읽힙니다. butler 안에 있기 때문에 기록과 함께 Git으로 동기화됩니다.
다만, 기억의 장소가 있다고 해서 성장하는 것은 아닙니다. 그래서 정의 본문에 업무 전후에 할 일을 작성합니다.
---
name: example-specialist
description: 언제 이 에이전트에게 맡길지 구체적으로 작성
...
아직 작동한 지 얼마 안 된 에이전트가 많아, 성장했다고 실감하는 것은 앞으로일 것입니다.
(사양 출처: 서브 에이전트, 메모리 및 CLAUDE.md. 확인일 2026-10-19. memory는 2026-10-28)
사용해 보니 알게 된 점
- 세션 도중에
.claude/agents/에 추가한 에이전트는 해당 세션에서는 호출할 수 없었습니다. 다음 세션부터 사용할 수 있습니다. 급할 때는 범용 에이전트에게 정의 파일을 읽히게 하여 대신 활용하면 됩니다.
- 이전에 나눈 이야기를 바탕으로 대화해 줍니다. 예를 들어, 제가 예전에 "하고 싶다"고 말했던 것을 기억하여 그것을 전제로 이야기가 진행됩니다.
- 기록의 내용은 파일 열람보다 집사에게 직접 질문하는 경우가 많아질 것 같습니다. 기록은 Claude가 작성해주기 때문에 저는 파일을 거의 보지 않습니다.
요약
- 기록을 파일로 만들고, 읽기/쓰기 규칙을 CLAUDE.md에 작성합니다.
- Git으로 동기화하여 어디서든 동일한 기록을 사용합니다.
- Git에 올리지 않을 정보는
private/ 폴더로 분리합니다. - 무거운 작업은 전문 에이전트에게 맡기고, omitClaudeMd: true를 사용하여 규칙을 섞지 않습니다.
템플릿은 여기서 공개하고 있습니다.
시작 방법은 다음과 같습니다:
- 템플릿 페이지 오른쪽 상단의 'Use this template' → 'Create a new repository'를 선택합니다.
- 공개 범위를 비공개(Private)로 설정하여 자신의 리포지토리로 만듭니다. - 로컬에 clone한 후, 해당 폴더에서 Claude Code를 열고 대화를 시작합니다.
fork는 사용하지 마세요. 공개 리포지토리의 fork는 비공개로 만들 수 없기 때문에 기록이 외부에 노출될 위험이 있습니다.
월터나 알프레드 같은 집사가 있어주면 좋을 것 같네요.
Discussion
