기억하는 에이전트, 끊기지 않는 작업

CLAUDE.md — 영속하는 규칙과 기억 파일

매번 출근할 때마다 회사 이름도, 자기 자리도, 업무 규칙도 잊어버리는 신입사원이 있다고 해보자. 똑똑하긴 한데, 아침마다 처음부터 다시 알려줘야 한다.

에이전트가 딱 그렇다. 세션이 끝나면 방금까지 나눈 대화도, 합의한 규칙도 전부 사라진다.

7모듈에서 본 대로 컨텍스트 윈도우는 한정된 책상이다. 세션이 닫히면 그 책상은 통째로 비워진다. 어제 “우리 프로젝트는 들여쓰기 2칸이야”라고 합의했어도, 오늘 새 세션에서는 그런 약속이 없던 일이 된다.

그래서 필요한 게 책상 옆에 늘 펼쳐 두는 업무수첩이다. 에이전트의 업무수첩이 바로 CLAUDE.md 파일이다.

CLAUDE.md가 하는 일

CLAUDE.md는 프로젝트 폴더에 두는 평범한 텍스트 파일이다. 다만 특별한 점이 하나 있다. 에이전트가 그 폴더에서 일을 시작할 때마다 이 파일을 가장 먼저, 자동으로 읽는다.

덕분에 매번 다시 설명할 필요가 없다. “이 프로젝트는 파이썬을 쓰고, 테스트는 pytest로 돌리고, 커밋 메시지는 한국어로”라고 한 번 적어 두면, 새 세션마다 에이전트가 알아서 그 규칙을 떠올린다.

중요한 건 분량이다. CLAUDE.md는 매 세션 컨텍스트에 통째로 올라간다. 즉 책상 위 공간을 상시 차지한다. 길게 쓸수록 정작 일할 공간이 줄고, 핵심 규칙이 잡담에 묻힌다. 짧고 단단하게 — 이게 첫 번째 원칙이다.

기억의 세 칸 — 무엇을 적고 무엇을 버릴까

사람의 기억을 셋으로 나눠 보면 무엇을 수첩에 남길지 감이 온다. 서랍 세 칸이라고 생각하면 쉽다.

첫 칸은 의미 기억이다. 변하지 않는 사실 — 프로젝트가 무엇이고, 어떤 언어·도구를 쓰는지. 둘째 칸은 절차 기억이다. 일하는 방식 — 테스트는 어떻게 돌리고, 배포는 어떤 순서로 하는지. 셋째 칸은 일화 기억이다. 특정 순간의 사건 — “오늘 3시에 로그인 버그를 고쳤다” 같은 일회성 기록.

CLAUDE.md에 남길 건 앞의 두 칸, 즉 의미와 절차다. 오래 가는 사실과 방식만 적는다. 일화 기억은 대부분 그 세션이 끝나면 잊어도 되는 것들이라 수첩에 박제하면 오히려 짐이 된다.

CLAUDE.md

프로젝트 폴더에 두는 규칙·기억 파일. 세션 시작 때마다 자동으로 읽힌다.

의미 기억

변하지 않는 사실. 프로젝트 정의, 쓰는 언어·도구. 수첩에 남긴다.

절차 기억

일하는 방식. 테스트·빌드·배포 순서. 수첩에 남긴다.

일화 기억

특정 순간의 사건. 대부분 세션과 함께 흘려보낸다.

메모리 만들어주기 실습

수첩의 개념은 알았다. 그런데 처음부터 완벽한 규칙서를 손으로 쓰려면 막막하다. 다행히 가장 좋은 작성자는 따로 있다 — 에이전트 자신이다.

좋은 CLAUDE.md를 만드는 가장 빠른 길은 “네가 한 번 만들어 봐”라고 시키는 것이다.

에이전트는 폴더를 둘러보고 어떤 언어를 쓰는지, 어떤 구조인지, 어떤 명령으로 빌드하는지 스스로 파악할 수 있다. 그 관찰을 바탕으로 초안을 만들게 한 다음, 사람이 다듬는 편이 훨씬 빠르고 정확하다.

핵심은 ‘완벽한 첫 버전’이 아니라 ‘살아 있는 수첩’이다. 한 번 만들고 끝내는 게 아니라, 일하다 같은 실수가 반복되면 그때그때 한 줄씩 보태는 것이다.

세 단계로 만든다

1. 초안을 시킨다“이 프로젝트를 살펴보고, 다음 세션의 너 자신을 위한 CLAUDE.md 초안을 만들어줘”라고 부탁한다. 에이전트가 폴더를 읽고 사실·방식을 정리한다.
2. 사람이 가지친다초안에는 군더더기가 섞인다. 당연한 내용·일회성 내용은 지우고, 정말 반복되는 규칙만 남긴다. 짧을수록 좋다.
3. 쓰면서 키운다작업 중 “아, 이건 매번 알려주네” 싶은 순간 그 규칙을 한 줄 추가한다. 수첩은 한 번에 완성되지 않고 자란다.

아래는 잘 자란 CLAUDE.md가 대략 어떤 모습인지를 보여준다. 항목이 짧고, 사실(의미)과 방식(절차)으로 나뉘어 있다.

# 프로젝트 개요
사내 매출 대시보드. 파이썬 + Streamlit.
데이터는 data/ 폴더의 월별 csv를 읽는다.

