클로드 코드 프로젝트 간 기억 설정법 3단계

클로드 코드 프로젝트 간 기억은 하나의 전역 파일에 전부 넣지 말고, CLAUDE.md는 안정적인 사실, Claude Code Skills는 반복 절차, 외부 Agent Memory는 변화하는 선호와 작업 상태로 나누어 설정하는 방식이 가장 안전합니다. 개인 개발자는 첫 두 단계만으로 시작하고, 여러 저장소에서 작업을 이어가야 할 때만 세 번째 단계를 추가하면 됩니다.

이 글은 여러 저장소의 규칙을 반복해서 입력하는 개인 개발자, 공통 개발 절차를 정리하려는 팀 책임자, 재시작 뒤에도 작업 상태를 복구해야 하는 코딩 에이전트 운영자를 대상으로 합니다.

마지막 업데이트: 2026년 8월 10일
내용은 클로드 코드 공식 개요와 공식 메모리 설정 문서를 기준으로 확인했습니다.

시작 전에 기억을 세 종류로 분리합니다

여러 프로젝트에서 같은 설정을 공유하려고 할 때 가장 흔한 실수는 모든 정보를 하나의 전역 지시문에 넣는 것입니다. 이 방식은 처음에는 편하지만 저장소마다 다른 규칙이 충돌하고, 현재 작업과 무관한 정보가 계속 문맥에 들어오는 문제가 생깁니다.

먼저 다음 세 가지를 구분해야 합니다.

• 안정적인 프로젝트 사실: 폴더 구조, 주요 모듈, 빌드 명령, 테스트 명령, 코딩 규칙
• 반복 가능한 작업 절차: 배포 순서, 코드 검토 방식, 테스트 실행 순서, 변경 보고 형식
• 계속 변하는 상태: 개인의 답변 선호, 최근 결정, 중단한 작업, 다음에 해야 할 일

여기에 포함하면 안 되는 정보도 분명히 정해야 합니다.

• 접근 토큰과 비밀번호
• 고객 이름과 내부 식별자
• 다른 저장소의 비공개 코드 내용
• 특정 프로젝트에서만 유효한 임시 경로
• 근거 없이 추정한 업무 규칙

공식 메모리 문서는 프로젝트 파일과 사용자 파일을 구분해 읽는 방식을 설명하지만, 이것이 모델이 모든 과거 대화와 작업을 영구적으로 기억한다는 뜻은 아닙니다. 설정 파일을 다시 읽는 동작과 외부 저장소에서 과거 상태를 검색하는 동작은 서로 다릅니다. (공식 메모리 설정 문서)

첫 단계는 한 프로젝트의 CLAUDE.md를 정리하는 일입니다

처음부터 전역 설정을 만들지 말고, 가상의 저장소 orbit-api 하나에서 기준 파일을 만듭니다.

# orbit-api

## 구조
- src/api: 요청 처리
- src/domain: 핵심 규칙
- test: 자동화 테스트

## 자주 쓰는 명령
- 설치: pnpm install
- 테스트: pnpm test
- 검사: pnpm lint

## 작업 규칙
- 도메인 규칙은 라우터에 직접 넣지 않습니다.
- 변경 전 관련 테스트를 먼저 확인합니다.
- 새 환경 변수는 문서와 예제 파일에 함께 기록합니다.

이 파일에는 장기적으로 유지될 내용만 남겨야 합니다. 특정 이슈의 임시 해결 방법이나 이번 주에만 필요한 배포 순서는 넣지 않는 편이 좋습니다. 그런 내용은 별도 문서나 스킬로 분리해야 합니다.

공식 문서에 따르면 프로젝트 안의 CLAUDE.md는 팀이 공유하는 지침에 사용할 수 있고, 사용자 범위의 CLAUDE.md는 여러 프로젝트에 적용되는 개인 선호를 담을 수 있습니다. 또한 @ 가져오기로 다른 파일을 불러올 수 있으며, 가져오기는 최대 5단계까지 중첩될 수 있습니다. (CLAUDE.md 설정 범위 안내)

설정 뒤에는 새 세션에서 다음처럼 확인합니다.

이 저장소의 테스트 명령과 도메인 계층 규칙을 CLAUDE.md에서 읽었는지 먼저 설명하세요.
파일을 수정하지 말고 근거가 된 항목만 나열하세요.

/memory로 현재 불러온 메모리 파일을 확인할 수 있습니다. 파일을 만들었다는 사실보다 실제 세션에서 읽혔는지 검증하는 일이 더 중요합니다.

주의: 설정 파일이 다시 읽힌다는 것은 기억이 새로 주입된다는 뜻입니다. 모델이 과거 대화 전체를 영구 보존하거나 모든 프로젝트의 결정을 자동으로 알고 있다는 의미는 아닙니다.

두 번째 단계는 Claude Code Skills로 반복 절차를 분리하는 일입니다

