메모리 관리(Memory Management)

Claude Code의 자동 메모리와 CLAUDE.md에 프로젝트가 성장함에 따라 라이브러리를 검색 가능한 상태로 유지하는 방법을 작성하는 방법입니다.

빠른 참조(Quick Reference)

사용자가 말하면...	이렇게 하세요
"기록해줘" (모호함, 여러 후보)/"복기해줘"/"개발 끝났는데 기록할 만한 거 봐줘"	→ 모드 1: 후보 평가(여러 후보 필터링)
"오늘 그 X 함정 기록해줘" (구체적인 단일 항목)/ 중요 버그 수정 완료 후/ 보안 사고 처리 완료 후/ 명확하지 않은 결론이 있는 단일 결정	→ 모드 2: 새 memory 생성(직접 진행)
"이 memory 업데이트해줘 / X 결론 수정해줘"	→ 모드 3: 기존 memory 업데이트(새로 생성보다 우선)
추가할 단락이 100줄을 넘거나 파일에 H2 주제가 이미 4개 이상인 경우	→ 규칙 6: 업데이트 대신 분할
"스키마 변경해줘 / 새 type 추가해줘 / 기억 구조 바꿔줘"	→ 모드 4: 구조적 변경(반드시 이미 겪은 함정 목록 참고)
"새 프로젝트 기억 없이 시작" / "어떻게 시작하지?"	→ 모드 5: 제로 메모리 부트스트랩
"기억 시스템이 지저분해 보여/감사해줘"	→ 프로젝트 루트에 `scripts/audit-memory.sh`가 있으면 실행; 없으면 `templates/audit-memory.template.sh`를 참고하여 직접 생성

중요 규칙(Important Rules)

규칙 1: 사실은 memory에, 방법은 skill에

memory 파일에는 "X 함정을 겪음", "업계 Y 데이터", "프로젝트 Z 상태"를 담습니다. 이 skill에는 "무엇을 기록할지 결정하는 방법/작성 방법/구성 방법"을 담습니다. 스키마 규칙을 memory에 작성하지 마세요(카테고리 오류).

규칙 2: 먼저 '기록할 가치가 있는지' 판단하고, 그다음 '어디에 기록할지' 판단하세요

모든 발견 사항을 기록할 필요는 없습니다. 의사 결정 트리:

신호	기록해야 하나요?
같은 함정을 두 번째로 겪음	✅ 반드시 기록
검토 중 명확하지 않은 판단 발견	✅ 결정의 '이유(Why)' 기록
업계 비교/실측 데이터(재사용 가능한 기준)	✅ 기록
일회성 디버그, 수정 완료, 가치 없음	❌ 기록하지 않음(커밋 메시지로 충분)
임시 상태, 변경될 예정	⚠️ 지속성 확인 후, 장기적인 경우만 기록
빈도는 낮지만 치명적(6개월간 읽지 않았지만 유일한 진실)	✅ 남겨둠 — 30일간 접근하지 않음 ≠ 오래됨; 삭제 기준은 '주제가 사라졌거나/대체됨'이지, '얼마나 오래 읽지 않았는지'가 아님

'어디에 기록할지' 판단 — 근접성 유발 4단계 라우팅:

먼저 직교 질문을 던지세요: '미래에 이 사실이 필요할 때, 특정 코드 위치를 보고 있는 중인가요, 아니면 파일 간 의사 결정을 하거나 특정 유형의 오류를 추적하는 중인가요?'

트리거 조건	대상	메커니즘
특정 라인/블록을 보고 있고, WHY가 한 문장으로 설명 가능함	인라인 코드 주석(해당 라인 바로 위에)	파일 수정 시 100% 발견, 인덱싱 비용 0
특정 파일 그룹에 대한 다중 계약/체크리스트	`.claude/rules/<x>.md` + `paths:` frontmatter	일치하는 경로 접근 시 자동으로 context 주입
트리거가 시나리오/오류/특정 문제이거나, 여러 파일에 걸쳐 있거나, 단일 저장소 파일에 속하지 않음(플랫폼/SDK 함정)	memory(본 시스템)	description 매칭
매 세션마다 지켜야 하는 규칙(명령어, 기술 스택, 협업 선호도)	CLAUDE.md	상주