# 일하는 방식 (절차)
- 테스트: pytest 로 전체 실행
- 실행: streamlit run app.py
- 커밋 메시지는 한국어로, 한 줄 요약

# 규칙 (꼭 지킬 것)
- data/ 의 원본 csv는 절대 수정·삭제하지 않는다
- 새 패키지는 requirements.txt 에 추가하고 알려준다

이 프로젝트 폴더를 살펴보고, 다음 세션의 너를 위한 CLAUDE.md 초안을 만들어줘.
- 프로젝트가 무엇인지(개요), 어떤 언어·도구를 쓰는지(의미)
- 빌드·테스트·실행을 어떤 명령으로 하는지(절차)
- 반드시 지켜야 할 규칙(예: 원본 데이터 수정 금지)
규칙은 짧게, 정말 반복되는 것만. 당연하거나 일회성인 내용은 넣지 마.
다 쓰면 왜 각 항목을 넣었는지 한 줄씩 설명해줘.

물리적 분리로 컨텍스트 관리

책상 하나에 세 가지 일을 동시에 펼쳐 두면, 서류가 섞이고 정신이 흩어진다. 에이전트도 똑같다. 한 세션에 여러 일을 욱여넣으면 컨텍스트가 오염된다.

해법은 의외로 단순하다. 일을 책상이 아니라 방으로 나누는 것이다.

7모듈에서 컨텍스트 5대 실패모드를 배웠다. 그중 오염·혼란은 대부분 한 곳에 너무 많은 걸 쌓아서 생긴다. 무관한 정보가 책상에 같이 올라와 있으면, 에이전트는 엉뚱한 자료를 참고하거나 지난 작업의 잔상에 휘둘린다.

이걸 막는 가장 확실한 방법이 물리적 분리다. 논리적으로 “이건 신경 쓰지 마”라고 부탁하는 것보다, 아예 다른 폴더·다른 세션으로 떼어 놓는 편이 훨씬 깨끗하다. 벽이 있으면 섞일 수가 없다.

두 가지 분리 — 샤딩과 격리

분리에는 두 결이 있다. 하나는 큰 자료를 잘게 나누는 샤딩, 다른 하나는 작업을 각자의 방에 가두는 격리다.

• 샤딩 — 큰 걸 잘게. 1000쪽짜리 문서를 통째로 올리면 책상이 꽉 찬다. 챕터별 파일로 쪼개 두고, 그때 필요한 조각만 읽게 한다. 위키나 지식베이스를 다룰 때의 기본기다.
• 격리 — 일을 각방에. 서로 무관한 작업은 폴더도 세션도 나눈다. ‘A 기능 개발’과 ‘B 문서 정리’를 한 세션에서 번갈아 하지 말고, 각각 따로 연다. 한쪽의 잔상이 다른 쪽을 흐리지 않는다.
• 서브에이전트도 격리다. 7모듈의 서브에이전트는 ‘별실에 보낸 직원’이다. 깊은 조사를 별도 컨텍스트에서 끝내고 요약만 가져오니, 본 세션의 책상은 깨끗하게 유지된다.

세션 관리 — 긴 작업 이어가기

하루에 끝나지 않는 일이 있다. 그런데 에이전트의 책상은 세션이 닫히면 비워진다. 어떻게 어제 하던 작업을 오늘 이어갈까.

답은 ‘기억하게’ 하는 게 아니라, ‘인수인계’하게 하는 것이다.

긴 작업의 진짜 적은 망각이 아니라 컨텍스트 부패다. 한 세션을 오래 끌수록 책상엔 시도와 실패와 잡담이 쌓이고, 에이전트는 점점 흐려진다. 그래서 노련한 사용자는 한 세션을 무한정 끌지 않는다.

대신 적당한 지점에서 인수인계 문서를 남기고 세션을 새로 연다. 퇴근하는 직원이 “여기까지 했고, 다음은 이걸 하면 됨”이라고 메모를 남기는 것과 같다. 새 직원(새 세션)은 그 메모만 읽고 깨끗한 책상에서 이어간다.

긴 작업을 이어가는 리듬

1. 큰일을 단계로 쪼갠다“전부 다 해줘” 대신, 작업을 끝이 보이는 단계들로 나눈다. 단계 하나가 한 세션에 들어갈 만한 크기면 좋다.
2. 마디마다 진행 메모를 남긴다한 단계가 끝나면 “지금까지 한 일 / 남은 일 / 다음에 할 일”을 PROGRESS.md 같은 파일에 적게 한다. 이게 인수인계장이다.
3. 흐려지면 세션을 갈아탄다응답이 둔해지거나 같은 실수를 반복하면 미련 없이 새 세션을 연다. 새 세션은 진행 메모부터 읽고 이어간다.
4. 되돌릴 지점을 남긴다단계마다 저장(커밋·백업)해 두면, 한 단계가 틀어져도 통째로 무너지지 않는다. 1모듈의 ‘되돌리기’가 여기서도 안전벨트가 된다.

이번 세션을 곧 마칠 거야. 다음 세션의 너를 위해 PROGRESS.md 를 남겨줘.
- 지금까지 끝낸 일 (한 줄씩)
- 아직 남은 일 (우선순위 순서로)
- 바로 다음에 할 일 한 가지와, 그걸 위해 알아야 할 맥락
- 주의할 점(건드리면 안 되는 것, 알려진 문제)
짧고 구체적으로. 새 세션이 이 파일만 읽고 바로 이어갈 수 있게.