배포나 코드 검토처럼 설명이 길고 실행 순서가 정해진 작업은 CLAUDE.md보다 스킬에 넣는 편이 적합합니다. 예를 들어 가상의 저장소에서 배포 절차를 다음처럼 구성할 수 있습니다.

.claude/
└── skills/
    └── release-check/
        └── SKILL.md

SKILL.md에는 다음 내용을 포함합니다.

---
name: release-check
description: 배포 전 테스트와 변경 사항을 확인하고 결과를 보고합니다.
---

1. 현재 브랜치와 변경 파일을 확인합니다.
2. 단위 테스트와 정적 검사를 실행합니다.
3. 환경 변수 이름만 확인하고 값은 출력하지 않습니다.
4. 실패한 항목과 재현 명령을 보고합니다.
5. 승인 전에는 배포 명령을 실행하지 않습니다.

설명에는 스킬이 언제 필요한지 명확히 적어야 합니다. “배포를 준비할 때 사용”처럼 작업 조건을 포함하면 자동 선택 가능성이 높아집니다. 반대로 “개발에 도움을 주는 기능”처럼 범위가 넓으면 엉뚱한 요청에도 불릴 수 있습니다.

프로젝트 스킬은 팀 저장소에 포함할 수 있고, 개인 스킬은 특정 사용자의 여러 프로젝트에서 활용할 수 있습니다. 플러그인으로 배포하는 스킬은 여러 저장소에 같은 절차를 공급할 때 유용하지만, 프로젝트 규칙보다 우선해야 하는지와 충돌 시 처리 방식을 별도로 정해야 합니다. 최신 설치 방식은 클로드 코드 시작 안내에서 확인해야 합니다.

실무에서는 다음 원칙이 안전합니다.

• 프로젝트마다 다른 명령은 프로젝트 스킬에 둡니다.
• 팀 전체가 공유할 검토 형식은 버전 관리합니다.
• 개인적인 답변 형식은 사용자 범위에 둡니다.
• 비밀 값은 스킬 파일에도 넣지 않습니다.
• 스킬이 파일을 수정하거나 배포할 경우 승인 조건을 명시합니다.

세 번째 단계에서 외부 Agent Memory를 제한적으로 연결합니다

외부 Agent Memory는 설정 파일의 대체재가 아닙니다. 안정적인 프로젝트 사실을 저장하는 장소가 아니라, 여러 세션에 걸쳐 변화하는 정보를 검색하기 위한 별도 계층입니다.

다음과 같은 상황에서만 도입하는 편이 좋습니다.

• 며칠에 걸쳐 진행되는 작업을 중단 후 재개해야 할 때
• 여러 저장소에 걸친 설계 결정을 추적해야 할 때
• 개인의 선호를 매번 다시 설명하기 어려울 때
• 팀 작업에서 결정 이유와 근거를 남겨야 할 때

기억 항목에는 최소한 다음 값을 함께 기록합니다.

project_id: orbit-api
user_id: developer-a
type: decision
summary: 인증 모듈은 요청 계층이 아니라 도메인 계층에서 검증합니다.
source: architecture-review-2026-08-10
created_at: 2026-08-10
expires_at: 2026-11-10

프로젝트 식별자가 없으면 orbit-api의 결정을 atlas-web에 잘못 불러올 수 있습니다. 사용자 식별자가 없으면 개인의 선호가 팀 전체 규칙처럼 적용될 수 있습니다. 근거와 만료일이 없으면 오래된 기억이 계속 검색되는 문제도 생깁니다.

외부 기억 저장소에는 원문 코드 대신 요약과 참조 위치를 남기는 방식이 안전합니다. 검색 결과를 사용하기 전에는 현재 저장소와 사용자 범위가 일치하는지 확인하고, 근거가 없는 항목은 지시가 아니라 참고 정보로 취급해야 합니다.

팀 환경에서는 권한도 함께 설계해야 합니다. 파일 읽기, 명령 실행, 파일 수정에 서로 다른 승인 흐름을 적용하고, 외부 기억을 연결한 뒤에는 자동 수정 권한까지 한 번에 열지 않는 편이 안전합니다. 먼저 읽기와 계획 모드로 검증한 뒤 필요한 권한만 추가해야 합니다.

자주 묻는 내용

클로드 코드는 예전에 작업한 프로젝트를 자동으로 기억하나요?

새 세션이 시작되었다고 해서 이전 프로젝트의 모든 대화가 자동으로 복원되지는 않습니다. 현재 작업 폴더에서 읽는 CLAUDE.md, 사용자가 직접 재개하는 세션, 외부 기억 저장소에서 검색하는 상태는 각각 다른 기능입니다. 세션 재개 명령과 사용법을 확인하면 재개와 영구 기억을 구분할 수 있습니다.

CLAUDE.md와 스킬 파일은 각각 어떤 내용을 넣어야 하나요?

CLAUDE.md에는 구조, 명령, 코딩 규칙처럼 자주 바뀌지 않는 사실을 넣습니다. 스킬 파일에는 배포, 검토, 테스트처럼 요청이 있을 때 실행하는 절차를 넣습니다. 긴 작업 설명을 모두 기본 파일에 넣으면 모든 세션의 문맥이 커지고, 현재 작업과 무관한 규칙이 행동에 영향을 줄 수 있습니다.

