ttipo
700a100a38
규칙과 구현이 어긋나 있던 부분을 바로잡고, 작업하며 발견한 함정을 기록한다.
- 스킬 문서의 "기본 제공 골격" 표를 실제 파일 목록과 일치시킴
- 커밋 전 체크리스트에 테스트 실행·에러 코드 동기화 절차 추가
- 커밋 규칙에 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>
2.4 KiB
2.4 KiB
name, description
| name | description |
|---|---|
| coding-common | 세 클라이언트(backend/frontend/flutter) 공통 코딩 규칙 — 주석 언어, 타입 정책, 린트, 순수 유틸 분리, 절대경로 alias. |
공통 코딩 규칙
- 모든 코드 주석은 한국어로 작성
- 웹(
frontend)·서버(backend)는 100% TypeScript, 모바일(flutter)은 Dart Sound Null Safety 준수 - 컴파일러/린터 Warning 방치 금지 — 커밋 전 각 프로젝트
lint/analyze통과 (lint 스크립트에--max-warnings 0이 걸려 있다. 자동 수정은npm run lint:fix) - 아래 규칙은 린트로 강제되므로 위반 시 빌드가 실패한다:
any/dynamic사용,console/print출력, Vue 인라인 스타일·Options API, Dartconst누락·await 누락, backend 에서HttpException직접 생성(→BusinessException사용) - 유틸 함수는 순수 함수로 분리 — TS는
shared/utils/, Dart는core/utils/ - 매직 넘버·하드코딩 문자열 지양 → 상수 또는 환경변수로 분리
(반복 사용되는 키 문자열도 상수로: 예
kJwtTokenKey,REQUEST_ID_HEADER) - 절대경로 alias 사용 (TS
@/, Dartpackage:), 깊은 상대경로(../../) 지양 — backend/frontend 모두@/→src/로 설정되어 있다 (backend 는tsconfig.jsonpaths + jestmoduleNameMapper) - 자동 생성 파일은 직접 수정하지 않는다 —
*.generated.ts,*.g.dart는 생성 스크립트를 통해서만 바꾼다 (error-codes)
네이밍 규약
| 대상 | 규칙 | 예 |
|---|---|---|
| TS 파일(일반) | kebab-case | user.store.ts, use-api.ts / 기존 composable 은 useApi.ts 형태 유지 |
| Vue 컴포넌트 파일 | PascalCase | BaseButton.vue, UserCard.vue |
| Dart 파일·디렉터리 | snake_case | dio_client.dart, user_repository.dart |
| 클래스/타입 | PascalCase | UserModel, TransformInterceptor |
| 변수/함수 | camelCase (Dart 포함) | getUser, isLoggedIn |
| 상수 | TS UPPER_SNAKE 또는 모듈 상수, Dart lowerCamel |
MAX_RETRY, defaultTimeout |
| 에러 코드 | DOMAIN_NNN |
AUTH_001, VAL_001 (error-codes) |
| 자동 생성 파일 | TS *.generated.ts, Dart *.g.dart |
error-codes.generated.ts, error_lexicon.g.dart |
도메인별 세부 규칙: nestjs · vue3 · flutter · 테스트: testing · 로깅: logging · API 설계: api-design