sync-project-docs
Claude Code의 프로젝트 수준 컨텍스트 파일을 감사하고 업데이트합니다. CLAUDE.md, 스킬 및 메모리는 자동으로 처리하며, 설정은 명시적인 사용자 승인이 필요하므로 제안으로 제공합니다.
1단계 — 상황 파악
프로젝트가 git을 사용하는 경우:
git log --oneline -20
git status --short
그런 다음 git diff HEAD~5 -- <아래 주요 파일들>로 최근 인프라 변경 사항을 확인합니다.
git 저장소가 없는 경우 디렉토리 구조와 주요 파일을 직접 읽습니다.
다음 파일들이 존재하는지 확인합니다:
| 찾을 대상 | 예시 |
|---|---|
| 패키지/의존성 설정 | package.json, pyproject.toml, Cargo.toml, go.mod, pom.xml, requirements.txt, Gemfile |
| 명령어 | Makefile, justfile, scripts/, package.json scripts, taskfile.yml |
| 인프라 | docker-compose.yml, fly.toml, render.yaml, Procfile, vercel.json, k8s/ |
| 앱 설정 | config.*, settings.*, config/, application.yml |
| 환경 변수 템플릿 | .env.example, .env.template, .env.sample |
목표: 어떤 작업이 완료되었고, 무엇이 진행 중이며, 어떤 주요 파일이 변경되었는지 파악합니다.
2단계 — CLAUDE.md 감사 및 업데이트
모든 프로젝트 수준 명령 파일을 확인합니다:
ls CLAUDE.md .claude/CLAUDE.md CLAUDE.local.md .claude/rules/ 2>/dev/null
CLAUDE.md가 없는 경우: sub-skills/init/SKILL.md의 init 스킬을 호출한 후 계속 진행합니다.
CLAUDE.md가 있는 경우, 파일을 읽고 각 섹션을 1단계의 소스와 교차 검증합니다:
명령어 — 실제 명령어 소스와 비교합니다. 변경된 명령어를 수정하고, 유용한 새 명령어를 추가하며, 삭제된 명령어를 제거합니다.
아키텍처/구조 — 설명된 모듈과 주요 파일을 디스크에 실제로 존재하는 것과 비교합니다. 새로 추가된 내용을 반영하고, 삭제되거나 이름이 변경된 항목은 제거합니다.
설정/환경 변수 — 실제 설정 파일과 비교합니다. 새로운 런타임 관련 설정을 추가하고, 오래된 설정은 제거하거나 수정합니다.
제약 조건 및 주의사항 — 문서화된 제약 조건이 최근 작업으로 해결되었는지 확인합니다.
환경 변수 템플릿: 설정에 필요한 모든 변수를 나열하고 있는지 확인합니다. 누락된 변수는 새로운 설정 환경을 망가뜨릴 수 있습니다.
@import 참조: @path/to/file 줄을 스캔하고 가져온 각 파일이 여전히 존재하는지 확인합니다. 누락된 임포트는 조용히 컨텍스트 로딩을 실패하게 만듭니다.
크기: 파일이 200줄을 초과하면 플래그를 표시합니다. 이 이상이면 준수율이 떨어지고 컨텍스트 비용이 증가합니다. 세부 내용을 .claude/rules/ 주제 파일로 옮길 것을 제안합니다.
.claude/rules/: 이 디렉토리가 존재하는 경우, 경로 범위 규칙 파일이 현재 코드베이스와 더 이상 일치하지 않는 명령어, 모듈 이름 또는 파일 경로를 참조하는지 확인합니다. 오래된 것을 수정하거나 플래그를 표시합니다.
CLAUDE.local.md: 이 파일이 존재하면 CLAUDE.md와 동일한 검사를 수행합니다. git에 무시되는 개인 보충 파일이므로 역시 오래될 수 있습니다.
정밀하게 작업하세요: 오래된 내용만 업데이트하고 정확한 내용은 그대로 둡니다. 이 파일은 향후 Claude 세션이 읽을 것입니다.
3단계 — 프로젝트 스킬 감사
ls .claude/skills/ 2>/dev/null
각 스킬을 읽습니다. 두 가지 범주가 있습니다:
인프라 결합 스킬 (실행, 배포, 마이그레이션, CI, 통합)은 구체적인 대상을 참조합니다 — 명령어, 서비스, 포트, 환경 변수, 파일 경로. 각각을 1단계와 교차 검증합니다:
- 참조된 명령어가 여전히 존재합니까?
- 서비스 이름, 포트 및 URL이 여전히 일치합니까?
- 환경 변수가 설정에 여전히 존재합니까?
- 파일 경로와 모듈 이름이 여전히 유효합니까?
작은 불일치는 직접 수정합니다. 실행/시작 스킬의 대대적인 재작업(새로운 시작 절차, 주요 서비스 변경)이 필요한 경우 먼저 질문합니다:
"실행 스킬이 상당히 오래된 것으로 보입니다.
/run-skill-generator로 처음부터 다시 생성하시겠습니까 (사용자 지정 주의사항이 손실될 수 있음) 아니면 오래된 섹션을 수동으로 다시 작성하시겠습니까?"
실행 스킬이 없고 시작 절차가 간단하지 않은 경우: 사용 가능하다면 /run-skill-generator를, 그렇지 않으면 /run을 대안으로 제안합니다.
프로세스/워크플로우 스킬 (PR 템플릿, 커밋 스타일): git 로그가 설명된 프로세스가 변경되었음을 암시하는 경우에만 확인하고, 그렇지 않으면 그대로 둡니다.
4단계 — 메모리
메모리 경로는 git 저장소 루트(또는 저장소 외부의 pwd)에서 파생됩니다:
REPO=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
echo "$HOME/.claude/projects/$(echo "$REPO" | sed 's|/|-|g')/memory/"
메모리가 존재하는 경우: consolidate-memory를 호출합니다.
메모리가 없는 경우: 생성하기 전에 먼저 질문합니다 —
"프로젝트 메모리가 아직 없습니다. 자동 메모리는 이미 켜져 있어서 Claude가 시간이 지남에 따라 구축할 것입니다. 하지만 지금 이 코드베이스의 핵심 사실로 시드하여 다음 세션이 바로 방향을 잡을 수 있도록 하시겠습니까?"
동의하는 경우: 향후 세션이 다시 유도하는 데 시간을 낭비할 명확하지 않은 사실을 시드합니다:
- 놀라운 제약 조건 (동시성 모델, 버전 고정, 예상치 못한 기본값)
- 현재 진행 중인 작업과 그 이유
- 코드에 반영된 명확하지 않은 결정
MEMORY.md를 한 줄에 하나의 항목으로 간결하게 생성합니다. 상세 노트는 별도의 주제 파일(예: architecture.md, constraints.md)에 저장합니다. MEMORY.md는 세션 컨텍스트 창에 맞도록 200줄 미만으로 유지합니다.
5단계 — 설정
더 이상 존재하지 않는 스크립트나 명령어를 참조하는 오래된 훅이 있는지 .claude/settings.json을 확인합니다.
지속적으로 사용되는 읽기 전용 명령어(테스트 러너, 린터, 헬스 체크, git log, git diff)를 식별하여 프롬프트 없이 허용해도 안전한지 판단합니다.
settings.json에 직접 쓰지 말고 제안으로 제시합니다. 다음을 안내합니다:
update-config: 권한, 환경 변수 추가 또는 훅 수정fewer-permission-prompts: 실제 transcript 기록에서 권한 찾기
6단계 — 정리
모든 결과가 이제 디스크에 저장되었습니다. 마무리하기 전에 사용자에게 /compact 명령을 실행하여 새로운 상태에서 시작하도록 컨텍스트를 처리하라고 알립니다.
요약
변경 사항 요약을 출력합니다:
## 프로젝트 동기화 완료
**CLAUDE.md**: <변경 사항, 또는 "변경 불필요">
**스킬**: <업데이트된 내용, 또는 "정확함">
**메모리**: <통합됨 / 시드됨 / "변경 없음">
**설정 제안**: <제안된 허용 사항, 또는 "추가할 내용 없음">
**Git 상태**: <커밋되지 않은 파일 + 진행 중인 작업, 한 문장>
`git diff`를 실행하여 파일 변경 사항을 검토하십시오.