docs: 규칙 문서를 실제 구현에 맞춰 갱신

규칙과 구현이 어긋나 있던 부분을 바로잡고, 작업하며 발견한 함정을 기록한다.

- 스킬 문서의 "기본 제공 골격" 표를 실제 파일 목록과 일치시킴
- 커밋 전 체크리스트에 테스트 실행·에러 코드 동기화 절차 추가
- 커밋 규칙에 scope·브랜치 전략·PR 규칙 보강
- 새 규칙 파일(api-design, logging)을 CLAUDE.md import 목록에 등록하고,
  규칙 추가 시 등록이 필수라는 메타 규칙 명시
- README 를 현재 구조에 맞게 갱신 (traceId·페이지네이션·에러 코드 SSOT·로컬 개발 명령)

작업 중 실제로 겪은 함정들을 규칙으로 남긴다:
- Windows 에서 npm install 하면 Linux 전용 optional 의존성이 lock 에서 잘려
  Docker 의 npm ci 가 실패한다 → 의존성 변경은 컨테이너 안에서 수행
- --build 만으로는 node_modules 익명 볼륨이 갱신되지 않아
  새 패키지가 컨테이너에 반영되지 않는다 → --renew-anon-volumes 필요
- compose 는 미정의 변수를 빈 문자열로 주입해 Number('')===0 함정이 생긴다
- dev 는 PID 1 이 npm 이라 graceful shutdown 확인은 운영 이미지로 해야 한다
- Redis 는 컨테이너만 떠 있고 사용처가 없다 — 확장 지점임을 명시

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

.claude/skills/vue3/SKILL.md

@@ -5,7 +5,7 @@ description: Vue 3 프론트엔드(frontend/) 개발 규칙 — Composition API
 
 > 이 스킬은 `.claude/skills/vue3/SKILL.md`에 위치한다.
 > 사용법: `/vue3 [요청 내용]` 또는 frontend/ 작업 시 자동 적용.
-> 공통 규칙: [[response-format]] · [[error-codes]] · [[security]] · [[coding-common]]
+> 공통 규칙: [[response-format]] · [[error-codes]] · [[api-design]] · [[security]] · [[coding-common]]
 
 ---
 
@@ -16,8 +16,10 @@ description: Vue 3 프론트엔드(frontend/) 개발 규칙 — Composition API
 | 제공 항목 | 위치 | 비고 |
 | --- | --- | --- |
 | 중앙 Axios 인스턴스 | `src/composables/useApi.ts` | baseURL=`VITE_API_BASE_URL`, `withCredentials` |
-| 응답 언래핑 인터셉터 | `useApi.ts` | `{success,data}→data`, 에러 코드 처리 |
-| ErrorCodeLexicon | `useApi.ts` 내부 | 에러 코드 → 한국어 메시지 ([[error-codes]]) |
+| 응답 언래핑 인터셉터 | `useApi.ts` | `{success,data}→data`, 에러 코드 정규화(`ApiError`), 중복 알림 억제 |
+| 에러 코드 사전 | `src/shared/constants/error-codes.generated.ts` | **자동 생성 파일 — 직접 수정 금지** ([[error-codes]]) |
+| 세션 만료 처리 | `useApi.ts` 의 `toAuthCode()` | 로그인 상태에서 401 → `AUTH_002` 승격 + `authStore.clearAuth()` |
+| 페이지네이션 타입 | `src/shared/types/pagination.ts` | 목록 응답 공유 계약 ([[response-format]]) |
 | 도메인 Composable 예제 | `src/composables/useUser.ts` | 새 도메인 API 패턴 참고 |
 | 인증 Composable 예제 | `src/composables/useAuth.ts` | 로그인/로그아웃 흐름(쿠키 기반) 시작점 |
 | Pinia 스토어 예제 | `src/stores/user.store.ts` | 새 스토어 패턴 참고 |
