Claude Code 사용법: CLAUDE.md로 팀 규칙과 메모리 관리하기

이렇게 하면 같은 맥락을 거듭 설명하는 일을 줄일 수 있습니다. 가령 개발자 네 명이 각자 다섯 번의 세션을 진행하면서 세션마다 준비에 3분씩 쓴다고 가정하면, 맥락을 다시 설명하는 데만 주당 60분이 듭니다. 공유 지침 파일을 두면 이런 사전 설명을 한곳에서 관리할 수 있습니다. 다만 절약되는 시간이 보장되지는 않습니다. 반복 설명이 얼마나 줄었는지, 파일을 관리하는 데는 얼마나 시간을 쓰는지 함께 비교해야 합니다.

CLAUDE.md는 어떤 파일인가요?

CLAUDE.md는 프로젝트, 개인 작업 방식 또는 조직에 관한 지침을 담은 Markdown 파일로, Claude Code가 읽어 작업에 참고합니다. 팀이 늘 공유하는 기본 업무 지침이라고 생각하면 됩니다. 자동 메모리는 Claude가 그 옆에 두고 쓰는 작업 노트입니다. 기본 지침은 사람이 관리하고, 노트는 Claude가 작성합니다. 둘 다 Claude가 판단할 때 참고하는 컨텍스트가 됩니다. Anthropic 메모리 가이드

둘을 구분하는 기준은 세션이 바뀌어도 계속 유효해야 하는 내용인지입니다. 반드시 실행해야 할 테스트 명령어는 기본 지침에 넣습니다. 어떤 설명이 지나치게 상세했다는 피드백은 학습한 선호 사항으로 남길 수 있습니다. 지금 수행 중인 작업은 대화에서 다룹니다.

이 구분은 공식 디렉터리 가이드를 따릅니다. 처음부터 .claude 폴더를 복잡하게 구성할 필요는 없습니다. 기본 지침부터 만들고, 역할이 분명해질 때 파일을 추가하면 됩니다.

CLAUDE.md 저장 위치: 프로젝트, 사용자, 조직별 구분

소규모 팀이라면 저장소 루트에 프로젝트 지침 파일 하나를 두고 커밋합니다. 개인 선호 사항은 사용자 지침 파일에 넣어 다른 팀원에게 의도치 않게 적용되지 않도록 합니다.

위 항목은 문서에 명시된 적용 범위와 파일 위치입니다. 조직이 관리하는 지침 파일은 개인 설정으로 로드 대상에서 제외할 수 없지만, 파일에 적힌 문장은 여전히 지침으로 작용합니다.

Claude는 시작할 때 작업 디렉터리와 그 상위 디렉터리의 지침 파일을 불러옵니다. 하위 디렉터리의 지침은 해당 디렉터리의 파일을 다룰 때 불러옵니다. 이 파일들은 합쳐서 사용하므로, 더 구체적인 지침 파일을 추가한다고 해서 다른 곳의 상충하는 지침이 사라지지는 않습니다. 사용자 지침과 프로젝트 지침이 서로 일치하도록 관리해야 합니다. 지침 파일 로드 방식

Claude Code 사용법: 소규모 제품팀을 위한 CLAUDE.md 예시

같은 실수를 반복하지 않도록 팀의 결정 사항을 적습니다. 아래 예시는 pnpm을 사용하는 TypeScript 제품을 전제로 하며, lint, typecheck, test 스크립트가 이미 정의되어 있다고 가정합니다. 커밋하기 전에 명령어와 경로를 실제 저장소에서 확인한 내용으로 바꿔야 합니다.

각 항목에는 왜 필요한지 한 줄 설명을 붙였습니다. 제안하는 팀 규칙이며, Anthropic의 기본 설정은 아닙니다.

# Product Team Instructions

## Product Intent
Why: Keep implementation tied to the customer problem.
- Read the task's acceptance criteria before changing code.
- Ask when missing product behavior would change the solution.

