클로드 코드 하위 에이전트 기억 — 범위 셋·켜면 쓰기 도구가 따라옴

하위 에이전트는 매번 빈손으로 시작합니다. 같은 저장소를 열 번 훑어도 열 번 다 처음이죠. 그런데 대화가 끝나도 살아남는 폴더를 하나 쥐여 주면 이야기가 달라집니다 — 코드 규칙이나 자주 걸리는 함정 같은 걸 스스로 적어 두고 다음에 꺼내 봅니다.

다만 켜는 순간 도구 구성까지 같이 바뀝니다. 읽기만 하게 좁혀 둔 에이전트였다면 쓰기와 편집이 슬그머니 들어옵니다.

📌 30초 요약

• 대화를 넘어 남습니다.
• 둘 자리가 셋입니다.
• 쓰기 도구가 따라옵니다.
• 요약 앞부분만 실립니다.
• 알아서 쌓이진 않습니다.

1. 대화를 넘어 남는 폴더

정의 파일에 기억 항목을 한 줄 적으면 그 하위 에이전트만의 폴더가 생깁니다. 대화가 끝나도 폴더는 그대로 남고, 다음에 같은 에이전트를 부르면 그 내용을 들고 시작합니다. 지금 대화를 통째로 물려받는 방식과는 방향이 다릅니다 — 저쪽이 가로로 넓히는 거라면 이쪽은 세로로 쌓는 쪽이죠.

쌓이는 내용은 문서가 예로 드는 것만 봐도 감이 옵니다 — 이 저장소의 코드 규칙, 디버깅하다 알아낸 것, 왜 이렇게 설계했는지 같은 것들입니다. 같은 검토자를 한 달쯤 굴리면 그 프로젝트를 아는 검토자가 되는 셈입니다.

2. 어디에 쌓을지 셋 중에

범위를 고르면 폴더가 놓이는 자리가 갈립니다. 얼마나 넓게 적용될 지식이냐를 기준으로 고르시면 됩니다.

범위	이럴 때 고릅니다
내 계정 쪽	모든 프로젝트에 통하는 지식
저장소 안	팀과 같이 쌓고 싶을 때
저장소 안·비공개	이 프로젝트용이되 안 올릴 것
문서 권장값	둘째 줄 — 버전 관리로 공유

둘째와 셋째의 차이가 실무에서 중요합니다. 둘 다 저장소 안에 놓이는데 하나는 커밋 대상이고 하나는 아닙니다. 팀원 모두가 같은 지식을 나눠 갖게 하려면 둘째, 내 작업 습관이나 실험 메모처럼 남에게 안 보일 것은 셋째를 쓰시면 됩니다. 프로젝트 지시문이 저장소를 따라다니는 구조와 같은 감각입니다.

한 가지 더 알아 두면 좋은 건 폴더가 에이전트 이름별로 갈린다는 점입니다. 같은 범위를 골라도 검토자와 조사자는 서로 다른 칸에 쌓으니 지식이 섞이지 않습니다. 뒤집어 말하면 정의 파일의 이름을 바꾸는 순간 그동안 쌓은 폴더와 연결이 끊깁니다 — 옛 폴더는 그대로 남고 새 이름으로 빈 칸이 하나 더 생기는 셈이죠. 이름을 손볼 일이 있으면 폴더도 같이 옮겨 주셔야 합니다.

3. 켜면 따라오는 것들

기억을 켜는 건 폴더 하나 주는 걸로 끝나지 않습니다. 그 에이전트의 시작 조건이 세 군데 바뀝니다.

무엇이	어떻게 됩니다
지시문	읽고 쓰는 방법이 덧붙음
요약 파일 앞부분	200줄까지만 같이 실림
도구	읽기·쓰기·편집이 자동으로
자동 기억을 끄면	이 항목이 통째로 무효

둘째 줄은 분량 관리 이야기입니다. 폴더 안의 요약 파일 앞부분만 지시문에 실리는데 — 200줄 또는 25킬로바이트 중 먼저 닿는 쪽까지입니다 — 넘어가면 「정리해서 줄이라」는 지시가 함께 들어갑니다. 그러니 이 파일은 차곡차곡 쌓는 일지가 아니라 골라 담는 요약본으로 두셔야 제 몫을 합니다.

⚠️ 읽기 전용으로 좁혀 둔 에이전트가 쓰기를 갖게 됩니다

기억을 켜면 그 에이전트가 자기 파일을 관리해야 하니 읽기·쓰기·편집 도구가 자동으로 붙습니다. 문제는 쓸 도구를 읽기·검색만으로 좁혀 둔 에이전트에 기억을 더할 때입니다 — 「이 녀석은 파일을 못 고친다」고 믿고 맡겼는데 고칠 수 있는 상태가 됩니다. 검토자나 조사자처럼 손대지 않는 게 전제인 에이전트라면, 기억을 줄지 말지를 도구 목록과 함께 판단하세요. 정말 손대지 못하게 하려면 기억을 빼거나, 파일 수정 자체를 권한 설정에서 막아 두셔야 합니다.

