memory-tidy

프로젝트 메모리는 쓰기만 하고 아무도 정리하지 않으면 끝난 작업, 일회성 참조, 다른 곳에 이미 있는 내용이 쌓인다. 어느 프로젝트에나 맞는 사실은 한 프로젝트 폴더에만 있어 다른 프로젝트 세션에서 안 보인다. 이 스킬은 항목마다 판정표를 만들어 승인을 받고, 정리와 승격을 한 번에 적용한다.

준비 — 전역 메모리가 없으면

~/.claude/global-memory/MEMORY.md가 없으면 절차에 들어가기 전에 만든다. 프로젝트 메모리와 같은 구조(인덱스 + 항목 파일)를 홈 아래에 하나 더 두고, 전역 CLAUDE.md가 인덱스만 불러오게 한다. 항목 본문은 필요할 때만 읽히므로 세션마다 늘어나는 로드는 인덱스 줄뿐이다.

1. ~/.claude/global-memory/MEMORY.md를 이 머리말로 만든다.

   # 전역 메모리
   
   어느 프로젝트에서나 똑같이 성립하는 메모리만 둔다. 항목 파일은 `~/.claude/global-memory/`에 있고 형식은 프로젝트 메모리와 같다.
   - 새 메모리는 지금처럼 프로젝트 메모리 폴더에 쓴다. 이 폴더에는 프로젝트 메모리에서 승격한 것만 넣는다.
   - 프로젝트 메모리와 내용이 다르면 프로젝트 쪽을 따른다.

2. 전역 ~/.claude/CLAUDE.md에 넣을 절을 보여 주고 승인을 받은 뒤 추가한다.

   ## 전역 메모리
   
   @~/.claude/global-memory/MEMORY.md
   
   * 메모리에는 모델이 바뀌어도 유효한 것을 쓴다 — 사용자의 선호와 결정, 작업 범위, 사실, 환경. 한 번 지적받은 어투·어휘·문장 습관은 그 답변에서 고치는 것으로 끝낸다. 반복되는지는 사용자가 판단해 이 파일이나 스킬에 규칙으로 넣는다. 사용자가 직접 기억하라고 한 것은 예외다.
   * 메모리를 쓸 때 그 내용이 다른 프로젝트에서도 그대로 성립하면 그 자리에서 전역 승격을 제안한다. 일괄 작업 중이면 묻지 않고 인덱스 줄 끝에 `전역 이관 후보`를 붙인다. 정리와 승격 절차는 `memory-tidy` 스킬을 따른다.

3. 확인: 다른 프로젝트에서 새 세션을 열고, 불러온 지침 파일 목록(Contents of <경로> 제목)에 global-memory/MEMORY.md가 별도 항목으로 있는지 본다. "이 파일이 컨텍스트에 있느냐"고 직접 물으면 있는데도 없다고 답한 경우가 있었으니, 목록을 그대로 나열하게 한다.

범위