## Working Commands
Why: Make verification repeatable across teammates and sessions.
- Use pnpm for this repository; keep pnpm-lock.yaml consistent.
- Run pnpm lint and pnpm typecheck for application changes.
- Run pnpm test for behavior changes; report any checks not run.

## Change Boundaries
Why: Keep reviews small and dependencies deliberate.
- Follow nearby patterns before adding a new abstraction.
- Ask before adding a runtime dependency or changing public APIs.
- Keep unrelated cleanup out of the change.

## Data and Migrations
Why: Make data changes reviewable and reversible where possible.
- Add schema changes through the existing migration workflow.
- Describe compatibility and rollback concerns in the handoff.
- Use synthetic data in examples and tests.

## Quality
Why: Catch user-visible regressions before review.
- Add a focused regression test when fixing a behavior bug.
- Check loading, empty and error states when changing UI flows.
- State remaining uncertainty instead of calling unchecked work done.

## Project References
Why: Point to maintained decisions without copying the whole wiki.
- Read docs/product-decisions.md when product behavior is unclear.
- Read docs/release-checklist.md before preparing a release.

예시의 문서 참조는 필요할 때 해당 문서를 읽으라는 일반적인 지침입니다. 그 문서를 만들거나 경로를 바꿔야 합니다. 의도적으로 자동 가져오기 방식은 사용하지 않았습니다.

파일을 저장하고 저장소에서 세션을 시작한 다음, /context를 실행해 시작 시 로드된 메모리 목록을 확인합니다. /memory로 지침 파일을 열어 수정할 수 있습니다. 이어서 Claude에게 작지만 실제로 필요한 작업을 맡기고, 명령어와 작업 범위에 관한 지침이 도움이 되는지 확인합니다. 메모리 확인 방법

특정 파일에만 필요한 규칙은 별도로 분리합니다

대부분의 작업에 필요하지 않은 규칙은 .claude/rules/로 옮깁니다. 예를 들어 프런트엔드를 수정할 때 API 핸들러에 관한 모든 규칙까지 컨텍스트에 넣을 필요는 없습니다.

paths 헤더를 포함한 .claude/rules/api.md 파일을 만듭니다. glob은 파일 이름을 매칭하는 패턴입니다. src/api/**/*.ts는 해당 디렉터리와 하위 디렉터리 안의 TypeScript 파일을 선택합니다.

---
paths:
  - "src/api/**/*.ts"
---

# API Rules
- Validate external input before passing it to application logic.
- Use the existing error response format.
- Add a focused test when changing an endpoint's behavior.

이 패턴은 지침을 언제 컨텍스트에 넣을지 결정합니다. paths가 없으면 시작할 때 조건 없이 로드됩니다. 로드 범위를 지정하지 않은 채 긴 기본 지침을 여러 규칙 파일로 나누기만 해서는 컨텍스트를 절약할 수 없습니다. 경로별 규칙

가져오기는 내용을 공유하는 방법이며, 컨텍스트 비용을 줄이지는 않습니다

CLAUDE.md 안에 @docs/team-conventions.md처럼 가져오기 구문을 넣으면 시작 시 해당 파일이 컨텍스트에 포함됩니다. 상대 경로는 가져오기 구문이 적힌 파일을 기준으로 해석합니다. 실제로 가져오려면 Markdown 백틱이나 코드 블록 바깥에 구문을 적어야 합니다. 그 안에 적으면 단순한 텍스트로 남습니다. 프로젝트에서 작업 디렉터리 밖의 파일을 가져오려 하면 승인을 요청합니다. 가져오기 구문

다른 팀이 이미 관리하는 짧은 규칙이 모든 세션에 필요하다면 가져오기를 사용합니다. 긴 릴리스 체크리스트라면 위 예시처럼 일반적인 문서 참조를 쓰는 편이 낫습니다. 가져오기는 기본 지침의 구성을 바꿀 뿐, Claude가 시작할 때 읽는 분량을 줄여 주지는 않습니다.