넷째 줄도 한 번쯤 걸리는 대목입니다. 이 기능은 클로드의 자동 기억에 딸린 식구라, 자동 기억을 통째로 꺼 두셨다면 정의 파일에 기억 항목을 적어도 아무 일도 안 일어납니다. 지시문도 안 붙고 도구도 안 켜집니다. 「분명 적었는데 기억을 안 한다」면 여기부터 보세요.

쓰기가 붙는 게 걸리는데 기억은 주고 싶다면 길이 하나 더 있습니다. 도구를 쓰기 직전에 끼어드는 검사를 걸어 두는 방식입니다. 도구 이름으로 걸어 두면 실행 전에 지정한 스크립트가 돌고, 그 스크립트가 2번 코드로 끝나면 그 호출이 막히면서 에이전트에게 사유가 그대로 전달됩니다. 「기억 폴더 안은 되고 바깥은 안 됨」처럼 도구를 통째로 빼지 않고 범위만 자를 수 있는 셈이죠.

★여기에 운영체제별 함정이 하나씩 있습니다. 맥과 리눅스에서는 그 스크립트에 실행 권한을 안 주면 막히는 게 아니라 검사 자체가 실패합니다. 그리고 윈도우에서는 파워셸로 쓰고 훅 항목에 그 셸을 쓰겠다고 따로 적어 줘야 합니다 — 이걸 빼먹으면 검사가 안 걸린 채로 지나갑니다.

4. 알아서 쌓이지는 않습니다

폴더를 줬다고 저절로 차오르지는 않습니다. 읽으라고, 쓰라고 말해 줘야 합니다. 문서가 권하는 방식은 단순합니다 — 일을 맡길 때 「전에 본 패턴이 있는지 기억을 확인해 봐」를 붙이고, 끝난 뒤에 「알아낸 걸 기억에 저장해」를 한 번 더 시키는 겁니다.

매번 말하기 번거로우면 정의 파일 본문에 아예 적어 두면 됩니다. 「코드 경로와 패턴, 라이브러리 위치, 중요한 설계 결정을 발견하면 기억을 갱신하라」 정도로요. 그러면 시키지 않아도 스스로 자기 지식을 관리합니다. 이때 「무엇을 찾았고 어디에 있었는지 짧게 적어라」까지 넣어 두면 요약 파일이 덜 비대해집니다.

덧붙여 이 기억은 개발 키트 쪽에서 서버에 쌓이는 기록과 전혀 다른 물건입니다. 이쪽은 내 기계의 폴더라 열어 보고 고치고 지우는 게 자유롭고, 저장소에 넣으면 코드 리뷰를 거쳐 쌓입니다. 무엇이 기억됐는지 눈으로 확인할 수 있다는 점이 가장 큰 차이입니다.

자주 묻는 질문 (FAQ)

Q. 어느 범위를 기본으로 쓰면 되나요

문서는 저장소 안에 두고 버전 관리로 공유하는 쪽을 권합니다. 팀이 같은 지식을 나눠 갖고, 무엇이 쌓였는지 변경 이력으로 확인할 수 있기 때문입니다.

Q. 적어 뒀는데 기억을 안 합니다

먼저 자동 기억이 켜져 있는지 보세요. 꺼 두면 이 항목이 통째로 무효입니다. 켜져 있다면 「기억을 확인해」·「기억에 저장해」를 시켰는지 확인해 보세요.

Q. 요약 파일이 길어지면 어떻게 되나요

앞부분만 실리고 「정리하라」는 지시가 함께 들어갑니다. 200줄이나 25킬로바이트 중 먼저 닿는 쪽이 경계입니다. 일지가 아니라 요약본으로 관리하세요.

Q. 읽기 전용 검토자에게 줘도 되나요

주는 순간 읽기 전용이 아니게 됩니다. 쓰기와 편집이 자동으로 붙기 때문입니다. 손대지 않는 게 전제라면 기억을 빼거나, 권한 설정에서 파일 수정을 따로 막아 두세요.

정리하면

• 대화를 넘어 쌓입니다.
• 커밋 여부로 둘이 갈립니다.
• 쓰기 도구가 따라옵니다.
• 자동 기억이 전제입니다.
• 시켜야 쌓입니다.

※ 공개된 하위 에이전트 문서의 「영속 기억」 절을 읽고 정리했습니다. 설정 항목과 폴더 경로는 우리말로 풀어 적었으니 실제 표기는 원문에서 확인하세요.

※ 실리는 분량 한도와 자동으로 붙는 도구 구성은 2026년 9월 기준이며 판올림에 따라 바뀔 수 있습니다.