• 프로젝트 범위(기본): 이 세션의 메모리 폴더(시스템 프롬프트의 auto memory 경로).
• 전체 범위: 사용자가 "전체"를 요청할 때. ~/.claude/projects/*/memory/ 전부와 ~/.claude/global-memory/. 설정 디렉터리를 둘 이상 쓰면서 projects를 링크로 공유한다면 링크 쪽은 스캔하지 않는다(같은 파일을 두 번 센다). 판정표는 프로젝트별로 나눠 낸다.
• 사용자가 항목을 지정해 범위를 좁히면 1단계는 지정한 파일과 2단계 grep으로 찾은 파일만 읽는다.

판정 — 항목마다 하나

• 애매하면 유지한다. 잘못 승격하면 다른 프로젝트까지 틀린 규칙을 따르고, 잘못 남기면 다른 프로젝트에서 안 보일 뿐이다.
• 일반 규칙과 프로젝트 예외는 나눈다. 일반 규칙만 승격하고, 프로젝트 쪽에는 전역과 다른 부분만 남긴다. 예: 범위 밖 작업을 작업 칩 대신 상태 파일에 적는 것은 전역 규칙이고, 그 파일의 어느 절에 적는지는 프로젝트의 예외다.
• 끝난 작업은 상태 파일에서 찾는다. 프로젝트가 진행 상태 파일(STATE.md 등)을 쓰면, 비우기 전에는 그대로 읽고 비운 뒤에는 git show HEAD~1:STATE.md처럼 직전 판에서 방금 끝난 목표와 체크리스트를 읽어 그 작업을 다루는 project 메모리를 찾는다. 끝난 작업의 메모리도 다음 작업에 쓸 교훈이 있으면 그 교훈만 남길 곳으로 옮긴 뒤 삭제한다.
• 출력 습관은 삭제한다. 한 번 지적받은 어투·어휘·문장 습관을 적은 항목이다. 모델과 버전마다 달라지는 것이라 다음 세션에 쓸모가 없다. 가르는 기준은 "다른 모델이 처음부터 그렇게 쓰지 않았어도 이 항목이 행동을 바꾸는가"다. 바꾸면 선호(PR 본문에 무엇을 넣고 뺄지 같은 내용·범위 결정)이고, 바꾸지 않으면 습관이다. 같은 습관 지적이 여러 항목에 있으면 판정표에 "CLAUDE.md·스킬 규칙 후보"로 적어 사용자가 정하게 한다.
• 인덱스에 전역 이관 후보 표시가 붙은 항목은 승격(전역) 후보로 시작해 위 기준으로 다시 판정한다.

절차

1. 읽기. 대상 폴더의 MEMORY.md와 항목 파일 전부, 전역 MEMORY.md, 프로젝트 상태 파일을 읽는다. 인덱스 줄과 description만 보고 판정하지 않는다. 본문을 읽어야 프로젝트 예외가 보인다. 완료 기준: 폴더의 항목 파일을 모두 열었고, 인덱스에 없는 파일과 파일이 없는 인덱스 줄을 따로 적었다.
2. 판정표. 위 표의 판정 하나와 근거 한 줄을 항목마다 단다. 승격(전역) 후보는 ~/.claude/projects/*/memory/를 grep해 같은 내용을 가진 다른 프로젝트 항목도 표에 넣는다. 완료 기준: 1단계에서 연 파일이 표에 정확히 한 번씩 있다.
3. 승인. 표를 대화에 보여 주고 유지 외 항목의 승인을 받는다. 메모리 폴더는 git 밖이라 지운 것은 되돌릴 수 없다. 사용자가 표에서 바꾼 판정은 그대로 따른다.
4. 적용. 승격 → 원본 처리 → 인덱스 순서로 한다.
   • 승격(전역): 프로젝트 메모리와 같은 frontmatter로 ~/.claude/global-memory/에 파일을 쓰고 전역 MEMORY.md에 한 줄 추가한다.
   • 승격(스킬): 승인받은 문장만 해당 SKILL.md에 넣는다.
   • 원본을 고치거나 지우고, 프로젝트 MEMORY.md에서 해당 줄을 고치거나 지운다. 전역 이관 후보 표시도 지운다. 지우기 전에 대상 폴더를 임시 위치에 복사해 두고, rm에는 셸 변수 없이 절대 경로를 적는다(변수로 만든 경로는 Claude Code 안전 검사에 막힌다).
   • 완료 기준: 승인한 항목이 모두 반영됐고, 손댄 각 폴더에서 MEMORY.md 줄과 항목 파일이 1:1로 맞는다.
5. 보고. 손댄 파일 수와 승격·삭제한 항목 이름을 짧게 적는다.

성공 기준 · 존재 의의

RATIONALE.md를 만들어 아래를 시드로 옮기고, 실행 회차 기록도 그 파일의 관측 표에 쌓는다. 만든 뒤에는 이 절을 참조만 하고 두 벌로 두지 않는다.

없애려는 것 — 메모리는 쓰는 계기만 있고 정리하는 계기가 없다. 원작성자 환경에서는 정리 절차(consolidate-memory)가 설치돼 있었지만 세션 로그상 실제 호출이 0회였고, 정리는 사용자가 직접 물었을 때 한 번뿐이었다. 크기로는 계기를 걸 수 없다 — 인덱스가 가장 큰 곳도 30줄로 로드 한도(200줄)에 한참 못 미쳤다. 대신 보인 문제는 범위였다. 이 PC 전반에 관한 참조 9건(24KB)이 한 프로젝트 메모리에만 있어 다른 프로젝트 세션에서 안 보였고, PR 문체 피드백이 한 레포 메모리에만 있어 다른 레포의 PR에는 적용되지 않았다.

재는 것

1. 전역 이관 후보 표시가 30일 넘게 남아 있지 않다. 남아 있으면 계기가 돌지 않은 것이다.
2. 작업 목표를 끝내고 상태 파일을 비운 세션에서 이 스킬이 실행됐다. 비운 기록만 있고 실행이 없으면 description이나 계기가 약한 것이다.
3. 승격한 내용이 다시 프로젝트 메모리에 쓰이지 않는다. 다시 쓰였다면 스킬 문제가 아니라 전역 인덱스가 읽히지 않는 것이다. 그때는 전역 메모리의 자리를 다시 정한다.

확정 결정

• 승격 대상은 전역 CLAUDE.md 본문이 아니라 ~/.claude/global-memory/다. 원작성자 환경에서 참조 9건을 CLAUDE.md에 넣으면 당시 CLAUDE.md 전체와 같은 24KB가 매 세션 로드될 상황이었다.
• 프로젝트와 전역이 다르면 프로젝트를 따른다. 프로젝트마다 진행 방식이 다른 항목이 실제로 있다.
• 출력 습관(한 번 지적받은 어투·어휘·문장 습관)은 메모리에 쓰지 않고 정리 때 지운다. 어투는 모델·버전·샘플링마다 달라져서 한 번의 지적을 기억해도 다음 모델에서는 쓸모가 없고 인덱스 로드만 늘린다.
• 삭제·승격은 판정표 승인 뒤에 한다. 메모리 폴더는 git 밖이다.

사용자가 "이 스킬 의도대로 작동해?" 라고 물으면 RATIONALE.md를 읽고 지난 회차 관측과 대조한다.