docs: 작업 흐름을 GitHub Issue/PR/Wiki 모델로 전환

- CLAUDE.md: 문서 구조/워크플로우를 이슈→작업→PR→Wiki 4단계로 개정,
  스펙 canonical을 GitHub Wiki로 이동
- .claude/github-workflow.md: 신규. issue/PR/wiki 구체 절차(gh, 브랜치 규칙)
- .claude/dod.md, commit-rules.md: PR/브랜치 규칙, 작업로그→PR, 스펙→Wiki
- 강제 훅 조정:
  - check-plan-on-edit: docs/plans 강제 → main 직접 소스 수정 차단(이슈 브랜치 유도)
  - check-docs-on-stop: works/spec 로컬 강제 제거, cargo check 안전망만 유지
  - spec-sync-check: specification/ → Wiki 갱신 리마인드

Refs #18

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: trz-21

.claude/commit-rules.md

@@ -11,7 +11,7 @@
 ```
 <type>: <subject>
 
-[optional body]
+[optional body — 관련 이슈는 Refs #N / #N 으로 참조]
 
 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
 ```
@@ -34,6 +34,15 @@ Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
 - 서로 독립적인 변경은 **별도 커밋**
 - `.env`, `.env.prod`, 시크릿 파일은 **절대 커밋 금지**
 
+## 브랜치 / PR (GitHub 작업 흐름)
+
+상세: `.claude/github-workflow.md`
+
+- 작업은 `main` 직접 커밋 대신 **이슈 기반 브랜치**에서: `feature/issue-<N>-<slug>` (fix는 `fix/issue-<N>-<slug>`)
+- 완료 시 **PR**로 올린다. PR 본문 첫 줄에 **`Closes #N`** → 머지 시 이슈 자동 종료
+- PR 본문이 작업 로그 역할 (변경 요약 / 검증 / 주요 결정)
+- 루트 단일 레포 → 프로젝트 루트에서 커밋 (backend/frontend는 별도 레포 아님)
+
 ## 푸시
 
-사용자가 명시적으로 요청할 때만 푸시한다.
+사용자가 명시적으로 요청할 때만 푸시한다 (`git push`, PR 생성 포함).

.claude/dod.md

@@ -4,10 +4,11 @@
 
 ## 체크리스트
 
+- [ ] **이슈**: 작업 단위가 GitHub Issue로 등록돼 있다 (`#N`) — `.claude/github-workflow.md`
 - [ ] **컴파일/타입**: `cargo check` (BE) / `npm run type-check` (FE) 통과
 - [ ] **테스트**: `cargo test` (BE) / `npm test -- --run` (FE) 전체 통과
-- [ ] **작업 로그**: `docs/works/YYYYMMDD-[작업명].md` 작성
-- [ ] **스펙 동기화**: 기능/설계 변경 시 `specification/` 해당 파일 업데이트
+- [ ] **작업 로그**: **PR 본문**에 `Closes #N` + 작업 요약 (기존 `docs/works` 대체)
+- [ ] **스펙 동기화**: 기능/설계 변경 시 **GitHub Wiki** 해당 페이지 업데이트
 - [ ] **커밋**: 작업 단위로 git commit (`.claude/commit-rules.md` 참조)
 
 ## 검증 명령어
@@ -30,5 +31,5 @@ npm test -- --run
 메인이 서브에이전트 완료 후 직접 검증해야 한다:
 
 1. 해당 명령어 실행 (cargo check, npm run type-check, cargo test, npm test -- --run)
-2. `docs/works/YYYYMMDD-*.md` 오늘 날짜 파일 존재 확인
+2. 작업이 GitHub Issue(`#N`)에 연결돼 있고, 완료 시 PR(`Closes #N`)로 기록되는지 확인
 3. 모두 통과 시에만 작업 완료 처리

.claude/github-workflow.md