AGENTS.md를 쓰고 있다면 팀 지침의 원본을 하나로 유지합니다

Claude Code는 2.1.277 버전부터 해당 지원 기능을 사용할 수 있는 경우 CLAUDE.md 대신 AGENTS.md를 직접 읽을 수 있습니다. 다만 기본 동작에는 중요한 조건이 있습니다. 작업 디렉터리와 그 상위 디렉터리에 CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md가 모두 없어야 합니다. 사용자 지침 파일과 조직 지침 파일은 이 대체 로드 동작을 막지 않습니다. AGENTS.md 로드 방식

그래서 CLAUDE.local.md 때문에 혼동하기 쉽습니다. 프로젝트의 개인 메모를 추가했을 뿐인데, 자신에게 로드되는 공유 지침 파일이 달라질 수 있습니다.

두 파일이 모두 필요하다면 /config를 열고 Project instructions를 claude-md-and-agents-md로 설정합니다. 또는 같은 디렉터리의 CLAUDE.md에 @AGENTS.md를 넣습니다. 이 가져오기 방식은 AGENTS.md 직접 로드를 지원하지 않을 때도 작동합니다. 팀 규칙을 두 벌로 복제해 관리하지 않도록 합니다. 선택 기준은 AGENTS.md 설정 가이드에서 더 자세히 다룹니다.

Claude Code 메모리: 학습한 내용은 자동 메모리에 남깁니다

자동 메모리를 사용하면 Claude가 유용한 선호 사항, 피드백, 프로젝트 맥락을 저장해 다음 대화에서도 활용할 수 있습니다. 무엇을 남길지는 Claude가 판단하므로, 어떤 세션에서는 아무것도 저장하지 않을 수 있습니다. 로컬 세션에서는 기본으로 활성화되어 있습니다. 자동 메모리

기본 저장 위치는 ~/.claude/projects/<project>/memory/입니다. 같은 저장소의 워크트리와 하위 디렉터리는 내 컴퓨터에서 이 메모리 디렉터리를 공유합니다. 워크트리는 같은 저장소를 별도로 체크아웃한 작업 공간입니다. 따라서 그곳에서 브랜치 작업을 시작한다고 해서 독립적인 메모리 노트가 생기지는 않습니다. 이 파일들은 다른 팀원, 다른 컴퓨터, 클라우드 환경과 자동으로 공유되지 않습니다. 저장 위치

MEMORY.md는 색인 역할을 합니다. 세션을 시작할 때 Claude는 이 파일의 처음 200줄 또는 25KB 중 먼저 도달하는 한도까지 불러옵니다. 주제별 상세 파일은 필요할 때 읽습니다. 이 기준은 시작 시 색인을 얼마나 불러오는지에 관한 것이며, 저장할 수 있는 전체 메모리 용량의 한도가 아닙니다. 자동 메모리 로드 방식

메모리를 관리할 때는 /memory부터 엽니다. 메모리 위치를 나열하고, 편집기에서 파일을 열고, 자동 메모리 폴더로 이동하며, 자동 메모리를 켜거나 끌 수 있습니다. 시작할 때 어떤 CLAUDE.md와 규칙 파일이 로드됐는지 확인하려면 /context를 사용합니다. 메모리 관리 기능

어디에 저장할지 명확하게 요청해야 합니다. “작업 완료 보고는 짧게 받는 것을 선호한다고 기억해 줘”는 학습한 메모를 남기라는 요청입니다. “팀에서 반드시 실행해야 하는 테스트 명령어를 CLAUDE.md에 추가해 줘”는 관리 대상인 지침을 수정하라는 요청입니다. 팀 전체에 필요한 규칙이 개발자 한 명의 홈 디렉터리에 있는 메모에만 의존해서는 안 됩니다.