특정 파일에 바인딩된 feedback은 기본적으로 SPLIT: 파일 로컬 핵심 -> 인라인 주석(작성 전에 해당 코드를 grep하면 이미 동등한 주석이 있는 경우가 많음); memory에는 '파일 간 재사용 가능한 원칙 + 해당 파일을 가리키는 포인터'만 남깁니다.

3가지 과도한 마이그레이션 방지 가드레일(기본값 memory, 가능한 적게 마이그레이션):

특정 파일을 제거해도 일반적인 교훈이 남는 경우 -> memory 유지(예: 'optional 필드를 중요한 결정 경로에 사용하지 마세요', 특정 파일은 예시일 뿐, 원칙은 이전 가능)
플랫폼/SDK 동작이 여러 파일에서 반복됨 -> memory 유지(코드에 의미가 있더라도)
묘비(X는 은퇴 -> Y를 보세요)/ 조사 SOP / 비즈니스 경제적 추론 -> memory 유지(트리거는 아키텍처/시나리오 수준)

실증(175개 파일 프로덕션 라이브러리 전체 감사): 약 15%의 항목만 단일 파일에 바인딩되어 있으며, 그중 대부분의 파일 로컬 핵심은 이미 코드 주석에 있음 — '마이그레이션'은 대부분 memory의 중복 복사본을 삭제하는 것이지 실제로 이동하는 것이 아님.