@@ -0,0 +1,135 @@
+# GitHub 작업 흐름 (Issue → 작업 → PR → Wiki)
+
+문서화는 로컬 `docs/` 대신 **GitHub Issue / PR / Wiki**를 적극 활용한다.
+모든 작업 단위는 아래 4단계를 **순서대로** 따른다.
+
+```
+1. 이슈 등록   →   2. 작업(harness)   →   3. PR(Closes #N)   →   4. Wiki 업데이트
+```
+
+- 레포: `boostcampwm-snu-2026-1/ServiceForSmallCommerce-taeyoon`
+- 도구: `gh` CLI (인증됨), Wiki는 `*.wiki.git` 클론
+
+---
+
+## 1단계: 이슈 등록 (기존 `docs/plans` 대체)
+
+작업을 시작하기 **전에** GitHub Issue로 작업 단위를 등록한다.
+`/task-with-harness`의 "구현 계획"이 곧 이슈 본문이 된다.
+
+```bash
+gh issue create \
+  --title "<작업 제목>" \
+  --body "$(cat <<'EOF'
+## 목표
+<무엇을, 왜>
+
+## 작업 항목
+- [ ] 서브태스크 1 (대상 파일)
+- [ ] 서브태스크 2
+
+## 영향 범위
+- BE / FE / 문서
+
+## 테스트 전략
+- <harness 관점: 단위/통합 테스트, 커버리지>
+EOF
+)"
+```
+
+- 반환된 이슈 번호(`#N`)를 브랜치/PR에서 참조한다.
+- 큰 작업은 서브태스크 체크박스로 분해해 진행 상황을 이슈에서 추적한다.
+
+---
+
+## 2단계: 작업 (브랜치 + harness)
+
+이슈 기반 브랜치를 만들고 `/task-with-harness`로 구현한다.
+
+```bash
+git checkout -b feature/issue-<N>-<slug>
+```
+
+- 브랜치 네이밍: `feature/issue-<N>-<slug>` (fix는 `fix/issue-<N>-<slug>`)
+- harness 검증(컴파일/테스트/커버리지)은 `.claude/dod.md` 기준 그대로 유지한다.
+- 커밋 규칙은 `.claude/commit-rules.md`. 커밋 메시지 본문에 `Refs #N` 또는 `#N`을 남긴다.
+- **루트 단일 레포**이므로 프로젝트 루트에서 커밋한다 (backend/frontend는 별도 레포 아님).
+
+---
+
+## 3단계: 이슈 기반 PR (기존 `docs/works` 대체)
+
+작업이 DoD를 충족하면 PR을 올린다. **PR 본문이 작업 로그 역할**을 한다.
+
+```bash
+git push -u origin feature/issue-<N>-<slug>
+gh pr create \
+  --base main \
+  --title "<type>: <작업 제목>" \
+  --body "$(cat <<'EOF'
+Closes #<N>
+
+## 작업 요약
+<무엇을 구현했는지>
+
+## 변경 내용
+- <파일/모듈별 요약>
+
+## 검증
+- [ ] cargo check / cargo test (BE)
+- [ ] npm run type-check / npm test -- --run (FE)
+- [ ] 커버리지 유지/상승
+
+## 주요 결정과 이유
+- <설계 판단>
+
+## Wiki 반영 예정
+- <업데이트할 Wiki 페이지>
+EOF
+)"
+```
+
+- 본문 첫 줄에 **`Closes #N`**(또는 `Fixes #N`)을 넣어 머지 시 이슈 자동 종료.
+- 리뷰가 필요하면 `gh pr create` 후 리뷰어 지정. `git push`는 사용자가 명시 요청 시에만 (`.claude/commit-rules.md`).
+
+---
+
+## 4단계: Wiki 업데이트 (스펙 = 최종 현황, canonical)
+
+기능/설계가 바뀌면 **GitHub Wiki**의 해당 페이지를 최신 현황으로 갱신한다.
+Wiki는 별도 git 레포다.
+
+```bash
+# 최초 1회: 작업 디렉터리 밖에 클론
+git clone https://github.com/boostcampwm-snu-2026-1/ServiceForSmallCommerce-taeyoon.wiki.git /tmp/srv-wiki
+cd /tmp/srv-wiki
+
+# 페이지 수정 후
+git add -A && git commit -m "docs: <페이지> 현황 갱신 (refs #<N>)" && git push
+```
+
+### Wiki 페이지 구성
+
+| 페이지 | 내용 | 원본 스냅샷 |
+|--------|------|-------------|
+| `Home` | 개요 + 네비게이션 + 작업 흐름 요약 | — |
+| `Workflow` | 이 문서의 GitHub 작업 흐름 | `.claude/github-workflow.md` |
+| `Service-Overview` | 서비스 스펙 | `specification/service/overview.md` |
+| `Tech-Stack` | 기술 스택 | `specification/dev/tech-stack.md` |
+| `API` | API 엔드포인트 | `specification/dev/api.md` |
+| `Backend` | 백엔드 구조 | `specification/dev/backend.md` |
+| `Frontend` | 프론트엔드 구조 | `specification/dev/frontend.md` |
+| `Harness` | 테스트 하네스 | `specification/dev/harness.md` |
+
+- 페이지 파일명은 `<Page-Name>.md` (공백은 `-`).
+- 페이지 간 링크는 `[[Page-Name]]` 또는 `[텍스트](Page-Name)`.
+
+---
+
+## 요약 체크리스트
+
+- [ ] 작업 전 **이슈** 등록했는가? (`#N` 확보)
+- [ ] `feature/issue-<N>-<slug>` 브랜치에서 작업했는가?
+- [ ] harness(DoD) 검증을 통과했는가?
+- [ ] **PR** 본문에 `Closes #N` + 작업 요약을 넣었는가?
+- [ ] 스펙 변경분을 **Wiki**에 반영했는가?