일반 서브에이전트도 이 노트를 전달받는다고 가정하지 않아야 합니다. 주 대화의 자동 메모리는 일반 서브에이전트에 로드되지 않습니다. 부모 대화를 상속하는 포크는 예외이며, 서브에이전트에 자체 메모리를 별도로 설정할 수도 있습니다. 에이전트끼리 작업을 나눈다면 Claude Code 서브에이전트 가이드를 참고합니다. 서브에이전트의 메모리 동작

Claude Code 설정에서 자동 메모리를 끄는 방법

원하는 적용 범위에 맞는 방법을 선택합니다.

• 사용자 설정: /memory를 열고 자동 메모리를 끕니다. 이 토글은 ~/.claude/settings.json에 autoMemoryEnabled 설정을 저장합니다.
• 특정 프로젝트: 해당 프로젝트의 설정에 "autoMemoryEnabled": false를 지정합니다. 팀이 공유할 프로젝트 설정은 .claude/settings.json에, 내 컴퓨터에서만 적용할 설정은 .claude/settings.local.json에 넣습니다.
• 환경 변수로 제어하는 실행: CLAUDE_CODE_DISABLE_AUTO_MEMORY=1을 설정합니다.

위 방법은 문서에 명시된 비활성화 방법과 설정 파일 위치를 따릅니다. 자동 메모리를 꺼도 별개로 작동하는 CLAUDE.md 지침 기능은 계속 사용할 수 있습니다. 기존 메모까지 없애려면 해당 Markdown 파일을 직접 확인하고 삭제해야 합니다.

한 달에 한 번 자동 메모리를 정리합니다

Claude가 앞으로의 작업에 가져갈 내용을 짧게 검토하는 시간으로 삼습니다. 월별 검토는 팀에 제안하는 습관이며, 제품에서 요구하는 절차는 아닙니다.

1. /memory를 열고 자동 메모리 폴더를 살펴봅니다. MEMORY.md를 읽은 다음, 참조를 따라 실제 메모를 확인합니다.
2. 더 이상 유효하지 않은 맥락을 삭제합니다. 이미 지난 마감일, 폐기한 계획, 더는 적용되지 않는 예외를 지웁니다. 판단하기 어려운 메모는 현재 프로젝트 상황과 대조합니다.
3. 반복되는 피드백을 합칩니다. 조금씩 다른 여러 문장 대신 정확한 문장 하나만 남깁니다.
4. 오래 유지할 팀의 결정 사항은 공유 지침으로 옮깁니다. 모두에게 필요한 규칙을 커밋된 CLAUDE.md나 적용 범위를 지정한 규칙 파일로 옮기고, 중복되는 개인 메모는 삭제합니다.
5. 색인을 줄입니다. MEMORY.md에는 짧은 참조만 남기고 자세한 내용은 주제별 파일에 둡니다. 줄 수와 바이트 크기를 모두 확인해 시작 시 로드 한도와 비교합니다.
6. 새 세션에서 확인합니다. /context로 지침 목록을 확인하고, 다음 실제 작업에서 오래된 조언이 나오는지 살펴봅니다.

자동 메모리 파일은 수정 가능한 Markdown이며, 대화 기록 보관 기간이 지나도 자동으로 정리되지 않습니다. 쓸모없어진 메모는 누군가 직접 지워야 합니다. 메모리 편집과 보관

이런 다섯 가지 상황에서 효과를 볼 수 있습니다

반복되는 피드백 때문에 이미 리뷰가 지연되는 곳부터 시작합니다. 아래는 소규모 제품팀에서 유용할 가능성이 높은 순서로 정리한 작업 방식입니다.

이를 바탕으로 만들어 볼 만한 작은 서비스 두 가지