여러 프로젝트에서 같은 클로드 코드 설정을 공유하려면 어떻게 해야 하나요?

개인 선호와 공통 도구는 사용자 범위에 두고, 팀 규칙과 반복 절차는 각 저장소에 버전 관리되는 파일로 배포합니다. 반대로 저장소별 빌드 명령과 보안 정책은 프로젝트 안에 남겨야 합니다. 하나의 전역 파일에 모든 저장소의 규칙을 합치면 충돌 범위와 검토 대상이 지나치게 커집니다.

프로젝트 간 기억을 설정할 때 코드 정보가 새어 나가지 않게 하려면 어떻게 하나요?

외부 기억에는 코드 원문이나 비밀 값을 넣지 않고, 필요한 요약과 참조 위치만 기록해야 합니다. project_id와 user_id를 함께 저장하고, 생성 근거와 삭제 규칙을 둡니다. 회사 네트워크에서 중계 계층을 사용한다면 인증 정보가 스크립트에 하드코딩되지 않았는지도 확인해야 합니다.

마지막에는 재시작과 격리를 검증합니다

구성은 파일을 만드는 순간 끝나지 않습니다. 다음 순서로 고정된 회귀 검사를 실행해야 합니다.

1. 테스트 저장소를 두 개 만들고 서로 다른 프로젝트 이름을 지정합니다.
2. 각 저장소의 CLAUDE.md에 서로 다른 명령을 기록합니다.
3. 새 세션에서 각 규칙이 올바른 저장소에만 적용되는지 확인합니다.
4. 프로젝트 스킬을 추가한 뒤 별도 세션에서 호출되는지 확인합니다.
5. 외부 기억에 저장소별 결정을 하나씩 넣고 다른 저장소에서 검색되지 않는지 확인합니다.
6. 클로드 코드를 종료하고 다시 시작한 뒤 설정과 기억이 같은 범위로 복구되는지 확인합니다.
7. 버전을 올리기 전에 설정 파일과 기억 저장소를 백업하고 같은 작업을 다시 실행합니다.

점검 항목	통과 조건	실패할 때의 조치
프로젝트 규칙	현재 저장소의 명령만 읽음	전역 파일과 하위 파일의 중복을 제거합니다
스킬 선택	요청 조건에 맞는 스킬만 실행	설명과 호출 조건을 더 구체화합니다
기억 격리	다른 프로젝트 결과가 나오지 않음	프로젝트 식별자와 검색 조건을 수정합니다
사용자 분리	개인 선호가 팀 규칙으로 변하지 않음	사용자 범위와 프로젝트 범위를 나눕니다
재시작 복구	종료 후에도 필요한 상태만 복구	백업과 복구 절차를 다시 검증합니다

세 단계의 적용 범위는 다음처럼 정리하면 됩니다.

저장 위치	넣을 내용	여러 프로젝트 공유	피해야 할 내용
프로젝트 CLAUDE.md	구조, 명령, 저장소 규칙	팀 단위	임시 이슈와 비밀 값
사용자 또는 프로젝트 스킬	배포, 검토, 테스트 절차	선택적 공유	토큰과 고객 정보
외부 Agent Memory	선호, 결정, 중단 상태	식별자 조건부 공유	코드 원문과 무기한 기록

장기간 실행되는 환경이나 여러 사람이 함께 쓰는 환경에서는 개인 컴퓨터에만 설정을 두기보다 원격 개발 환경을 검토할 수 있습니다. 다만 장기 고정 작업에는 직접 구매한 맥이나 사내 서버가 더 적합할 수 있고, 물리 장치 접근이 필요하면 원격 환경이 맞지 않을 수 있습니다. 반대로 일시적인 테스트, 여러 저장소를 번갈아 확인하는 작업, 팀용 격리 환경이 필요하다면 맥 미니 원격 대여 환경을 기준으로 접근 방식과 복구 절차를 비교해 볼 수 있습니다.

기존 노트북에서 계속 운영하면 환경이 자주 바뀌고, 저장소별 권한과 기억 데이터가 한 사용자 계정에 섞이며, 재설치 뒤 설정 복구를 다시 해야 하는 단점이 있습니다. 원격 맥 환경도 자동으로 안전해지는 것은 아니지만, 프로젝트별 계정과 저장 공간을 나누고 설정 백업과 재시작 검사를 절차화하기는 더 쉽습니다. 지속 실행이나 공동 사용이 목적이라면 Zutcloud 도움말 센터에서 원격 개발 환경의 접근과 격리 조건을 먼저 확인하는 편이 합리적입니다.

더 읽기

• 여러 프로젝트에서 쓰는 에이전트의 파일과 기억을 나누는 법
• 외부 에이전트 기억 저장소의 비용과 운영 방식 살펴보기
• 개발 보조 도구의 월 사용료와 실제 비용 계산하기