.claude/hooks/check-docs-on-stop.sh

@@ -4,9 +4,11 @@ STOP_HOOK_ACTIVE=$(echo "$INPUT" | jq -r '.stop_hook_active // false')
 if [ "$STOP_HOOK_ACTIVE" = "true" ]; then exit 0; fi
 PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}"
 
+# 컴파일 안전망은 유지. 작업 로그/스펙 동기화는 새 흐름에서 PR 본문/Wiki가 담당하므로
+# 로컬 docs 강제 블록은 제거하고, 구조적 BE 변경 시 Wiki 갱신을 비차단 리마인드한다.
+# (PR/Wiki 절차: .claude/github-workflow.md)
 RUST_MARKER="${PROJECT_ROOT}/.claude/.pending-rust-check"
 SPEC_MARKER="${PROJECT_ROOT}/.claude/.pending-spec-check"
-MARKER="${PROJECT_ROOT}/.claude/.pending-doc-check"
 
 if [ -f "$RUST_MARKER" ]; then
   BACKEND_DIR="${PROJECT_ROOT}/backend"
@@ -18,12 +20,7 @@ if [ -f "$RUST_MARKER" ]; then
 fi
 
 if [ -f "$SPEC_MARKER" ]; then
-  echo "{\"decision\": \"block\", \"reason\": \"구조적 BE 파일이 변경됐는데 specification/ 업데이트가 없습니다.\"}"
-  exit 0
+  echo "⚠️  구조적 BE 변경 감지: 관련 GitHub Wiki 페이지(Backend/API 등) 갱신이 필요한지 확인하세요. (.claude/github-workflow.md)" >&2
 fi
 
-if [ -f "$MARKER" ]; then
-  TODAY=$(date +%Y%m%d)
-  echo "{\"decision\": \"block\", \"reason\": \"소스 코드가 변경됐는데 작업 로그가 없습니다. docs/works/${TODAY}-[작업명].md 를 작성한 후 완료하세요.\"}"
-  exit 0
-fi
+exit 0