가장 가능성이 큰 아이디어는 저장소 지침 점검 서비스입니다. 소규모 팀은 명령어를 검증하고, 상충하는 지침을 찾아내고, 짧은 기본 지침과 범위별 규칙을 제안하는 검토에 비용을 지불할 수 있습니다. 최소한의 유용한 결과물은 검토를 마친 풀 리퀘스트와 반복해서 사용할 수 있는 점검 체크리스트입니다. DataForSEO가 추정한 “claude project instructions”의 미국 월간 검색량은 260회입니다. 이 검색어에는 Claude Code 외의 관심도 포함되어 있습니다. 관련 주제를 찾는 사람이 있다는 신호이지, 구매자 수를 뜻하지는 않습니다. 일반적인 템플릿은 쉽게 복사할 수 있으므로, 유료 서비스의 가치는 각 저장소에 맞춘 판단에 있어야 합니다.

활성 저장소가 많은 팀에는 로컬 메모리 정리 보고서도 도움이 될 수 있습니다. 첫 버전에서는 지나치게 큰 색인, 참조 대상이 없는 주제별 파일 링크, 오래되어 보이는 메모를 표시한 뒤 개발자가 수정 내용을 검토하게 할 수 있습니다. DataForSEO가 추정한 “claude code memory”의 미국 월간 검색량은 1,300회입니다. 이는 문제에 대한 관심을 보여 줄 뿐, 이 툴 자체의 수요를 입증하지는 않습니다. 큰 한계도 있습니다. 파일이 오래됐다는 사실만으로 그 안의 결정이 더는 유효하지 않다고 판단할 수는 없습니다. 내용의 의미를 판단하는 일은 프로젝트를 아는 사람에게 맡겨야 합니다.

두 추정치는 모두 2026년 10월 11일 사이트의 DataForSEO 리서치 연동을 통해 조회한 미국 영어 키워드 개요 결과입니다. 위 아이디어는 제안하는 제품이며 Claude Code에 내장된 기능이 아닙니다. 작은 저장소 하나를 운영한다면 둘 중 어느 것을 구매하거나 만들기 전에, 지침 파일과 월별 검토부터 시작합니다.

메모리는 판단에 참고하는 맥락이며, 강제 수단은 아닙니다

CLAUDE.md에 “절대로 하지 말 것”이라고 써도 해당 동작 자체가 불가능해지지는 않습니다. 자동 메모리와 조직 전체에 배포하는 문장형 지침도 마찬가지입니다. Claude는 모호한 지침을 잘못 해석하거나 서로 모순되는 지침을 만날 수 있습니다. Anthropic의 주의 사항

Claude의 판단과 관계없이 특정 동작을 차단해야 한다면 PreToolUse 훅을 사용합니다. 툴이 동작하기 전에 실행되는 제어 장치입니다. 보호할 파일에 관한 주의 문구는 팀의 의도를 설명할 수 있지만, 실제 차단을 하려면 제어 기능을 구현해야 합니다. 훅을 설정하는 방법은 Claude Code 훅 설정 가이드에서 다룹니다.

컨텍스트 크기를 관리할 때는 사람이 실제로 유지할 수 있는 분량의 기본 지침을 목표로 합니다. Anthropic은 개별 CLAUDE.md 파일을 200줄 미만으로 유지하라고 권장하지만, 이는 MEMORY.md의 시작 시 로드 한도와는 별개입니다. 정해진 분량을 채워야 한다고 생각해 예시를 불필요하게 늘리거나, 모든 내용을 가져오기로 옮긴 뒤 비용이 줄었다고 가정하지 않아야 합니다. 효과적인 지침 작성법

소규모 팀이 자주 묻는 질문

월요일에 바로 해볼 일은 이렇습니다. 최근 몇 차례 세션에서 전달한 피드백을 모으고, 반복되는 팀의 결정 사항을 하나의 CLAUDE.md로 정리해 리뷰한 뒤 작은 작업에 적용해 봅니다. 월별 메모리 검토 일정도 팀 캘린더에 추가합니다.

이런 규칙을 안정적인 개발 워크플로로 정착시키는 데 도움이 필요하다면 AI 프로덕션 시스템 서비스를 살펴보십시오.