.claude/rules/*.md 작성 방법(프로젝트 .claude/rules/에 배치, git에 포함 -> 머신/worktree 간 공유):

---
description: 이 규칙이 무엇을 담당하는지 한 문장으로
paths:
  - src/components/SomeDialog.tsx
  - src/lib/providers/*.ts          # glob 지원
---
위 경로가 일치할 때 자동으로 주입되는 계약/체크리스트 본문(다중 gotcha).

⚠️ 네이티브 rules 주입의 알려진 경계(2026-07 확인, anthropics/claude-code issues): paths: 규칙은 Read 시에만 일치하는 파일에 주입되고, Write/새 파일 생성 시에는 주입되지 않음(#23478); 사용자 수준 ~/.claude/rules/의 paths:는 무시되며, 프로젝트 수준만 적용됨(#21858). '새 파일을 생성할 때도 반드시 적용되어야 하는 계약'은 CLAUDE.md에 남겨두고 rules에만 두지 마세요.

규칙 3: 기존 항목을 우선 업데이트하고, 새로 생성하지 마세요

주제와 관련된 기존 파일이 있으면 해당 파일을 업데이트합니다(단락 또는 변경 로그 섹션 추가). 주제가 완전히 직교하는 경우에만 새로 생성합니다. 새로 생성하면 주제가 파편화되어 -> 찾기 어려워지고 -> 기억 상실로 이어집니다.

규칙 4: memory는 자동으로 로드되지 않으며, description이 적중을 결정합니다

topic file(memory/*.md)은 세션 시작 시 로드되지 않습니다. Claude는 MEMORY.md 인덱스의 description을 기반으로 읽을지 판단합니다. description은 반드시 시나리오 키워드 + 핵심 결론을 혼합해야 합니다. 그렇지 않으면 Claude가 인상에 따라 어떤 파일을 읽을지 결정합니다.

네이티브 메커니즘 확인(2026-07, 공식 docs/en/memory): 벡터/의미론적 자동 검색은 없음 — 발견은 전적으로 'MEMORY.md 인덱스 라인 + 파일 이름'에 의존하며, Claude는 Read를 사용하여 필요에 따라 읽습니다. 읽을 때 harness는 "이 memory는 N일 전입니다"라는 시간 정보 프롬프트를 주입합니다. 인덱스 라인 hook의 품질 = 적중률의 전부이며, 이는 네이티브 동작이지 본 스킬의 규칙이 아닙니다.

규칙 5: skill 자신이 skill이 가르치는 규칙을 따라야 합니다

이 skill이 사용자에게 ## Why 섹션을 작성하도록 요구한다면, 이 skill도 자신의 각 규칙에 대한 이유(Why)를 설명해야 합니다(모두 이 파일에 인라인으로 포함되어 있습니다).

범위 주의: 규칙 5의 적용 범위는 "방법/작성법/빠른 참조 형식 등"이며, 스키마 규칙에는 재귀적으로 적용되지 않습니다. 스키마(이름/frontmatter/Why 섹션)는 memory 파일을 위한 것이며, skill 자체에는 적용되지 않습니다. Skill은 memory 파일이 아닙니다.

규칙 6: 언제 업데이트 대신 분할할지(단일 파일/단일 그룹 과부하 방지)

규칙 3은 업데이트를 우선시하지만, 임계값이 있습니다. 분할을 트리거하는 신호(단일 파일 수준):

신호	조치
기존 파일이 100줄 초과이고, 추가할 새 내용이 원래 주제와 직교함	새 파일로 분할, 추가하지 않음
기존 파일에 H2 최상위 섹션이 이미 ≥ 4개이고, 새 내용이 5번째 독립 주제에 속함	새 파일로 분할
섹션 추가 후 총 길이가 150줄을 초과함	분할 여부 평가(주제 독립성 확인)
추가할 내용이 원래 파일 제목/description과 일치하지 않음	새 파일로 분할(원래 파일은 선언된 주제에 집중해야 함)

단일 그룹 과부하(인덱스 수준):

신호	조치
MEMORY.md의 특정 큰 그룹 엔트리 수 ≥ 15	허브 memory(섹션 인덱스) 생성을 고려하여 플랫 리스트 대체, 새 엔트리는 허브에 연결
한 그룹의 description을 모두 훑어보는 데 25줄이 넘음	위와 동일
MEMORY.md > 23,000자(`wc -m`) 또는 > 190줄	🔴 네이티브 하드 제한 = 처음 200줄 또는 25K 자 중 먼저 도달하는 쪽(공식 문서 "25KB" 표현, 실제로는 string length=자 기준: 27,972자/37.9KB 인덱스가 정확히 25,000자에서 잘림, 바이트 기준으로는 약 35% 일찍 잘림). 초과분은 조용히 로드되지 않음. ⚠️ `wc -c`(바이트)로 추정하지 마세요: 한글 UTF-8은 글자당 3바이트로, 약 35% 여유를 과대평가하게 됩니다. 한계에 가까워지면 harness가 경고를 주입하며, `Only part of it was loaded` 메시지가 보이면 이미 인덱스가 손실되고 있는 중입니다.
단일 인덱스 라인 > ~160자	description에 세부 정보가 너무 많음 -> topic file로 이동하거나 코드 주석으로 내리고, 인덱스에는 "시나리오 키워드 + 핵심 결론"만 남깁니다.

단일 그룹 과부하도 관리해야 하는 이유: Claude는 MEMORY.md 인덱스를 훑어 description을 매칭하는데, 그룹 내 20개 이상의 description을 한 번에 훑으면 누락률이 발생합니다. 허브를 구축하면 그룹 인덱스는 허브를 가리키는 한 줄만 남고, 허브 내에서 주제 맵을 제공합니다.

인덱스 수준 전체가 가장 위험한 이유: 단일 파일/단일 그룹 과부하는 '적중률 감소'일 뿐이지만, 인덱스 전체가 잘리면 = 끝부분 전체가 로드되지 않음 = 적중률이 0이 되며, 조용히 오류 없이 진행됩니다. 따라서 ⭐⭐⭐ 핵심 항목은 MEMORY.md 상단에 배치해야 합니다(잘림 방지 보험).

한계 초과/과대 시 다이어트 우선순위(description 압축은 최악의 첫 번째 방법으로, 적중률을 스스로 해칩니다):

먼저 이동: 파일 로컬 항목 -> 인라인 주석 / .claude/rules(인덱스는 작아지고 적중률은 높아짐, 규칙 2의 4단계 라우팅 참조)
그다음 삭제: 진정한 묘비(주제가 사라졌거나/대체되었고 부활 방지 가치가 없는 것)
그다음 재배치: ⭐⭐⭐ 항목을 MEMORY.md 상단으로 이동
그다음 계층화: 인덱스 라인을 중요도별로 예산 배분 — 핵심 항목 ≤160자, 일반 항목 ≤110자, 롱테일 저빈도 항목은 하나의 라인에 여러 링크로 집계(하위 주제 → [a](f1.md) · [b](f2.md), 한 줄에 5-10개 파일 수용). 또한, 링크 레이블은 type 접두사를 제거한 짧은 이름 사용([foo-bar](feedback_foo_bar.md)), 전체 파일 이름을 반복하지 말고, 줄당 12-45자 절약
마지막으로 단일 description의 정보량 압축

역사적 함정 사례(참고용, 규칙의 일부가 아님)

단일 파일 과부하: 한 reference 파일이 130+ 줄까지 커져 7-8개의 독립 하위 주제(인프라, cron 목록, 장애 수첩 등)를 포함하게 되었고, MEMORY.md 인덱스 설명이 부정확하여 Claude가 특정 하위 주제를 적중하지 못함. 5개의 독립 memory로 분할 후 각 주제 정확히 적중.
단일 그룹 과부하: 특정 그룹에 20개 이상의 엔트리가 누적되어 새 세션에서 Claude가 인덱스를 훑을 때 누락이 발생, 작업 처리 시 바퀴를 재발명. 허브 memory를 구축하여 관련 진입점 집계 -> 해결.
인덱스 수준 전체 과부하: MEMORY.md가 43KB 바이트(≈31K 자, 25K 자 제한 초과)까지 커지고, 93개의 description이 각각 400-900자로, 시작 시 조용히 잘려서 끝부분의 ⭐⭐⭐ 항목이 누락 -> 한 조사에서 설계대로 작동하는 메커니즘을 취약점으로 오판. 교훈: description이 너무 상세하면 인덱스를 터뜨려 오히려 적중률을 해친다.
바이트/자 혼동으로 인한 잘못된 교정: 과부하 관리 시 경고선을 바이트(wc -c) 기준 32KB로 설정했지만, harness는 자 기준으로 실행(한글은 글자당 3바이트) -> 바이트 기준선은 여유가 있다고 착각하게 만들어 인덱스가 다시 잘림. 교훈: harness와 같은 단위를 사용해야 하며, 모니터링은 wc -m을 사용하세요.

워크플로우 모드(Workflow Modes)

모드 1: 후보 평가(여러 후보, 필터링 필요)

트리거 시나리오(여러 후보 -> 모드 1 필터링 필요):

기능 개발 완료 / 긴 디버그 완료 / 검토 완료
남용 방지 처리 완료(여러 판단 포인트 + 교훈 가능)
보안 사고 처리 완료 / 장애 위치 파악 완료
사용자가 "기록해줘"라고 말함(모호함, 특정 함정 미지정)

단일 구체적인 내용은 직접 모드 2로 이동: 사용자가 "오늘 그 wildcard 버그 기록해줘" / "연결 누수 장애 수첩 기록해줘"라고 말함 -> 이미 단일 항목 명확 -> 모드 2, 모드 1 불필요.

단계:

이번 세션의 주요 노드 검토(사용자 수정, 검토 발견, 예상치 못한 버그, 업계 비교 조회, 단일 결정의 명확하지 않은 결론)
하나씩 규칙 2 의사 결정 트리 적용, 기록할 가치가 있는 것 필터링
각 후보에 대해 판단:
- 이미 해당 내용을 다루는 memory 파일이 있는가?(MEMORY.md 인덱스 grep) -> 있으면 모드 3 업데이트, 없으면 모드 2 새로 생성
- 추가할 내용이 규칙 6 분할 트리거 선을 초과하는가? -> 새 파일로 분할
- memory가 아닌 CLAUDE.md에 들어가야 하는가?(아래 표 참조)
사용자와 목록 확인: "추가 제안 / 업데이트 제안 / 분할 제안" 후보를 나열하고 사용자 확인 후 작성

memory vs CLAUDE.md 경계:

내용 성격	위치
구체적인 함정 경험(SDK 버그, 플랫폼 제한, 업계 데이터)	memory `feedback_*`
주제 심층 참고 / 표준 방법 / 프로세스 문서	memory `reference_*`
상태적 사실(진행 중인 작업, 임시 설정, 현재 아키텍처 스냅샷)	memory `project_*`
매 세션마다 지켜야 하는 규칙(명령어, 기술 스택, 협업 선호도)	CLAUDE.md
특정 파일 작업 시에만 필요한 규칙	`.claude/rules/*.md` + paths frontmatter

모드 2: 새 memory 생성(표준 절차)

단계 0: 먼저 근접성 유발 4단계 라우팅 확인(규칙 2)

작성 전에 정말 memory에 들어가야 하는지 확인: 단일 파일에 집중 -> 인라인 주석; 파일 그룹의 계약 -> .claude/rules+paths; 시나리오/파일 간/플랫폼 함정 -> 그래야만 memory로 이동. 파일에 바인딩된 feedback은 기본적으로 SPLIT(핵심은 주석, memory는 파일 간 원칙 + 포인터만). 자세한 내용은 규칙 2 참조.

단계 1: type 결정

Type	사용 시기	필수 포함 정보
feedback	배운 함정(SDK 버그 / 플랫폼 제한 / 사용자 선호도)	이유(이 결론이 나온 이유) + 재사용 시기(트리거 시나리오)
reference	주제 심층 참고 / 표준 방법 / 업계 비교 / 재사용 가능한 파이프라인	이유 섹션 불필요(설명적)
project	상태적 사실(아키텍처 스냅샷, 진행 중인 작업, 경제학 분석)	이유 섹션 불필요(상태적)

feedback 필수 포함 정보의 표현 형식(다음 중 하나):

별도 섹션: ## Why 또는 동의어 한글 ## 근본 원인 / ## 원인 / ## 교훈 / ## 이유(감사에서 모두 허용)
굵은 글씨 인라인: **Why**: / **근본 원인**: (짧은 결론도 가능)
description 또는 ## 제목에 인라인(결론 자체가 이미 이유와 재사용 시기를 함축한 경우, 예: ❌/✅ 비교 표)

재사용 시기 정보: 별도의 ## How to apply 섹션이거나, description에 시나리오 키워드 포함(예: tab 전환 / mutation이 이미 트리거 시나리오를 암시).

단계 2: 파일 이름 지정

<type>_<topic>[_<modifier>].md 모두 소문자, 밑줄 사용:

✅ feedback_supabase_from_deadlock.md
✅ reference_supabase_egress_favorites_refactor.md
❌ feedback-supabase-deadlock.md(하이픈 사용)
❌ FeedbackSupabaseDeadlock.md(카멜 케이스)
❌ _schema.md(밑줄로 시작하면 숨김 파일로 간주되며, Claude가 능동적으로 읽지 않음)

단계 3: frontmatter 작성

---
name: kebab-case-slug
description: 시나리오 키워드 + 핵심 결론
type: feedback | reference | project       # 평평하게(권장)
# 또는:
# metadata:
#   type: feedback | reference | project   # 중첩(호환 가능)
---

type 필드 위치: type: 평평하게(권장) 또는 metadata.type: 중첩 모두 허용. 감사 스크립트는 둘 다 인식. 새 파일 생성 시 평평한 방식을 우선 사용하며, 기존 대부분과 일관성을 유지합니다.

description 스타일 판단:

✅ 좋은 description	❌ 나쁜 description
`브라우저에서 supabase.from() mutation이 탭 전환 후 교착 상태 발생, 반드시 fetch()로 REST API 호출`	`Supabase 관련 문제`
`CF Image Transformations 실패 7일 캐시 / cf-resized err= / FavoriteCard retry 패턴`	`이미지가 가끔 표시되지 않음`
`RLS 정책은 반드시 (SELECT auth.uid())로 래핑해야 함, 그렇지 않으면 각 행마다 반복 평가`	`RLS 성능 최적화`

판단 기준: Claude가 description을 읽을 때 "이것은 X 시나리오에서 확인해야 할 Y 결론이다"를 즉시 알 수 있는가?

단계 4: 본문 작성

feedback 클래스(필수: 이유 + 재사용 시기 포함) :

# 제목(무엇(What) — 한 문장)

[핵심 결론 + 1-2단락 배경]

## Why(또는 동의어: ## 근본 원인 / ## 원인 / ## 교훈 / ## 이유)

[왜 이 결론이 나왔는가 — 겪은 구체적인 함정, 검토 발견, 사용자 선호도]
**이유가 반드시 필요한 이유**: 이유 섹션이 없으면, 다음에 같은 결정을 재논의할 때 종종 같은 잘못된 결론에 도달하게 됩니다.

## How to apply(description에 이미 시나리오 키워드가 포함된 경우 생략 가능)

[이 결론을 재사용할 시기 — 트리거 시나리오, 체크리스트, 함정 회피 단계]

reference / project 클래스: 섹션 구조 강제 없음, 주제에 따라 자연스럽게 구성.

단계 5: MEMORY.md 인덱스에 추가

기존 큰 그룹 선택, 새 그룹 생성 금지
description을 그룹 내 해당 위치에 추가(높은 중요도는 ⭐⭐ / ⭐⭐⭐ 굵게 표시)
주제 간: description 끝에 (다른 파일 보기 [[other-file]]) 추가

모드 3: 기존 memory 업데이트(새로 생성보다 우선)

단계 1: grep으로 기존 주제 소속 확인

grep -l "<키워드>" memory/*.md

단계 2: 업데이트 방식 결정

상황	업데이트 방법
새 데이터 / 새 사례로 기존 결론 보강	본문에 단락 또는 변경 로그 섹션 추가
기존 결론이 반박됨	기존 파일 상단에 `⚠️ Superseded by [[new-file-slug]]` 추가, 새 파일 본문에 "[[old]]의 어떤 부분을 대체" 작성
description 설명이 불충분한 경우	MEMORY.md 인덱스만 수정, 파일 자체는 수정하지 않음(내용 추가 시 함께 수정)

단계 3: MEMORY.md 동기화

description을 변경했다면 MEMORY.md의 해당 라인도 변경해야 합니다.

모드 4: 구조적 변경(스키마 변경 / 새 type 추가 / 그룹 변경)

반드시 읽어야 할 이미 겪은 함정 목록:

if: "Write(memory/*.md)" glob 문법을 hook에 사용하지 마세요 — if:는 permission rule이지 file glob이 아니며, 유효하지 않음이 확인됨
exit 2를 사용하여 hook을 차단하지 마세요 — pre-deploy batch 흐름을 망가뜨리는 것으로 확인됨(Claude에 자동 재시도 메커니즘 없음)
스키마 권위 소스를 _schema.md와 같은 밑줄로 시작하는 파일에 두지 마세요 — Claude가 topic file을 능동적으로 읽지 않음
프로젝트 .claude/settings.json에 hook을 구성하지 마세요 — 해당 디렉토리는 일반적으로 .gitignore에 있어 git에 포함되지 않고 worktree 간 공유되지 않음
새 필수 필드 추가 시 3곳 동기화: (a) 본 skill 섹션 "모드 2 → 단계 3" (b) MEMORY.md 상단 빠른 참조 핵심 섹션 (c) audit-memory.sh 스크립트 필드 목록
hook 수정 / 제약 조건 추가 전에 먼저 bash scripts/audit-memory.sh를 실행하여 현재 규정 준수율 확인 — <95%인 경우에만 하드 조치 필요, ≥95%는 소프트 경고 유지
MEMORY.md 크기 모니터링은 반드시 자(wc -m) 기준이어야 하며 바이트(wc -c) 기준이 아님 — 네이티브 상한 200줄/25K 자는 자 기준; 한글은 글자당 3바이트이므로 바이트로 교정하면 조용히 잘림 발생(규칙 6 역사적 사례 참조)

스키마 변경 절차:

audit 실행하여 현재 기준선 확보
변경 설계(본 skill + 프로젝트 허브 수정)
기존 memory가 새 규칙을 대량으로 위반하는지 확인(>10% → 일시 중지, 먼저 새 규칙으로 마이그레이션)
MEMORY.md 핵심 섹션 업데이트 동기화
audit 스크립트 필드 목록 수정
audit 재실행하여 새 규정 준수율 확인

모드 5: 제로 메모리 부트스트랩(새 프로젝트)

사용자가 memory 시스템이 없는 프로젝트에서 "기억 구축 시작"이라고 말할 때:

단계 1: auto memory 디렉토리 경로 확인

Claude Code가 자동으로 ~/.claude/projects/<project-slug>/memory/를 생성합니다. 여기서 <project-slug> = 프로젝트 절대 경로에서 /를 -로 대체한 값입니다. 예:

프로젝트 /Users/alice/Project/myapp → slug -Users-alice-Project-myapp

Claude Code가 해당 프로젝트에 대해 이미 auto memory를 생성했다면 디렉토리가 존재합니다. 확인: ls ~/.claude/projects/ | grep <프로젝트명>.

단계 2: MEMORY.md 인덱스 생성

상단 템플릿(~25줄로 압축 가능):

# <프로젝트명> 프로젝트 기억

## ⭐⭐⭐ memory 작성 빠른 참조(하드 규칙)
- 파일 이름:`<type>_<topic>.md` 모두 소문자, 밑줄; type ∈ {feedback, reference, project}
- 필수 frontmatter: name / description / type
- feedback은 반드시 ## Why 섹션 포함(또는 동의어 한글 ## 근본 원인 / ## 교훈 / ## 원인)
- description 스타일: 시나리오 키워드 + 핵심 결론(한 줄 ≤160자)
- 동일 주제 기존 파일 있으면 → 업데이트, 새로 생성 금지(규칙 6 임계값 초과 시 분할)
- 본 인덱스 하드 상한: 처음 200줄 또는 25K 자(먼저 도달하는 쪽), 초과분은 조용히 로드되지 않음
- 자세한 방법: memory-management skill

## ⭐ 프로젝트 주제 목록
(없음 — 이후 주제별로 그룹 추가)

단계 3: 그룹 진화 임계값(파일 수에 따라 구조 결정)

memory 파일 수	권장 구조
< 15개	플랫 리스트, 그룹화 없음(단일 목록으로 충분, 그룹화는 오히려 파편화)
15-25개	3-5개의 큰 그룹 도입(주제별 집계)
> 25개	그룹화 성숙, 그룹 동결하여 새 그룹 생성 금지, 새 항목은 기존 그룹에 연결(주제 간은 `(다른 파일 보기 X)`)

단계 4: CLAUDE.md 상단에 Memory 프로토콜 추가(3-5줄)

## Memory 관리
memory 쓰기 / 업데이트 / 스키마 조정 관련 → `memory-management` skill을 사용하세요.
- 빠른 참조 규칙: MEMORY.md 상단 ⭐⭐⭐ 섹션
- 점검 규정 준수율: `bash scripts/audit-memory.sh`(선택 사항, skill templates/ 참조)

단계 5: 본 skill의 일반 방법 재사용

skill 내용을 프로젝트에 복사하지 마세요. Skill은 사용자 수준에 있으며, 모든 프로젝트가 한 세트의 방법을 공유합니다. 프로젝트에는 프로젝트별 상태(그룹 목록 / 할 일 / 프로젝트 특정 함정)만 넣으세요.

스키마 규격(Schema Specification, 권위 소스)

파일 이름

<type>_<topic>[_<modifier>].md 모두 소문자, 밑줄, type ∈ {feedback, reference, project}

필수 frontmatter

---
name: kebab-case-slug
description: 시나리오 키워드 + 핵심 결론
type: feedback | reference | project       # 평평하게(권장)
# 또는:
# metadata:
#   type: feedback | reference | project   # 중첩(호환)
---

audit 스크립트는 둘 다 인식합니다. 새 파일 생성 시 평평한 방식을 우선 사용합니다.

feedback 필수 포함 정보

이유 섹션(다음 중 하나):

## Why 또는 동의어 한글 제목 ## 근본 원인 / ## 교훈 / ## 원인 / ## 이유 / ## Root cause(영문 : 또는 한글 : 가능)
굵은 글씨 인라인 **Why**: / **근본 원인**: 등

재사용 시기(다음 중 하나):

별도 ## How to apply 섹션
description에 시나리오 키워드 포함(트리거 시나리오를 암시하면 충분)

description 스타일

혼합(시나리오 키워드 + 핵심 결론), Claude가 description으로 "X 시나리오에서 Y 결론 확인"을 적중할 수 있도록 합니다. 한 줄 ≤ ~160자 — 세부 사항은 topic file 또는 코드 주석으로 이동(인덱스 하드 상한 = 200줄/25,000 자 중 먼저 도달하는 쪽, 초과분은 조용히 로드되지 않음)

인덱스 라인 형식

- [짧은 레이블](전체파일명.md) — hook. 짧은 레이블 = type 접두사를 제거한 하이픈 이름(예: [supabase-from-deadlock](feedback_supabase_from_deadlock.md)); 롱테일 저빈도 항목은 집계 라인 사용(하위 주제 → [a](f1.md) · [b](f2.md))

그룹 동결

기존 큰 그룹에서 선택, 새 그룹 생성 금지. 소속이 모호한 경우 (다른 파일 보기 hub-X)로 교차 참조.

일반적인 실수(Common Mistakes)

틀림	맞음
인상으로 description 작성 "Supabase 문제"	시나리오 키워드 + 결론 작성 "supabase.from() 탭 전환 교착 상태, fetch 사용"
feedback에 "무엇인지"만 씀	feedback은 반드시 ## Why 포함, 미래에 재검증 방지
동일 주제로 두 번째 파일 생성	기존 파일 우선 업데이트, 새로 생성 시 파편화 발생
"네트워크 문제" 그룹을 새로 만들어 1개 entry 배치	기존 그룹 사용, 주제 간은 `(다른 파일 보기 X)` 사용
스키마 규칙을 memory 파일에 작성	스키마는 본 skill에, memory는 사실을 담음
hook exit 2로 강제 차단	소프트 경고(stderr + exit 0) 또는 audit 사후 점검 사용

자체 점검(Self-Check, 작성 후)

도구 통합(Tool Integration)

audit 스크립트는 선택 사항인 프로젝트 도구입니다.

프로젝트 루트에 scripts/audit-memory.sh 있음 → 실행:

bash scripts/audit-memory.sh  # 규정 준수율 확인 / 위반 항목 나열 / 30일간 미접근 항목 나열

출력: 총 파일 수 / frontmatter 누락 / Why 누락 / MEMORY.md 끊긴 링크 / 30일간 미접근 / MEMORY.md 크기(자+줄, 네이티브 200줄/25K 자 상한 대비) / 규정 준수율%. 목표 규정 준수율 ≥ 95%.

audit 스크립트 없음 → 템플릿에서 직접 생성:

# 사용자 수준 skill에 포함된 일반 템플릿
cp ~/.claude/skills/memory-management/templates/audit-memory.template.sh \
   <프로젝트>/scripts/audit-memory.sh
# MEMORY_DIR을 프로젝트의 auto memory 디렉토리로 변경
chmod +x <프로젝트>/scripts/audit-memory.sh
bash <프로젝트>/scripts/audit-memory.sh

기본 auto memory 경로 참조: ~/.claude/projects/<project-slug>/memory/, 모드 5 단계 1 참조.

즐겨 사용하는 AI에게 물어보기

문서