.claude/hooks/check-plan-on-edit.sh

@@ -1,17 +1,22 @@
 #!/bin/bash
+# 새 작업 흐름(.claude/github-workflow.md): 작업 전 GitHub 이슈 등록 →
+# 이슈 기반 브랜치(feature/issue-<N>-..., fix/issue-<N>-...)에서 작업.
+# docs/plans 로컬 플랜 강제 대신, "main 직접 소스 수정"을 차단해 브랜치 흐름을 강제한다.
 INPUT=$(cat)
 FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.path // ""')
 PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}"
 
-# docs/plans/ 작성 자체는 허용
-if echo "$FILE_PATH" | grep -qE 'docs/plans/'; then exit 0; fi
-
-# 소스 파일이 아니면 통과
+# 소스 파일이 아니면 통과 (문서/설정 수정은 자유)
 if ! echo "$FILE_PATH" | grep -qE '(backend/src/|frontend/src/|frontend/app/|backend/tests/|backend/migrations/)'; then
   exit 0
 fi
 
-PLAN_MARKER="${PROJECT_ROOT}/.claude/.plan-exists"
-if [ -f "$PLAN_MARKER" ]; then exit 0; fi
+cd "${PROJECT_ROOT}" || exit 0
+BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
+
+# main/master 가 아닌 브랜치에서 작업 중이면 통과 (이슈 기반 브랜치로 간주)
+if [ -n "$BRANCH" ] && [ "$BRANCH" != "main" ] && [ "$BRANCH" != "master" ]; then
+  exit 0
+fi
 
-echo '{"decision": "block", "reason": "소스 코드를 수정하기 전에 작업 플랜을 먼저 작성하세요.\n\ndocs/plans/YYYYMMDD-[작업명].md 파일을 작성한 뒤 다시 시도하세요."}'
+echo '{"decision": "block", "reason": "main에서 소스 코드를 직접 수정하려고 합니다.\n\n새 작업 흐름(.claude/github-workflow.md): 1) GitHub 이슈 등록 → 2) feature/issue-<N>-<slug> 브랜치 생성 후 작업.\n\ngh issue create 로 이슈를 만들고, git checkout -b feature/issue-<N>-<slug> 로 브랜치를 판 뒤 다시 시도하세요."}'

.claude/hooks/spec-sync-check.sh

@@ -7,22 +7,18 @@ PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.."
 cd "${PROJECT_ROOT}" || exit 0
 git rev-parse --git-dir &>/dev/null || exit 0
 
+# 스펙의 최종 현황은 GitHub Wiki(canonical). 구조적 코드 변경 시,
+# 갱신이 필요할 수 있는 Wiki 페이지를 비차단으로 리마인드한다. (.claude/github-workflow.md)
 CHANGED=$(git diff --name-only 2>/dev/null; git diff --name-only --cached 2>/dev/null)
 CHANGED=$(echo "$CHANGED" | sort -u)
 [ -z "$CHANGED" ] && exit 0
 
-MISSING_SPECS=()
-check_spec() {
-  local spec_file="$1"
-  echo "$CHANGED" | grep -q "^${spec_file}$" && return
-  MISSING_SPECS+=("$spec_file")
-}
+PAGES=()
+echo "$CHANGED" | grep -qE "^backend/src/(application|domain|adapters)/" && PAGES+=("Backend")
+echo "$CHANGED" | grep -qE "^backend/src/http/(handlers/|router\.rs)" && PAGES+=("API")
+echo "$CHANGED" | grep -qE "^frontend/src/features/" && PAGES+=("Frontend")
 