@@ -112,23 +114,33 @@ export const useUserStore = defineStore('user', () => {
 ## API 호출 (Composables + Axios)
 
 ```typescript
-// composables/useApi.ts — 중앙 Axios 인스턴스
+// composables/useApi.ts — 중앙 Axios 인스턴스 (구조 요약)
 const api = axios.create({
   baseURL: import.meta.env.VITE_API_BASE_URL || '/api', // env.d.ts 에 타입 선언
   withCredentials: true, // HttpOnly 쿠키 전송
 })
 
 // 응답 인터셉터 — 표준 응답 언래핑 + 에러 코드 전역 처리
-api.interceptors.response.use(
-  (response) => response.data.data, // { success, data } → data 언래핑
-  (error) => {
-    const code = error.response?.data?.error?.code
-    // 에러 코드별 Toast 알림 처리 ([[error-codes]] 참조)
-    return Promise.reject(error)
-  },
-)
+// 실패 시 ApiError { code, message, traceId, status } 로 정규화해 reject 한다.
+// 문구는 생성된 사전에서만 오고, 같은 코드의 알림은 중복 억제된다.
 ```
 
+에러 처리 규칙:
+
+- **개별 `try/catch` 에서 메시지를 만들지 않는다.** 알림은 인터셉터가 이미 처리했다.
+- 호출부에서 분기가 필요하면 `message` 가 아니라 **`code` 로 분기**한다.
+
+```typescript
+try {
+  await api.post('/users', payload)
+} catch (e) {
+  const error = e as ApiError
+  if (error.code === 'USER_001') focusEmailField()
+}
+```
+
+- Toast 라이브러리를 도입하면 `useApi.ts` 의 `showErrorUI()` **한 함수만** 교체한다.
+
 ```typescript
 // composables/useUser.ts — 도메인별 API Composable
 export function useUser() {
@@ -194,10 +206,13 @@ router.beforeEach((to) => {
 (전체 확장 지점·점검 목록은 [[checklist]])
 
 - [ ] **API 호출**: 컴포넌트에서 `axios` 직접 호출 금지 → `composables/` 경유.
-- [ ] **에러 처리**: 개별 try/catch 로 메시지를 만들지 말고 `useApi` 인터셉터 + [[error-codes]] 에 위임.
+- [ ] **에러 처리**: 개별 try/catch 로 메시지를 만들지 말고 `useApi` 인터셉터 + [[error-codes]] 에 위임. 분기는 `error.code` 로.
+- [ ] **에러 사전**: `error-codes.generated.ts` 직접 수정 금지 — 백엔드 레지스트리 수정 후 `npm run sync:error-codes`.
+- [ ] **목록 화면**: 응답은 `{items, pageInfo}` — `shared/types/pagination.ts` 타입 사용.
 - [ ] **컴포넌트**: `<script setup lang="ts">` + `<style scoped>` + rem 단위. 인라인 스타일·Options API 금지.
 - [ ] **타입**: Props/Emits 는 인터페이스로 정의.
 - [ ] **라우트**: 페이지는 lazy import, 보호 라우트는 `meta.requiresAuth`.
-- [ ] **auth 가드(인증 도입 시)**: `router/index.ts` 의 `TODO` — `auth.store.ts` 작성 후 `isLoggedIn` 검사 연결.
-- [ ] **lint**: 커밋 전 `npm run lint` + `npm run type-check` 통과.
+- [ ] **auth 가드**: `router/index.ts` 가드는 `auth.store.ts` 의 `isLoggedIn` 과 이미 연결되어 있다. 로그인 페이지 추가 시 리다이렉트 대상을 `{ name: 'login' }` 으로 바꾼다.
+- [ ] **lint/test**: 커밋 전 `npm run lint` (`--max-warnings 0`) + `npm run type-check` + `npm run test:unit` 통과. 자동 수정은 `npm run lint:fix`.
+- [ ] **린트로 강제되는 항목**: Options API·인라인 스타일·`console`·`any` 는 빌드가 실패한다.
 - [ ] **env**: `VITE_API_BASE_URL` 은 빌드 시 루트 `BACKEND_API_URL` 에서 주입된다 — `frontend/.env` 에 별도 작성 불필요.