6.5 KiB
6.5 KiB
코딩 컨벤션
공통
- 시작 버전은
v0.0.1이다. - 문서와 사용자 응답은 한국어로 작성한다.
- 작업 보고, 릴리스 메모, 주요 문서 업데이트에는 항상 버전명을 함께 표시한다.
docs/update.md는 짧은 항목형으로 작성한다.docs/update.md는 서술형 문장보다~추가.,~수정.,~정리.,~진행.형식을 우선 사용한다.docs/update.md는 날짜가 아니라 버전 기준 섹션으로 구분한다.docs/update.md는 가장 최신 버전 섹션이 항상 맨 위에 오도록 유지한다.docs/history.md는 이유를 포함한 서술형 기록을 허용한다.docs/history.md는 가장 최신 항목이 항상 맨 위에 오도록 유지한다.docs/history.md제목에는 날짜와 버전을 함께 적는다.- JavaScript는 세미콜론 없이 현재 코드 스타일을 유지한다.
- 새 주석이 필요할 경우 JSDoc 형식을 사용한다.
- 경로, 주소, 운영 설정은 하드코딩보다 환경변수 기반 구성을 우선한다.
- 사이트 전역 기본 폰트는 항상
Pretendard를 우선 사용한다. - Git 커밋 메시지는 한국어로 작성한다.
- 로컬 Git 작성자 정보는 항상
zenn/zenn.message@gmail.com조합을 사용한다. - 버전 릴리스가 포함된 작업은
docs/update.md의 버전 표기와 Git 태그를 함께 맞춘다. - Git 푸시 전에는 민감 정보(실명, 개인 이메일, 비밀키, 로컬 절대 경로) 포함 여부를 다시 확인한다.
- 작업이 끝난 뒤에는 문서 업데이트까지 포함한 변경사항을 커밋하고 원격 저장소에 푸시한다.
Git 업로드 양식
- 작성자 정보 확인:
git config user.name/git config user.email - 작성자 정보 고정:
git config user.name "zenn"/git config user.email "zenn.message@gmail.com" - 작업 확인:
git status - 변경 스테이징:
git add -A - 커밋:
git commit -m "작업 목적을 한 줄로 설명하는 한국어 메시지" - 원격 푸시:
git push origin main - 푸시 후 확인:
git status,git log -1 --oneline
Git 커밋 메시지 규칙
- 한국어 한 줄 요약으로 작성한다.
- 가능하면
영역: 변경 내용형식을 사용한다. - 예시:
docs: Git 업로드 규칙 정리 - 예시:
app: 기본 Vite 레이아웃 초기 구현
버전 표기 규칙
- 작업이 끝나 커밋할 때마다 버전을 증가시킨다.
- 새 기능 시작, 구조 변경, 배포 준비, 작업 결과 보고 시 현재 버전을 함께 적는다.
- 형식은 항상
v0.0.1처럼v접두사를 포함한다. - 버전이 변경되면
docs/update.md,docs/spec.md,docs/history.md,docs/deploy.md에 함께 반영한다.
수정 범위 규칙
- 요청된 기능과 직접 관련 없는 코드는 수정하지 않는다.
- 기존에 정상 동작하는 로직은 리팩토링하지 않는다.
- 스타일 변경만으로 해결 가능한 경우 로직 수정 금지.
- 기존 API 구조를 임의로 변경하지 않는다.
환경 변수 및 설정 규칙
- API 주소, 파일 경로, 외부 서비스 URL은 반드시 환경변수로 관리한다.
- 코드 내에 직접 문자열로 작성하지 않는다.
- 예외적으로 테스트용 임시 값은 주석으로 명시한다.
로그 및 디버깅 규칙
- console.log는 디버깅 용도로만 사용한다.
- 작업 완료 시 불필요한 로그는 반드시 제거한다.
- 운영 환경에 영향을 줄 수 있는 로그는 추가하지 않는다.
프런트엔드
기본 구조
- API 호출은
src/lib/pocketBase.js및 관련 composable을 통해 통합한다. - 정적 파일 URL 조합은
toApiUrl()로 처리한다. - 화면 상태는
ref,computed,onMounted중심의 단순한 Composition API 패턴을 유지한다.
UI/UX 패턴
- 설정/계정과 같이 자주 변경되지 않는 정보는
현재 상태 요약 + 필요 시 모달 편집구조를 우선한다. - 모달이 활성화된 동안에는
body스크롤 잠금을 적용한다. - 배경 화면이 움직이지 않도록 한다.
- 정렬 가능한 리스트는 즉시 재렌더링으로 깜빡이지 않도록 한다.
TransitionGroup등을 사용해 이동 애니메이션을 적용한다.
스타일 (Tailwind + 구조 클래스)
- 기본 스타일링은 Tailwind CSS를 사용한다.
- Tailwind 유틸리티 클래스만으로 구조를 구성하지 않는다.
- 주요 영역에는 반드시 의미 있는 고유 클래스명을 함께 작성한다.
- 고유 클래스명은 개발자 도구에서 구조를 빠르게 파악하기 위한 용도로 사용한다.
- 클래스명은 컴포넌트 또는 역할 기준으로 명확하게 작성한다.
- 임시 이름 사용을 금지한다.
백엔드
기본 규칙
- 라우트 검증은
zod로 처리한다. - 인증/권한 분기는 PocketBase 세션·가드(
requireAuth등)로 분리한다.
데이터 처리
- DB 저장 전 배포 환경에 종속되는 값(예: 로컬 절대 URL)을 제거하거나 정규화한다.
- 사용자 입력 데이터는 반드시 검증 후 저장한다.
파일 업로드
- 업로드 파일명은 ASCII 안전 문자열을 사용한다.
- 관리자 데이터와 사용자 데이터는 업로드 경로를 분리한다.
기능 흐름
- 사용자 프로필과 같이 “선택 후 저장” 흐름이 필요한 기능은 파일 선택과 실제 저장 요청을 분리한다.
네이밍 규칙
- 변수명, 함수명, 클래스명은 의미가 명확하게 드러나야 한다.
- 축약어 남용을 금지한다.
- 임시 이름(
temp,data2,testFn,aaa) 사용을 금지한다. - 컴포넌트 이름은 역할 기반으로 작성한다.
파일 및 구조 규칙
- 파일 생성은 최소화한다.
- 기존 파일에서 해결 가능한지 먼저 검토한다.
- 사용하지 않는 코드(import, 함수, 스타일)는 반드시 제거한다.
- 파일은 하나의 책임을 가지도록 유지한다.
주석 규칙
- 주석은 필요한 경우에만 작성한다.
- 함수, 복잡한 로직에는 JSDoc 형식을 사용한다.
- 코드로 설명 가능한 내용은 주석으로 반복하지 않는다.
- 오래되면 잘못될 수 있는 주석은 작성하지 않는다.
검증 규칙
- 가능한 범위에서 기능 검증을 수행한다.
- 주요 사용자 흐름을 확인한다.
- 에러 발생 가능성이 있는 조건(null, undefined, 실패 응답 등)을 점검한다.
- 검증을 수행하지 못한 경우 그 사유를 명확히 남긴다.