project-registry은(는) 무엇을 하나요?
EN — A Claude Code skill that manages a personal project registry (
~/projects/PROJECTS.json) with per-project AI-readable development logs (CLAUDE.md): list, create, delete, save, session-resume, decision attribution, health check and version rollback from one menu. The UI text is Chinese-first, but triggers work in both Chinese and English and every feature is fully functional regardless of language (the AI understands both). Install:npx skills add SUNQSHENG/project-registryor/plugin marketplace add SUNQSHENG/project-registry.
개요
~/projects/PROJECTS.json에 등록된 프로젝트 목록을 관리하며, 프로젝트의 추가, 삭제, 수정, 조회 및 통계 기능을 제공합니다. 프로젝트는 <key>/ 하위 디렉토리 형태로 ~/projects/ 아래에 저장되며, 각 프로젝트는 배경과 범위를 기록한 README.md를 포함합니다.
프로젝트 작업 시 자동으로 cd 해당 프로젝트 디렉토리로 이동합니다.
데이터 소스
~/projects/
PROJECTS.json # 프로젝트 등록 목록 (유일한 권위 소스)
<key>/ # 프로젝트 디렉토리
README.md # 프로젝트 배경 및 범위 설명 (사람 대상)
CLAUDE.md # 프로젝트 개발 기록 (AI 대상, 대화 시 자동 로드)
모든 프로젝트 반드시 ~/projects/ 디렉토리 아래에 저장되어야 합니다.
차이점: README.md는 개발자/협업자에게 프로젝트 개요를 제공하고, CLAUDE.md는 AI에게 개발 과정의 결정, 상태, 맥락을 기록하여 장기 프로젝트에서 정보 손실을 방지합니다.
PROJECTS.json 구조
{
"description": "프로젝트 목록 — 모든 프로젝트는 여기에 등록",
"updated": "2026-03-01",
"nextSeq": 3,
"projects": [
{
"seq": 1,
"key": "pet_hospital_crm_20260301",
"name": "애완동물 병원 CRM",
"status": "완료",
"created": "2026-03-01"
}
]
}
진입점
스킬에 진입할 때마다 먼저 cd ~로 사용자 홈 디렉토리로 이동한 후, PROJECTS.json을 읽어 목록과 간결한 메뉴를 표시합니다 (디렉토리 수준 검사는 하지 않음):
📋 현재 프로젝트 목록 (총 N개)
┌─────┬──────────────────────────────┬─────────────────┬──────────────────────┬──────────┬────────────┐
│ 순번 │ key │ 이름 │ 상태 │ 생성일 │
├─────┼──────────────────────────────┼─────────────────┼──────────────────────┼──────────┼────────────┤
│ 1 │ pet_hospital_crm_20260301 │ 애완동물 병원 CRM│ ✅ 완료 │ 2026-03-01 │
│ 2 │ gym_members_app_20260315 │ 피트니스 회원 App│ 🔄 진행 중 │ 2026-03-15 │
└─────┴──────────────────────────────┴─────────────────┴──────────────────────┴──────────┴────────────┘
> 초기 표시 시 디렉토리 검사는 하지 않고, JSON만 읽습니다. 디렉토리 상태는 MD 검사 시 일괄 검사합니다.
작업을 선택하거나 직접 요청해 주세요:
- 프로젝트 **순번** (1-99) 입력 → 해당 프로젝트 열기 (예: 12)
- 🆕 N. 새 프로젝트 생성
- 🗑️ D. 프로젝트 삭제
- 🔍 C. MD 검사 (모든 프로젝트 일괄 검사)
> 다른 요청 (수정/검색/통계/기록 업데이트/저장/종료/**프로젝트 검사**/**왜 XX** 등)은 대화에서 바로 말씀해 주세요
> ⚠️ **저장/종료 시 CLAUDE.md가 자동으로 업데이트됩니다** (강제 규칙)
⚙️ 최초 설정 안내 (API Key 선택 사항)
스킬에 처음 진입할 때:
- 환경 변수
PR_API_BASE_URL/PR_API_KEY/PR_API_MODEL이 설정되어 있는지 확인합니다 (printenv) - 설정되지 않음 → AskUserQuestion 카드로 질문: "API Key를 설정하여 자동 요약 저장을 활성화하시겠습니까?"
- 설정 (권장) → 세 가지 환경 변수 설정 안내 (README에 각 제공업체 예시: DeepSeek / OpenAI / Tongyi / Ollama 로컬)
- 건너뛰기 →
<스킬 디렉토리>/config.json에 기록 ("건너뜀" 저장, 이후 재질문 안 함) - 자세히 알아보기 → 기능 비교표 표시
- 설정 후 즉시 적용됨 (세션 재시작 불필요)
기능 비교:
| 기능 | Key 없음 | Key 있음 |
|---|---|---|
| 데이터 안전 (초 단위 백업 + 세션 종료 시 자동 커밋) | ✅ | ✅ |
| 모든 핵심 기능 (레지스트리/세션 복구/귀속/롤백/검사) | ✅ | ✅ |
| 자동 요약 (대화 자동 추출 → CLAUDE.md 실시간 업데이트) | ❌ | ✅ |
언제든지 "API 설정"이라고 말하면 재안내합니다.
🔍 현재 프로젝트 자동 인식
스킬 진입 시 이미 자동으로
cd ~가 실행됩니다. 프로젝트 위치 파악이 필요한 작업 (검사/수정/저장/기록 업데이트 등)은 현재 디렉토리를 자동으로 인식합니다:
1. pwd로 현재 디렉토리가 ~/projects/<key>/ 와 일치하는지 확인
2. 일치 → 해당 프로젝트 자동 선택
3. 불일치 → 수동 선택 (순번 또는 key로)
🧭 세션 시작流程 (컨텍스트 복원)
"프로젝트 작업 시작" 유형의 작업에만 트리거됩니다: 프로젝트 열기 / 검사 / 수정 / 기록 업데이트 / 저장 / 종료. 세부 정보 보기, 검색, 통계 등의 가벼운 작업은 트리거되지 않습니다.
프로젝트 진입 후, 작업 실행 전에 먼저 컨텍스트를 검토한 후 이어서 진행합니다 (장기 프로젝트 정보 손실 방지, 중단 후 재진입 시 맥락 파악):
- 해당 프로젝트의 CLAUDE.md 읽기 (존재하는 경우)
- 마지막 진행 상황 요약: "현재 상태 / 최신 진행" 인용, 필요 시 git log 최근 커밋 참조
- "다음 작업" 나열 (우선순위별 1. 2. 3. …)
- 사용자에게 어떤 작업부터 계속할지 질문 (AskUserQuestion 카드로 다음 작업 옵션 제시), 확인 후 작업
예시 멘트 (카드 하단 주석):
📌 마지막 진행 상황 요약: 프로젝트 초기화 완료, 레지스트리 생성됨
➡️ 다음 작업 (우선순위별):
1. 요구사항 문서 완성
2. 할 일 목록 보충
어느 항목부터 계속할까요?
새 프로젝트 (CLAUDE.md 방금 생성)는 검토를 건너뛰고 바로 작업을 시작할 수 있습니다.
📂 프로젝트 열기
- 순번 또는 key로 프로젝트 찾기 →
~/projects/<key>/디렉토리 존재 확인 cd프로젝트 디렉토리로 이동- "🧭 세션 시작流程" 트리거 (마지막 진행 상황 검토 → 계속할 작업 확인)
- 사용자가 프로젝트 내에서 작업을 시작하면 필요에 따라 작업 (수정/기록 업데이트/저장/종료)
작업 상세
📌 상호작용 규칙 (강제): 사용자에게 "예/아니오" 또는 "다중 선택"을 요청하는 모든 질문은 반드시 AskUserQuestion 도구를 사용하여 옵션 카드로 제시해야 합니다 (두 개 이상의 옵션 버튼), 일반 텍스트 질문은 금지됩니다. 적용 대상: grill-with-docs 도입 여부, 문서 프레임워크 구축 여부, 프로젝트 유형 확인, key/배경 확인 (제안 따름 or 수정), 삭제 확인, 세션 이어가기 선택 (어느 항목부터 계속) 등.
🆕 새 프로젝트 생성
- 프로젝트 이름 + 배경 설명 묻기, key 생성:
<영문 약어>_<YYYYMMDD> - PROJECTS.json 백업 → 디렉토리 생성 → README.md + CLAUDE.md +
.gitignore작성 (.gitignore에PROJECTS.json,backups/,*.bak,.memory/포함) - PROJECTS.json에 등록 (seq = nextSeq, 이후 nextSeq +1)
cd프로젝트 디렉토리로 이동,git init- 반드시 grill-with-docs 스킬 도입 여부 질문 (AskUserQuestion 카드: 도입 / 미도입):
- 동의 → 세 가지 조치 실행 (언어로만 "도입됨"이라고 하지 않음):
① CLAUDE.md "의존 관계" 테이블에 기록:
| grill-with-docs | 도입 | 디자인 심문流程 (사용자가 수동으로 /grill-with-docs 호출 필요) |② 초기 할 일 목록 상단에 알림 한 줄 추가 ("수동" 표시, 실행 가능한 작업 아님):- [ ] 📌 알림 (수동): 설계/계획 시 /grill-with-docs를 입력하여 심문 시작 (이 스킬은 사용자가 수동으로만 호출 가능, AI가 대신 활성화할 수 없음)③ 사용자에게 호출 방법 명시적으로 안내: "최초 설계/계획 시 수동으로 /grill-with-docs 입력" - 거절 → 기록하지 않음, 할 일 목록에 추가하지 않음, 정상 진행
- 동의 → 세 가지 조치 실행 (언어로만 "도입됨"이라고 하지 않음):
① CLAUDE.md "의존 관계" 테이블에 기록:
- 코드/엔지니어링 프로젝트: 선택적 문서 프레임워크 구축 여부 질문 (AskUserQuestion 카드: 구축 / 건너뛰기; "📁 선택적 문서 프레임워크" 참조); 업무/문서 프로젝트는 건너뜀
CLAUDE.md 초기 템플릿은 하단을 참조하세요.
🗑️ 프로젝트 삭제
- 프로젝트 찾기 → JSON 항목 + 디렉토리 파일 목록 표시 → 되돌릴 수 없는 위험 표시
- 사용자 확인 후: PROJECTS.json 백업 → JSON 항목 삭제 → 프로젝트 디렉토리 삭제 → 남은 프로젝트 1부터 연속 재번호 부여 → nextSeq = max(seq) + 1
💾 프로젝트 저장
- 백업 CLAUDE.md (
<스킬 디렉토리>/backups/, 즉~/.claude/skills/project-registry/backups/) - 이번 대화 검토, 다음 내용을 CLAUDE.md에 추가 또는 업데이트:
- 최신 진행 상황 및 완료된 작업
- 새로 추가된 아키텍처 결정 (일상적인 결정은 "📜 결정 기록 규율" 형식에 따라 추가, 이유 생략 불가)
- 할 일 목록 업데이트 (완료된 항목은 ✅ 표시, 새 항목 추가)
- 알려진 문제 업데이트
- ⚠️ "다음 작업"은 반드시 우선순위별로 나열 (1. 2. 3.), 생략 불가 (다음 세션에서 여기부터 이어감)
- 커밋 CLAUDE.md 변경 사항을 git에
- 다음 도구 제안: 프로젝트 내용과 할 일에 따라 사용 가능한 스킬 (예: ppt-master / docx / xlsx / pdf 등)을 힌트로 제공, 사용자가 결정
- 저장 후 종료하지 않고 현재 디렉토리에 유지
⚠️ CLAUDE.md 자동 업데이트는 강제 규칙이며 건너뛸 수 없습니다.
🚪 프로젝트 종료
저장과 동일하지만, 마지막 단계에서 ~로 복귀:
- 백업 CLAUDE.md
- 이번 대화 검토 CLAUDE.md 업데이트 ("다음 작업" 우선순위별 포함)
- 커밋 변경 사항을 git에
- 다음 도구 제안 (저장流程과 동일)
- 종료 후 바로
~로 복귀
🔍 MD 검사 (모든 프로젝트 CLAUDE.md 상태 일괄 검사)
등록된 모든 프로젝트에 대해 CLAUDE.md 유효성을 일괄 검사합니다 (수동 선택 불필요):
- 모든 프로젝트 디렉토리 순회, 다음 3가지 항목 검사:
- 디렉토리 존재 여부
- CLAUDE.md 존재 여부
.git존재 여부 (CLAUDE.md 작동 전제:.git과 동일한 레벨에 있어야 함)
- 요약 테이블 출력:
🔍 MD 상태 검사 (총 N개 프로젝트)
┌─────┬─────────────────────────────┬─────────────────┬──────────┬──────────┬──────────┬──────────┐
│ 순번 │ key │ 프로젝트 이름 │ 디렉토리 │ CLAUDE.md│ .git │ 유효? │
├─────┼─────────────────────────────┼─────────────────┼──────────┼──────────┼──────────┼──────────┤
│ 1 │ pet_hospital_crm_20260301 │ 애완동물 병원 CRM│ ✅ │ ✅ │ ✅ │ ✅ │
│ 2 │ gym_members_app_20260315 │ 피트니스 회원 App│ ✅ │ ✅ │ ✅ │ ✅ │
│ ... │ ... │ ... │ ... │ ... │ ... │ ... │
└─────┴─────────────────────────────┴─────────────────┴──────────┴──────────┴──────────┴──────────┘
- "유효?"가 ❌인 프로젝트에 대해 개별 문제 파악:
- 디렉토리 없음 → JSON 등록에 잔여 항목이 있는지 확인
- CLAUDE.md 누락 → 템플릿으로 재생성
.git누락 →git init실행
- 자동으로
cd사용자 홈 디렉토리로 이동 (특정 프로젝트로 진입하지 않음)
📁 선택적 문서 프레임워크 (코드/엔지니어링 프로젝트)
새 코드 프로젝트 생성 시 구축 여부 질문 (업무/문서 프로젝트는 건너뜀). 구축 후 CLAUDE.md와 역할 분담: CLAUDE.md는 상태와 결정을 기록하고, 프레임워크 문서는 설계 세부 사항을 기록합니다:
<프로젝트 디렉토리>/
├── CLAUDE.md # 개발 기록 (상태/결정/할 일)
└── docs/
├── ARCHITECTURE.md # 전체 아키텍처 설명 (선택 사항)
├── adr/ # 아키텍처 결정 기록 (선택 사항, grill-with-docs/domain-modeling의 ADR 출력과 연계)
└── dev/
├── README.md # 기능 색인
└── <feature>/
├── SPEC.md # 기능 명세
└── DESIGN.md # 구현 설계
경량 원칙: 사용자가 확인한 경우에만 생성, 강제하지 않음, 기본값 아님. grill-with-docs와 연계: grill-with-docs (심문+용어+ADR)는 설계 流程이고, 프레임워크는 저장 구조입니다——먼저 심문하여 명확히 한 후, 프레임워크에 저장합니다. 역할 분담: 가벼운 결정은 CLAUDE.md "아키텍처 결정 기록"에 기록 (한 줄); 되돌리기 어렵고 실제 트레이드오프가 있는 결정은
docs/adr/에 저장; 용어집 CONTEXT.md는 domain-modeling 전용으로 유지 관리하며, 프레임워크는 중복 생성하지 않습니다.
자동 cd + CLAUDE.md 자동 업데이트
| 작업 | cd | CLAUDE.md 자동 업데이트 |
|---|---|---|
| 새로 만들기 | 프로젝트 디렉토리로 이동 | ✅ 초기 템플릿 자동 생성 |
| 검사/수정 | 프로젝트 디렉토리로 이동 | ❌ 자동 업데이트 안 함 |
| 기록 업데이트 | 프로젝트 디렉토리로 이동 | ✅ 수동 트리거 업데이트 |
| 저장 | 프로젝트 디렉토리로 이동, 저장 후 종료하지 않고 디렉토리 유지 | ✅ 자동 업데이트 |
| 종료/돌아가기 | 먼저 CLAUDE.md 업데이트 후, ~로 복귀 | ✅ 자동 업데이트 |
보안 메커니즘
PROJECTS.json 쓰기 작업 (생성, 수정, 삭제)은 먼저 백업해야 합니다:
백업 경로: <스킬 디렉토리>/backups/ (즉 ~/.claude/skills/<스킬 이름>/backups/)
백업 파일: PROJECTS.json.<YYYYMMDD_HHMMSS>.bak
CLAUDE.md 쓰기 작업 (기록 업데이트, 저장 시 자동 업데이트)은 먼저 백업해야 합니다:
백업 경로: <스킬 디렉토리>/backups/
백업 파일: CLAUDE.md.<YYYYMMDD_HHMMSS>.bak
백업 디렉토리가 없으면 자동 생성합니다.
백업 자동 로테이션:
새 백업 생성 후, 파일 유형별로 이전 백업을 정리하며, 각 유형별로 최근 10개를 유지합니다:
백업 유형 접두사:
PROJECTS.json.*.bak # 프로젝트 목록 백업, 10개 유지
CLAUDE.md.*.bak # 개발 기록 백업, 10개 유지
SKILL.md.*.bak # 스킬 자체 백업, 10개 유지
정리 규칙: 파일명 끝의 YYYYMMDD_HHMMSS에서 타임스탬프를 추출하여 정렬합니다 (참고: CLAUDE.md.<프로젝트명>.<타임스탬프>.bak와 같은 특수 명명의 백업은 타임스탬프가 끝에 있으므로 전체 이름 문자열로 정렬할 수 없음). 가장 최근 10개를 유지하고 나머지는 삭제합니다.
🔁 자동 저장 (hooks, 무음 실행)
두 계층 메커니즘, 모두 백그라운드에서 무음 실행, 실패 시 무음 재시도, ~/projects/ 프로젝트 디렉토리에서만 작동합니다.
계층 1 기계적 스냅샷 (의존성 없음, 기본 활성화)
| Hook | 동작 |
|---|---|
| Stop (응답마다) | transcript를 <프로젝트>/.memory/transcript-latest.jsonl에 동기화 (초 단위) |
| SessionEnd (세션 종료) | CLAUDE.md 백업 (10개 로테이션) + git 커밋 (변경 사항이 있을 때만 커밋) |
- ⚠️ 개인 정보 보호:
.memory/에는 대화 원문이 포함됨——반드시 gitignore로 제외 (새 프로젝트 생성 시.gitignore에.memory/포함 자동 생성), 절대 저장소에 올라가지 않음 - 강제 종료 시 SessionEnd가 트리거되지 않지만, Stop의 초 단위 동기화는 계속 작동——데이터 손실 없음
계층 3 자동 요약 (선택 사항, API 설정 후 활성화)
- 트리거: 쓰로틀 제어 (≥10개 새 메시지 또는 ≥10분)——모든 응답마다 API 호출하지 않음
- 流程:
.memory/증분 읽기 →PR_API_BASE_URL호출 (모든 OpenAI 호환 제공업체) → 진행/결정/할 일/다음 단계 추출 → 병합하여 CLAUDE.md 업데이트 (결정 추가/진행 업데이트/할 일/다음 단계) - 설정 (환경 변수):
PR_API_BASE_URL/PR_API_KEY/PR_API_MODEL(설정하지 않으면 자동 건너뜀) - 개인 정보 보호: 대화는 사용자가 설정한 엔드포인트로만 전송됨; key는 환경 변수에서 읽으며, 절대 하드코딩하지 않음
수동 저장과의 관계
자동 요약 = 실시간 신선도 유지 (증분 병합); 수동 저장 = 권위 있는 정리 (전면 검토)——둘은 호환되고 보완적입니다.
📜 결정 기록 규율 (질문 시 반드시 근거 제시)
모든 결정은 추적 가능해야 합니다: "왜 이렇게 했는지"는 항상 확인 가능해야 하며, 이유는 생략할 수 없습니다.
가벼운 결정 형식
- [상태] YYYY-MM-DD — <결정> (이유: <사유>) (예상: <효과>)
- 상태 표시:
✅실행됨/🔄진행 중/⛔기각됨/⏸️보류됨 - 이유 강제: 이유 없으면 기록하지 않음
- 예상 선택 사항: 기록 시점에 예상 효과를 알고 있으면 추가 (귀속 시 효과 검증에 사용)
기록 시점 (계층별)
| 유형 | 시점 |
|---|---|
| 주요 결정 (방향에 영향 / 되돌리기 어려움 / 리소스 소모) | 대화 중 즉시 확인: Claude가 "이 결정을 기록할까요?"라고 능동적으로 질문 |
| 일상적인 결정 | 저장/종료 시 일괄 검토하여 추가 (강제) |
중대한 결정 → ADR
되돌리기 어렵고 실제 트레이드오프가 있는 결정은 docs/adr/에 저장하고, CLAUDE.md에는 한 줄 색인을 남깁니다:
- 2026-08-08 — ADR-0001 <결정 제목> (상태: ✅실행됨)
ADR 구조: # ADR-000N <제목> + Status / Date / Context / Decision / Consequences.
CLAUDE.md 초기 템플릿
# <프로젝트 이름>
## 프로젝트 목표
<배경 설명 요약>
## 기술 스택
(추후 보충 — 언어/프레임워크/데이터베이스/배포 등)
## 현재 상태
state: active
- 단계: 요구사항 분석 / 개발 중 / 완료
- 최신 진행 상황: 프로젝트 초기화
## 아키텍처 결정 기록
모든 주요 결정 기록, 형식:
- [상태] YYYY-MM-DD — <결정> (이유: <사유>) (예상: <효과>)
(상태: ✅실행됨 / 🔄진행 중 / ⛔기각됨 / ⏸️보류됨; 이유 생략 불가, 예상은 선택 사항)
## 프로젝트 범위 및 기능
(핵심 기능 목록, 테이블로 제시 가능)
## 의존 관계
| 의존 프로젝트 | 관계 | 설명 |
|:---|:---|:---|
| <프로젝트 이름> | 의존/피의존 | <구체적 설명> |
## 할 일
- [ ] 할 일 1 (실행 가능한 수준으로 세분화)
## 알려진 문제
- (없음 — 발견 시 추가, 영향 범위 포함)
## 다음 작업
- 우선순위별로 나열 (1. 2. 3.), 저장/종료 시 강제 업데이트
새로 만들 때는 최소한 프로젝트 목표, 기술 스택, 현재 상태, 할 일 상위 3개를 채웁니다. 나머지는 개발 과정에서 점진적으로 보강합니다.
key 명명 규칙
<영문/병음 약어>_<YYYYMMDD>
예시:
애완동물 병원 CRM → pet_hospital_crm_20260301
피트니스 회원 App → gym_members_app_20260315
- 영문 우선, 병음 차선
- 모두 소문자, 밑줄로 구분
- 끝에 날짜 추가
일련번호 관리 규칙
| 작업 | 규칙 |
|---|---|
| 생성 | nextSeq를 새 프로젝트의 seq로 읽고, 등록 후 nextSeq +1 |
| 삭제 | 삭제 후 남은 프로젝트를 1부터 연속 재번호 부여, nextSeq를 max(seq) + 1로 설정 |
| seq | 항상 연속, 번호 건너뛰기 없음 |
🧠 메모리 관리 (세 계층 메커니즘)
프로젝트 레벨 메모리 (스킬 관리)
| 메모리 매체 | 기록 내용 | 관리 메커니즘 |
|---|---|---|
| CLAUDE.md | 상태 / 결정 및 이유 / 할 일 / 알려진 문제 / 다음 작업 | 세션마다 자동 로드 + 저장 시 강제 업데이트 + git 커밋 + 백업 로테이션 |
| PROJECTS.json | 프로젝트 등록 목록 (seq/key/name/status/created) | 쓰기 전 백업 |
| git 기록 + backups/ | 히스토리 버전 스냅샷 | 언제든지回溯 가능 (git show / 백업 파일) |
메모리 생명 주기
쓰기 (저장/종료 시 강제 업데이트)
→ 자동 로드 (세션마다 Claude Code가 CLAUDE.md 자동 주입)
→ 백업 (10개 로테이션 + git 커밋)
→ 검색 (CLAUDE.md 읽기 / 귀속 조사 "왜 X" / git 히스토리回溯)
메모리 경계
기록: 아키텍처 결정 및 이유 | 규칙 및 규범 | 도메인 용어 | 할 일 및 알려진 문제 | 현재 상태 및 의존 관계 | 다음 작업
기록하지 않음: 상세 코드 구현 | git으로回溯 가능한 변경 사항 | 임시 논의 (대화 원문은 보관하지 않음——"당시 정확히 무엇을 논의했는지" 확인은 Claude Code 자체 세션 보관 --resume 사용, 이 스킬의 책임 범위 아님)
전역 메모리와의 역할 분담
- 프로젝트 관련 (진행/결정/왜 이렇게 정했는지) → 본 스킬 메모리 (CLAUDE.md, 프로젝트를 따라 이동)
- 사용자 선호도/프로젝트 간 사실 (예: "PPT는 우선 ppt-master 사용") → Claude Code 전역 메모리 (
~/.claude/.../memory/, 시스템 유지, 스킬이 쓰지 않음)
CLAUDE.md 유지보수
CLAUDE.md는 Claude가 대화 시 자동으로 로드하는 프로젝트 컨텍스트 파일로, 결정과 진행 상황을 기록합니다.
업데이트 시점 (강제 규칙): 새로 만들 때 자동 생성 | 대화 종료 시 "기록 업데이트" 호출 | 주요 결정 시 추가 | 요구사항 변경 시 동기화 | ⚠️ 종료 또는 저장 시 자동 업데이트 실행 (반드시 실행, 건너뛸 수 없음), 또한 "다음 작업"은 우선순위별로 작성
기록 내용: 아키텍처 결정 및 이유 | 규칙 및 규범 | 도메인 용어 | 할 일 및 알려진 문제 | 현재 상태 및 의존 관계 | 다음 작업
기록하지 않음: 상세 코드 구현 | git으로回溯 가능한 변경 사항 | 임시 논의
작동 조건: 반드시 .git과 동일한 레벨에 있어야 하며, 파일명은 CLAUDE.md (모두 대문자)
새 프로젝트 생성 시 자동으로
git init합니다. 기존 디렉토리에.git이 없는 경우, 이유를 알리고git init을 할지 질문합니다.
🔎 귀속 조사 (왜 X)
사용자가 "왜 X / 이 결정의 배경 / 당시 왜 그렇게 했는지 / 귀속 X"라고 말하면 트리거됩니다.
流程:
- 위치 파악: 조사 대상 확인 (프로젝트 + 주제/시점)
- 증거 수집: 해당 프로젝트의 CLAUDE.md "아키텍처 결정 기록" +
docs/adr/(존재하는 경우) + git log 최근 커밋 + 진행/할 일 읽기 - 귀속 보고서 출력:
- 결정 타임라인: 관련 결정을 시간순으로 정렬
- 이유 체인: 각 결정의 이유 + 결정 간 연관 관계 (어느 결정이 어느 결정에 기반하는지)
- 상태: ✅실행됨 / 🔄진행 중 / ⛔기각됨 / ⏸️보류됨
- 이후 영향: 최신 진행 상황과 결합하여 예상이 달성되었는지 판단
- 결론: "당시 왜 그렇게 했는지" 답변, 필요 시 예상이 검증되었는지 표시
출력은 대화 내; 보관 요청 시 저장소 외부 (~/project-audit-logs/)에 저장——검사/귀속 내용은 프로젝트 개인 정보를 포함하므로 프로젝트 저장소에 쓰기 금지.
📋 프로젝트 검사 (자연어 트리거, 메뉴에 추가되지 않음)
사용자가 "프로젝트 검사 / 점검 / audit"이라고 말하면 트리거되며, 메뉴에 항목이 추가되지 않습니다.
전체 스캔 ("모든 프로젝트 검사")
구조 검사 (MD 검사 C와 동일) + 내용 5가지:
| # | 차원 | 검사 논리 |
|---|---|---|
| 1 | 상태 일관성 | PROJECTS.json의 status와 CLAUDE.md의 최신 진행/할 일이 모순되는지 |
| 2 | 프로젝트 정체 | CLAUDE.md 최근 업데이트 (git log 시간)가 14일 초과 → "정체 가능성" |
| 3 | 할 일 누적 | 미완료 할 일 10개 초과 또는 장기간 진행 없음 |
| 4 | 결정 미실행 | 결정 기록에 ✅실행됨으로 표시되었지만 진행/할 일에 반영되지 않음 |
| 5 | 다음 작업 누락 | "다음 작업" 섹션 없음 (저장流程 게으름) |
이상 항목에는 자동으로 귀속 단서가 함께 제공됩니다: 최근 N개 결정을回溯하여 어떤 결정이 관련될 수 있는지 지적합니다.
단일 프로젝트 심층 검사 ("XX 프로젝트 검사")
내용 5가지, 지정된 프로젝트만 검사합니다.
보고서는 대화 내에서만 출력; 저장 요청 시 ~/project-audit-logs/ (저장소 외부)에 저장합니다.
↩️ 버전 롤백
사용자가 "롤백 / 복원 / 되돌리기 / 저장 취소"라고 말하면 트리거됩니다. 이중 채널: git 히스토리 (프로젝트 파일) + 백업 스냅샷 (레지스트리/개발 기록).
공통 안전 규칙 (모든 롤백 시 준수):
- 먼저 현재 버전 백업 (롤백 자체도 롤백 가능해야 함)
- 반드시 차이점 요약 표시 + AskUserQuestion 카드 확인 (롤백 / 취소) 후에 실행
- 롤백은 새 커밋을 생성하며, git 히스토리를 덮어쓰지 않음
① CLAUDE.md 롤백 (개발 기록 잘못 수정/삭제)
- 위치 파악:
git log --oneline으로 최근 커밋 나열 (또는 backups/CLAUDE.md.*.bak 파일명 타임스탬프) - 비교:
git show <commit>:CLAUDE.md와 현재 버전의 차이점 (핵심: 결정/할 일/다음 작업) - 확인: 차이점 요약 표시 → 카드 확인
- 실행: 현재 버전 백업 →
git checkout <commit> -- CLAUDE.md→ 커밋 ("으로 롤백" 기록) - 보고: 롤백 내용 요약
② 프로젝트 파일 롤백 (README/docs/코드)
- 위치 파악:
git log로 대상 버전 찾기 - 비교:
git diff <commit> -- <파일> - 확인: 차이점 요약 → 카드 확인
- 실행: 현재 버전 백업 →
git checkout <commit> -- <파일>→ 커밋 - 보고
③ 레지스트리 롤백 (PROJECTS.json 잘못 삭제/수정)
- 위치 파악:
backups/PROJECTS.json.<타임스탬프>.bak(최근 10개, 끝 타임스탬프 기준 정렬) - 비교: 현재 vs 백업 diff (프로젝트 추가/삭제 나열)
- 확인: 차이점 요약 → 카드 확인
- 실행: 현재 버전 백업 →
cp 백업 → PROJECTS.json→ 검증 (프로젝트 수/seq 연속성) - 보고
힌트: 롤백은 "🔎 귀속 조사"와 함께 사용——먼저 "왜 이렇게 되었는지" 조사한 후, 어떤 버전으로 롤백할지 결정합니다.
자주 묻는 질문
- PROJECTS.json이 없음: 기본 템플릿으로 빈 목록 생성
- 디렉토리가 이미 있음: 기존 디렉토리 재사용, JSON에만 등록
- 삭제 시 프로젝트를 찾을 수 없음: 먼저 목록을 표시하여 사용자 확인