/sync

/sync - Git Pull + 문서 동기화

---

플래그

플래그	설명
--no-pull	pull 건너뛰고 문서 동기화만 실행 (/sync-docs와 동일)
--check-only	문서 변경 필요 사항만 보여주고 수정하지 않음
(없음)	pull + 문서 동기화 모두 실행

---

Phase 1: Git Pull (--no-pull 시 스킵)

1-1. 현재 상태 확인

git branch --show-current
git status --short

커밋되지 않은 변경사항이 있으면 경고:

작업 중인 변경사항이 있습니다. stash 후 진행할까요? (Y/n)

• Y: git stash 후 진행, pull 후 git stash pop
• n: 그대로 pull 시도

1-2. Pull 실행

git pull origin main

충돌 발생 시 Phase 2 진행하지 않고 충돌 보고 후 중단.

---

Phase 2: 문서 동기화 (sync-docs v7 로직)

2-0. 모드 결정 (CRITICAL)

--check-only 플래그가 있으면:

• 모든 Write/Edit 도구 호출을 금지한다.
• 각 단계에서 "변경이 필요한 항목"만 수집한다.
• Read/Glob/Grep/Bash(git)만 사용한다.

2-1. 작업 설명 확인

인자로 전달된 작업 설명을 확인한다. 인자가 없으면 최근 커밋 메시지에서 작업 내용을 추론한다.

git log --oneline -5

2-2. 변경된 코드 분석

diff 범위 자동 감지:

BASE=$(git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null)
if [ -n "$BASE" ] && [ "$BASE" != "$(git rev-parse HEAD)" ]; then
  git diff --name-only "$BASE"..HEAD
  git diff --stat "$BASE"..HEAD
else
  COMMIT_COUNT=$(git rev-list --count HEAD 2>/dev/null || echo "0")
  if [ "$COMMIT_COUNT" -eq 0 ]; then
    echo "NO_COMMITS"
  elif [ "$COMMIT_COUNT" -ge 3 ]; then
    git diff --name-only HEAD~3..HEAD
    git diff --stat HEAD~3..HEAD
  else
    git diff --name-only HEAD~1..HEAD
    git diff --stat HEAD~1..HEAD
  fi
fi

NO_COMMITS가 출력되면 동기화할 변경사항이 없으므로 사용자에게 알리고 종료한다.

충돌 해결 원칙

소스 코드(git diff)가 최우선 진실 소스(source of truth)이다.

2-3. prompt_plan.md 동기화

Glob 패턴으로 prompt_plan.md를 탐색한다:

• ./prompt_plan.md
• ./.claude/prompt_plan.md
• ./docs/prompt_plan.md

업데이트 항목:

• 완료된 작업 항목 체크 (- [x])
• 진행 상황 갱신
• 다음 단계 업데이트

파일이 없으면 건너뛴다.

2-4. spec.md 동기화

Glob 패턴으로 spec.md를 탐색한다:

• ./spec.md
• ./docs/spec.md
• ./.claude/spec.md

업데이트 항목:

• 구현된 기능 반영
• API 변경사항 반영
• 데이터 모델 변경 반영

파일이 없으면 건너뛴다.

2-5. CLAUDE.md 동기화 (60줄 제한)

Glob 패턴으로 CLAUDE.md를 탐색한다:

• ./CLAUDE.md
• ./.claude/CLAUDE.md

60줄 제한 규칙 (CRITICAL):

CLAUDE.md는 60줄 이하를 유지한다.

CLAUDE.md에 허용되는 내용 (Core 정보만):

• 프로젝트 개요, 기술 스택, 필수 명령어, 핵심 디렉토리, Git 워크플로우, Rules 참조

CLAUDE.md에 넣으면 안 되는 내용 → rules/로 이동:

• 코딩 스타일/컨벤션 상세, 테스트 규칙, API 설계, 보안, DB 패턴

동기화 동작:

1. CLAUDE.md를 Read로 읽고 줄 수 카운트
2. 빌드 명령어/파일 구조/의존성 변경 → CLAUDE.md에 반영
3. 코딩 규칙/패턴 상세 → rules/ 파일로 라우팅 (2-6단계)
4. 60줄 초과 시 상세 내용을 rules/로 분리

2-6. rules/ 동기화

.claude/rules/ 디렉토리의 규칙 파일을 코드 변경에 맞게 동기화한다.

Glob: .claude/rules/**/*.md

판단 기준:

• 기존 rules 파일에 해당 주제가 있으면 → 해당 파일 업데이트
• 해당 주제의 rules 파일이 없으면 → 새 rules 파일 생성하지 않음 (알림만)
• 예외: CLAUDE.md가 80줄을 초과하여 분리가 필수인 경우, 적절한 이름으로 새 rules 파일 생성 가능

2-7. CLAUDE.md 줄 수 최종 검증

줄 수	상태	동작
≤ 60	정상	완료
61-80	경고	출력에 경고 표시, 분리 제안
> 80	초과	상세 내용을 rules/로 분리 실행

---

출력

전체 실행 (pull + sync)

════════════════════════════════════════════════════════════════
  Sync v7 (pull + docs)
════════════════════════════════════════════════════════════════

  [Pull]
    브랜치: {branch}
    상태: {up-to-date | N commits pulled}

  [Docs]
    작업: {작업 설명}

    prompt_plan.md  {업데이트 | 없음 | 변경없음}
    spec.md         {업데이트 | 없음 | 변경없음}
    CLAUDE.md       {업데이트 | 없음 | 변경없음} (N줄)
    rules/          {N개 업데이트 | 변경없음}

    변경 요약:
      - {변경 항목 1}
      - {변경 항목 2}

    CLAUDE.md: N줄 (정상 / 경고: 60줄 초과)

  다음: /quick-commit

════════════════════════════════════════════════════════════════

--no-pull (문서만)

════════════════════════════════════════════════════════════════
  Sync v7 (docs only)
════════════════════════════════════════════════════════════════

  작업: {작업 설명}

  동기화 결과:
    prompt_plan.md  {업데이트 | 없음 | 변경없음}
    spec.md         {업데이트 | 없음 | 변경없음}
    CLAUDE.md       {업데이트 | 없음 | 변경없음} (N줄)
    rules/          {N개 업데이트 | 변경없음}

  CLAUDE.md: N줄 (정상 / 경고: 60줄 초과)

  다음: /quick-commit

════════════════════════════════════════════════════════════════

--check-only

════════════════════════════════════════════════════════════════
  Sync v7 (check-only)
════════════════════════════════════════════════════════════════

  변경 필요 사항:

  prompt_plan.md:
    - [ ] → [x] Task 3: API 엔드포인트 구현

  spec.md:
    - API 섹션에 POST /api/users 추가 필요

  CLAUDE.md (현재 N줄):
    - 새 명령어 추가 필요: pnpm db:migrate

  rules/:
    - rules/api-design.md: POST /api/users 추가 필요

  적용하려면: /sync (--check-only 없이 실행)

════════════════════════════════════════════════════════════════

충돌 발생 시

════════════════════════════════════════════════════════════════
  Sync (중단)
════════════════════════════════════════════════════════════════

  [Pull] 충돌 발생! 수동 해결 필요:
    {충돌 파일 목록}

  문서 동기화는 충돌 해결 후 /sync --no-pull 로 실행하세요.

════════════════════════════════════════════════════════════════

동기화할 문서가 없는 경우

════════════════════════════════════════════════════════════════
  Sync v7 (pull + docs)
════════════════════════════════════════════════════════════════

  [Pull]
    브랜치: {branch}
    상태: {up-to-date | N commits pulled}

  [Docs]
    동기화 대상 문서를 찾을 수 없습니다.

    확인할 위치:
      - prompt_plan.md (프로젝트 루트, .claude/, docs/)
      - spec.md (프로젝트 루트, docs/, .claude/)
      - CLAUDE.md (프로젝트 루트, .claude/)
      - .claude/rules/*.md

════════════════════════════════════════════════════════════════