-echo "$CHANGED" | grep -qE "^backend/src/(application|domain|adapters)/" && check_spec "specification/dev/backend.md"
-echo "$CHANGED" | grep -qE "^backend/src/http/(handlers/|router\.rs)" && check_spec "specification/dev/api.md"
-echo "$CHANGED" | grep -qE "^frontend/src/features/" && check_spec "specification/dev/frontend.md"
+[ ${#PAGES[@]} -eq 0 ] && exit 0
 
-[ ${#MISSING_SPECS[@]} -eq 0 ] && exit 0
-
-echo "⚠️  스펙 동기화 확인 필요:" >&2
-printf "  - %s\n" "${MISSING_SPECS[@]}" >&2
+echo "⚠️  코드 변경 감지 — GitHub Wiki 페이지 갱신이 필요한지 확인하세요:" >&2
+printf "  - Wiki: %s\n" "${PAGES[@]}" >&2

CLAUDE.md

@@ -13,52 +13,50 @@
 새 세션 또는 서브에이전트 시작 시 순서대로 읽어라:
 
 1. 이 파일 (`CLAUDE.md`) — 전체 맥락
-2. `docs/works/` 최신 파일 — 최근 작업 내용 및 레퍼런스
-3. `specification/service/` — 현재 서비스 스펙
-4. `specification/dev/` 해당 영역 — 기술 구현 스펙
+2. `.claude/github-workflow.md` — **이슈 → 작업 → PR → Wiki** 작업 흐름 (필수)
+3. 관련 **GitHub Issue / PR** — 최근 작업 맥락 (`gh issue list`, `gh pr list`)
+4. **GitHub Wiki** — 현재 서비스/기술 스펙의 최종 현황 (canonical)
 5. 필요 시 `docs/decisions/` 세부 내용 참고
 
 ---
 
-## 문서 구조
+## 작업 흐름 (GitHub Issue → 작업 → PR → Wiki)
+
+문서화는 **GitHub Issue / PR / Wiki를 적극 활용**한다. 모든 작업은 아래 4단계를 따른다.
 
 ```
-service-for-small-business-taeyoon/
-│
-├── specification/              # 살아있는 스펙 (항상 최신 상태)
-│   ├── service/                # 서비스 스펙 (사용자/기능 관점)
-│   │   └── overview.md
-│   └── dev/                    # 개발 스펙 (기술 구현)
-│       ├── tech-stack.md
-│       ├── api.md
-│       ├── backend.md
-│       ├── frontend.md
-│       └── harness.md
-│
-├── docs/                       # 작업 기록 (축적형, 삭제 금지)
-│   ├── works/                  # 작업 완료 로그 (YYYYMMDD-slug.md)
-│   ├── plans/                  # 작업 시작 전 플랜 (YYYYMMDD-slug.md)
-│   ├── decisions/              # 의사결정 기록 (ADR)
-│   └── sessions/               # 세션 종료 시 자동 생성 로그 (YYYYMMDD-HHMMSS.md)
-│
-├── backend/                    # Rust 백엔드 코드
-├── frontend/                   # Next.js 프론트엔드 코드
-└── CLAUDE.md                   # 이 파일
+1. 이슈 등록     gh issue create — 작업 단위를 GitHub Issue로 (= 기존 docs/plans)
+2. 작업          /task-with-harness — 이슈 기반 브랜치에서 구현 + harness 검증
+3. PR            gh pr create — "Closes #N", PR 본문이 작업 로그 (= 기존 docs/works)
+4. Wiki 업데이트  스펙 변경분을 GitHub Wiki(최종 현황, canonical)에 반영
 ```
 
-### 문서 작성 규칙
+상세 절차: **`.claude/github-workflow.md`** (gh 명령어, 브랜치 규칙, PR/Wiki 템플릿)
+
+### 문서가 사는 곳
+
+| 문서 종류 | 위치 | 비고 |
+|-----------|------|------|
+| **스펙 (살아있는 현황)** | **GitHub Wiki** | canonical. 서비스/기술 스펙의 최종 현황 |
+| **작업 플랜** | **GitHub Issue** | 작업 시작 전 등록 (기존 `docs/plans` 대체) |
+| **작업 로그** | **GitHub PR** | `Closes #N` + PR 본문 (기존 `docs/works` 대체) |
+| 의사결정 (ADR) | `docs/decisions/YYYYMMDD-slug.md` | 레포 보존 (불변 기록) |
+| 세션 로그 | `docs/sessions/YYYYMMDD-HHMMSS.md` | 세션 종료 시 자동 생성, 레포 보존 |
 
-| 문서 종류 | 위치 | 언제 작성 |
-|-----------|------|-----------|
-| 스펙 변경 | `specification/` | 기능/설계가 바뀔 때마다 업데이트 |
-| 작업 플랜 | `docs/plans/YYYYMMDD-slug.md` | 작업 시작 전 (훅이 강제함) |
-| 작업 로그 | `docs/works/YYYYMMDD-slug.md` | 작업 단위 완료 시 |
-| 의사결정 | `docs/decisions/YYYYMMDD-slug.md` | 중요한 기술 결정 시 |
-| 세션 로그 | `docs/sessions/YYYYMMDD-HHMMSS.md` | 세션 종료 시 자동 생성 |
+> `specification/` 디렉터리는 Wiki 이관 이전의 스냅샷이다. **스펙의 최신본은 항상 Wiki를 본다.**
+> `docs/decisions/`, `docs/sessions/` 등 레포에 남은 문서는 **삭제하지 않는다** (WAL, append-only).
 
-**모든 문서는 삭제하지 않는다.** 스펙 파일은 업데이트 가능.
+### 레포 디렉터리
 
-**`docs/` 하위 문서는 WAL(Write-Ahead Log) 방식으로 append-only.**
+```
+service-for-small-business-taeyoon/
+├── specification/   # Wiki 이관 전 스냅샷 (최신본은 Wiki)
+├── docs/            # decisions/(ADR), sessions/(자동) — 레포 보존
+├── backend/         # Rust 백엔드 코드
+├── frontend/        # Next.js 프론트엔드 코드
+├── .claude/         # 워크플로우 규칙 + 훅
+└── CLAUDE.md        # 이 파일
+```
 
 ---
 
@@ -70,7 +68,7 @@ service-for-small-business-taeyoon/
 | 프론트엔드 | Next.js 14 (TypeScript) + Tailwind + Zustand + TanStack Query |
 | 테스트 | cargo test + testcontainers + Vitest + Playwright + GitHub Actions CI |
 
-→ 결정 이유: `docs/decisions/20260607-initial-tech-stack.md`
+→ 상세: Wiki `Tech-Stack` 페이지 / 결정 이유: `docs/decisions/20260607-initial-tech-stack.md`
 
 ---
 
@@ -80,10 +78,11 @@ service-for-small-business-taeyoon/
 
 | 규칙 | 파일 |
 |------|------|
+| **GitHub 작업 흐름 (이슈/PR/Wiki)** | `.claude/github-workflow.md` |
 | 코드 수정 규칙 | `.claude/code-rules.md` |
 | 작업 완료 기준 (DoD) | `.claude/dod.md` |
 | 커밋 규칙 | `.claude/commit-rules.md` |
-| 테스트 안전망 | `specification/dev/harness.md` |
+| 테스트 안전망 | Wiki: `Harness` 페이지 (`specification/dev/harness.md` 스냅샷) |
 
 ---
 
@@ -102,7 +101,7 @@ cd frontend && npm run type-check && npm test -- --run
 ## 세션 마무리
 
 세션 마무리 시 `/wrap` 스킬 실행:
-- 변경된 스펙 문서 업데이트
-- `docs/works/YYYYMMDD-summary.md` 작성
+- 진행한 작업의 **PR 본문/이슈 코멘트** 정리 + 머지된 변경분 **Wiki 반영**
+- 변경된 스펙은 GitHub **Wiki** 해당 페이지 업데이트
 - 필요 시 ADR 작성 (`docs/decisions/`)
 - CLAUDE.md 업데이트