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>

README.md

@@ -74,17 +74,70 @@ cd flutter && cp .env.example .env && flutter pub get && flutter run
 ```jsonc
 // 성공
 { "success": true, "data": { /* ... */ } }
-// 실패
-{ "success": false, "error": { "code": "VAL_001", "message": "..." } }
+
+// 실패 — 사용자에게 보이는 모든 실패는 에러 코드를 가진다
+{ "success": false, "error": { "code": "VAL_001", "message": "...", "traceId": "3f1c0a2e-..." } }
+
+// 목록 — data 안의 형태가 고정되어 있다
+{ "success": true, "data": { "items": [], "pageInfo": { "hasNext": false, "nextCursor": null, "total": 0 } } }
 ```
 
-에러 코드 맵과 코딩 규칙 전문은 [`CLAUDE.md`](./CLAUDE.md) 및 `.claude/rules/`·`.claude/skills/` 의 규칙 문서를 참고하세요.
+`traceId` 는 요청마다 발급되는 추적 ID(`x-request-id` 헤더와 동일)로, 서버 로그에 같은 값이 남습니다.
+사용자 문의가 들어오면 이 값으로 로그를 검색하면 됩니다.
+
+> `/api/health` 는 예외입니다. 모니터링 도구가 읽는 엔드포인트라 래퍼 없이 원본 형식을 반환합니다.
+
+### 에러 코드는 한 곳에서 관리됩니다
+
+```
+backend/src/common/errors/error-codes.ts   ← 여기만 수정
+        │  cd backend && npm run sync:error-codes
+        ├─▶ frontend/src/shared/constants/error-codes.generated.ts   (자동 생성)
+        └─▶ flutter/lib/core/api/error_lexicon.g.dart                (자동 생성)
+```
+
+생성 파일은 직접 수정하지 마세요. CI 가 동기화 여부를 검사합니다.
+자세한 규칙은 [`.claude/rules/error-codes.md`](./.claude/rules/error-codes.md) 참조.
+
+## 로컬 개발 (Docker 없이)
+
+```bash
+# backend
+cd backend && npm ci && npm run start:dev
+
+# frontend
+cd frontend && npm ci && npm run dev
+
+# flutter
+cd flutter && flutter pub get && flutter run
+```
+
+### 커밋 전 검사
+
+```bash
+cd backend  && npm run lint && npm run test && npm run build
+cd frontend && npm run lint && npm run type-check && npm run test:unit
+cd flutter  && flutter analyze && flutter test
+```
+
+lint 는 `--max-warnings 0` 이라 경고 하나만 있어도 실패합니다. 자동 수정은 `npm run lint:fix`.
+같은 검사를 CI([`.github/workflows/ci.yml`](./.github/workflows/ci.yml))가 PR 마다 수행합니다.
+
+> ⚠️ **의존성을 추가·제거할 때는 컨테이너 안에서** 실행하세요.
+> Windows 에서 `npm install` 하면 Linux 전용 패키지가 lock 에서 잘려 Docker 빌드가 깨집니다.
+> ```bash
+> docker compose -f docker-compose.yml -f docker-compose.dev.yml --env-file .env.development exec backend npm install <패키지>
+> ```
 
 ## 개발 규칙
 
 | 영역      | 문서                                              |
 | --------- | ------------------------------------------------- |
 | 공통/보안 | [`CLAUDE.md`](./CLAUDE.md) · [`.claude/rules/`](./.claude/rules/) |
+| 응답·에러 | [`response-format.md`](./.claude/rules/response-format.md) · [`error-codes.md`](./.claude/rules/error-codes.md) |
+| API 설계  | [`api-design.md`](./.claude/rules/api-design.md)   |
+| 로깅      | [`logging.md`](./.claude/rules/logging.md)         |
+| 체크리스트 | [`checklist.md`](./.claude/rules/checklist.md)    |
 | NestJS    | [`.claude/skills/nestjs/SKILL.md`](./.claude/skills/nestjs/SKILL.md)   |
 | Vue 3     | [`.claude/skills/vue3/SKILL.md`](./.claude/skills/vue3/SKILL.md)       |
 | Flutter   | [`.claude/skills/flutter/SKILL.md`](./.claude/skills/flutter/SKILL.md) |
@@ -96,12 +149,15 @@ cd flutter && cp .env.example .env && flutter pub get && flutter run
 .
 ├── backend/    # NestJS API (Controller / Service / DTO / 공통 필터·인터셉터)
 ├── frontend/   # Vue 3 (pages / components / composables / stores / router)
-├── flutter/    # Flutter (core / features / widgets)
+├── flutter/    # Flutter (core / features / shared)
 ├── docker-compose.yml         # 베이스 정의
 ├── docker-compose.dev.yml     # 개발 오버라이드 (핫리로드, 포트 노출)
 ├── CLAUDE.md   # 프로젝트 개요 + 공통 규칙 @import
+├── .github/
+│   ├── workflows/ci.yml       # lint·test·build + 에러 코드 동기화 검사
+│   └── pull_request_template.md
 └── .claude/
     ├── settings.json   # Claude Code 권한·환경 설정
-    ├── rules/          # 공통 규칙 (코딩·응답 포맷·에러 코드·커밋·보안·환경변수)
+    ├── rules/          # 공통 규칙 (코딩·응답 포맷·에러 코드·API 설계·로깅·보안·환경변수·테스트)
     └── skills/         # 도메인별 개발 규칙 (nestjs·vue3·flutter·docker)
 ```