sync-docs

/sync-docs - 문서 동기화 (v7.1)

Scope: prompt_plan.md, spec.md, CLAUDE.md, .claude/rules/ 등 핵심 프로젝트 메타 문서 동기화. 일반 문서(README, API docs, 가이드)는 /update-docs를 사용하세요.

---

0단계: 작업 설명 확인

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

git log --oneline -5

---

0.5단계: 흩어진 파일 housekeeping scan (CRITICAL, 2026-05-29 신설)

규칙: ~/qjc-office/dotclaude/rules/sync-housekeeping.md

문서 동기화 전, cwd에 흩어진 untracked 파일을 감지한다. 실제 이동은 본 명령어가 수행하지 않으며, 감지만.

~/.claude/scripts/sync-housekeeping-scan.sh --json > /tmp/sync-docs-housekeeping.json
LEVEL=$(python3 -c "import json; print(json.load(open('/tmp/sync-docs-housekeeping.json'))['level'])")

Level	동작
alert (PII/시크릿 패턴 감지)	즉시 중단 + /save-work --apply로 sanitize 권장 안내
warn (민감 파일 의심 또는 10개+ 흩어진 문서)	한국어 배너 stderr 출력 + 진행 유지 + /save-work --apply 권장
info (흩어진 파일 1~9개)	한 줄 카운트 출력 + 진행 유지
ok (정상)	출력 없이 진행

비활성: export QJC_SYNC_HOUSEKEEPING_DISABLED=1

---

1단계: 모드 결정 (CRITICAL)

인자에 --check-only가 포함되어 있으면:

• 모든 Write/Edit 도구 호출을 금지한다.
• 각 단계에서 "변경이 필요한 항목"만 수집한다.
• 9단계의 --check-only 출력 형식을 사용한다.

이 판단은 이후 모든 단계에 적용된다. --check-only 모드에서는 Read/Glob/Grep/Bash(git)만 사용한다.

---

2단계: 변경된 코드 분석

현재 브랜치에서 변경된 파일과 내용을 파악한다.

diff 범위 자동 감지:

# main/master 브랜치와의 분기점 기반 (우선)
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
  # 분기점이 없으면 (main 브랜치 자체) 최근 커밋 기반
  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가 출력되면 동기화할 변경사항이 없으므로 사용자에게 알리고 종료한다.

---

충돌 해결 원칙